AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆【免费下载链接】OperitThe most powerful AI agent and AI chat software on Android/Operit是一款Android上能力最为强大、发展最久的AI Agent项目地址https://gitcode.com/gh_mirrors/op/Operit点击查看免费下载导读本文讲解 Operit 针对 Issue 858「远程 MCP 工具参数完整性」问题的完整修复方案当模型流式生成的工具参数在 UTF-8 解码过程中产生替换字符UFFFD时如何在 MCP 调用离开应用之前将其拦截避免远程写入工具静默持久化损坏文本。读完本文你将理解损坏产生的数据链路、MCPToolExecutor.validateParameters的校验实现细节、UTF-8 字节偏移的精确计算方法以及日志与错误信息如何做到「可定位、不泄露原始内容」。问题背景约 7.8 KB 处的静默数据损坏现象与现场定位在 Operit 的实际运行中远程 MCP 写入工具收到的长文本参数会在约 7.8 KB 的 UTF-8 字节偏移处出现UFFFDUnicode 替换字符。这一现象意味着原始字节流在解码时已经发生了不可逆的损坏替换字符是解码器对无法识别的字节序列给出的替代标记。关键排查结论见 index.md调用方已在MCP 服务入口确认损坏数据在服务端业务代码之前到达即问题发生在客户端发出请求之前或传输链路上而非服务端自身处理所致RemoteMcpRuntimeSession将结构化参数直接交给 Kotlin MCP SDKSDK 以完整 JSON 字符串交给 Ktor 请求体中途没有截断或重新编码项目中唯一的 8 KB 缓冲用于MCP ZIP 下载与工具调用链路无关可以排除「下载缓冲污染参数」的猜测模型流式工具参数在此之前已被转换为字符串——原始字符一旦变成替换字符应用端便无法恢复其真实内容。为什么「重试」无法修复由于UFFFD意味着原始字节已经丢失应用无法推断出原始内容。此时如果只是简单地重试调用模型或调用方仍会携带同样的损坏参数再次发起请求远程写入工具会再次触发一次写入把损坏文本继续静默持久化到服务端。因此重试不能作为数据修复手段必须在请求发出前就将其拒绝。修复目标与作用域修复的核心目标非常明确同样记录在 index.md在 MCP 调用离开应用前拒绝包含UFFFD的参数避免远程写入工具静默持久化损坏文本错误与日志只报告参数名、替换字符数量和偏移不记录原始参数内容。作用域限定在MCPToolExecutor.kt核心实现docs/TODO/issue-858-mcp-tool-argument-integrity/目录下的排查与完成记录即本文所依据的 01-block-corrupted-arguments.md实现分析MCPToolExecutor 的完整性校验替换字符的常量定义实现位于 MCPToolExecutor.kt执行器在companion object中定义校验所需的常量和违规描述结构companion object { private const val TAG MCPToolExecutor private const val REPLACEMENT_CHARACTER \uFFFD } private data class ArgumentIntegrityViolation( val parameterName: String, val replacementCharacterCount: Int, val characterOffset: Int, val utf8ByteOffset: Int )ArgumentIntegrityViolation是一次校验失败的结构化描述包含四个字段字段含义parameterName出现损坏的参数名仅名称不含值replacementCharacterCount该参数值中UFFFD的总数量characterOffset首个替换字符的字符偏移以 Kotlin 字符串索引计utf8ByteOffset首个替换字符前的子串按 UTF-8 编码后的字节数校验主入口validateParametersoverride fun validateParameters(tool: AITool): ToolValidationResult { // 验证工具名称格式 val toolNameParts tool.name.split(:) if (toolNameParts.size 2) { return ToolValidationResult( valid false, errorMessage Invalid MCP tool name format, should be server_name:tool_name ) } findArgumentIntegrityViolation(tool)?.let { violation - // UFFFD means the original argument bytes have already been lost. Sending a write // request would silently persist corrupted user content on the remote MCP server. AppLogger.e( TAG, Blocked MCP tool call with corrupted argument: tool${tool.name}, parameter${violation.parameterName}, replacementCount${violation.replacementCharacterCount}, characterOffset${violation.characterOffset}, utf8ByteOffset${violation.utf8ByteOffset} ) return ToolValidationResult( valid false, errorMessage MCP tool argument ${violation.parameterName} contains ${violation.replacementCharacterCount} invalid UTF-8 replacement character(s) (UFFFD); the call was blocked before it reached the MCP server. First UTF-8 byte offset: violation.utf8ByteOffset ) } return ToolValidationResult(valid true) }这段代码体现了两个设计要点拦截时机正确参数校验发生在invoke内部任何连接与调用动作之前详见下文调用链分析因此被拒的请求不会触发会话创建也不会到达远程服务信息最小化原则无论是AppLogger.e的日志还是返回给调用方的errorMessage都只包含参数名、替换字符数量、字符偏移、UTF-8 字节偏移绝不包含参数值本身——因为损坏的原始内容既无保留价值也避免在日志中泄露用户文本。核心查找逻辑findArgumentIntegrityViolationprivate fun findArgumentIntegrityViolation(tool: AITool): ArgumentIntegrityViolation? { val parameter tool.parameters.firstOrNull { it.value.contains(REPLACEMENT_CHARACTER) } ?: return null val characterOffset parameter.value.indexOf(REPLACEMENT_CHARACTER) val utf8ByteOffset parameter.value .substring(0, characterOffset) .toByteArray(Charsets.UTF_8) .size return ArgumentIntegrityViolation( parameterName parameter.name, replacementCharacterCount parameter.value.count { it REPLACEMENT_CHARACTER }, characterOffset characterOffset, utf8ByteOffset utf8ByteOffset ) }逐行拆解firstOrNull { it.value.contains(REPLACEMENT_CHARACTER) }遍历tool.parameters找出第一个包含UFFFD的参数一个都没有则返回null表示校验通过characterOffset通过indexOf得到首个替换字符在字符串中的字符位置注意是字符索引不是字节索引utf8ByteOffset取该字符之前的所有字符substring(0, characterOffset)再toByteArray(Charsets.UTF_8).size得到这些字符按 UTF-8 编码后的字节数——这正是复现报告中「约 7.8 KB UTF-8 字节偏移」所指的度量方式说明这个偏移是可以与传输层字节位置直接对标的定位依据replacementCharacterCount用count { it REPLACEMENT_CHARACTER }统计整个参数值中替换字符的总数帮助判断损坏的严重程度。由于该查找逻辑只做纯字符串检查不产生网络请求、不解析复杂结构其执行成本可以忽略适合放在所有 MCP 调用的必经入口上。校验在调用链中的位置为什么能「阻止会话创建」修复文档明确要求验证失败时不创建或调用远程 MCP 会话。这一点由执行器内部的方法调用顺序保证也由上层调用方保证。从 MCPToolExecutor.kt 的invoke实现看参数校验并不发生在invoke内部而是由上层工具执行框架在invoke之前统一完成ToolExecutionManager.kt 的executeToolSafely首先调用executor.validateParameters(invocation.tool)若validationResult.valid false直接发射一个失败ToolResult根本不会进入executor.invokeAndStreamAIToolHandler.kt 与 AIToolHandler.kt 同样在调用执行器之前先做validateParameters检查而invoke内部要执行的动作依次是mcpManager.getOrCreateSession(serverName)创建或复用会话→mcpClient.isActive()→mcpClient.callTool(...)。因此完整的保护时序是executeToolSafely / AIToolHandler │ ▼ validateParameters(tool) ← UFFFD 在此被拦截返回 validfalse │ (valid 才继续) ▼ MCPToolExecutor.invoke │ ▼ getOrCreateSession(serverName) ← 不创建会话、不发起连接 │ ▼ RemoteMcpRuntimeSession.callTool ← 不向远程服务发送任何数据这正是 01-block-corrupted-arguments.md 中「通过代码路径审阅确认参数验证发生在getOrCreateSession与callTool之前」的源码依据。底层链路佐证参数是如何走向远程服务的要理解为什么必须在入口拦截需要看清参数离开应用前的最后一段旅程。远程会话实现位于 RemoteMcpRuntimeSession.kt其关键特征会话基于Kotlin MCP SDK 的Client与KtorHttpClient(OkHttp)构建支持两种传输httpStreamStreamableHttpClientTransport与sseSseClientTransport连接超时 15 秒、请求/套接字超时 60 秒RemoteMcpRuntimeSession.kt连接成功后callTool直接把arguments: MapString, Any?交给 SDK 的client.callTool(name, arguments)RemoteMcpRuntimeSession.ktSDK 会将结构化参数序列化为完整 JSON 字符串放入 Ktor 请求体——也就是说任何参数中携带的UFFFD都会原样进入 HTTP 请求直抵远程服务端。同时在调用前MCPToolExecutor.kt 的convertParameterTypes会结合工具定义的inputSchema.properties[param].type对参数做智能类型转换MCPToolParameter.smartConvert支持 number/boolean/integer/float/double/array/object 及未指定类型时的智能猜测但转换过程不会修复已经存在的替换字符——它只负责类型形态不负责字符完整性。因此可以明确结论一旦替换字符进入参数唯一的止损点就是validateParameters这道闸门放行之后损坏文本将不可恢复地流向远程写入工具并被静默持久化。错误信息与日志设计可定位、不泄露修复目标中「错误与日志只报告参数名、替换字符数量和偏移不记录原始参数内容」有两层工程意义可定位utf8ByteOffset字节偏移与characterOffset字符偏移能让开发者把损坏位置映射到传输层的字节位置与「约 7.8 KB 处出现 UFFFD」这类现场报告直接对标便于复现与排查不泄露被拦截时日志输出的是parameterxxx, replacementCountN, characterOffsetN, utf8ByteOffsetN这样的结构化元数据错误信息同样只包含参数名与偏移量避免了把用户私有文本写入日志文件或在 UI 中回显。用户侧最终会收到形如下方的失败信息由ToolExecutionManager.executeToolSafely包装为Invalid parameters: ...MCP tool argument 参数名 contains N invalid UTF-8 replacement character(s) (UFFFD); the call was blocked before it reached the MCP server. First UTF-8 byte offset: 偏移验证方式与完成状态按照仓库执行准则本次修复未运行构建或测试完成性验证通过代码路径审阅确认参数验证发生在getOrCreateSession与callTool之前01-block-corrupted-arguments.md 标注为[DONE]旧实现仅校验工具名格式、任何参数都放行已在 MCPToolExecutor.kt 中被新的完整性校验取代。后续若需进一步验证可从以下角度补充测试构造包含UFFFD的长文本参数模拟约 7.8 KB 场景、断言validateParameters返回validfalse、断言错误信息不含参数原始值、断言会话连接与callTool均未被触发。小结Operit 针对 Issue 858 的修复本质上是在「模型流式参数 → 字符串 → 远程 MCP 请求」的不可逆链路上于最后一道可控闸门处阻断不可恢复的损坏数据入口拦截validateParameters在getOrCreateSession与callTool之前完成UFFFD扫描失败时既不创建会话也不发请求精确度量同时报告字符偏移与 UTF-8 字节偏移与传输层字节位置可对标最小化泄露日志与错误只含参数名、数量和偏移不含原始内容明确止损替换字符意味着原始字节已丢失重试只会再次触发远程写入拒绝而非重试才是正确策略。这套模式对任何「客户端流式生成参数 远端持久化写入」的架构都具有参考价值在数据不可逆地离开进程边界之前对解码标记类异常做结构性校验是防止脏数据静默落盘的最后一层防线。赞分享AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆【免费下载链接】OperitThe most powerful AI agent and AI chat software on Android/Operit是一款Android上能力最为强大、发展最久的AI Agent项目地址https://gitcode.com/gh_mirrors/op/Operit点击查看免费下载相关推荐终极指南ScyllaDB如何防止数据损坏的核心机制终极指南ScyllaDB如何防止数据损坏的核心机制 ScyllaDB是一个高性能、高度可扩展的NoSQL数据库设计上兼容Cassandra API主打低延数据库分布式数据库后端大数据GB28181 视频监控平台实战教程Docker 一键部署 海康摄像头接入全流程GB28181 视频监控平台实战教程Docker 一键部署 海康摄像头接入全流程 小区要装 20 路摄像头找集成商报价十几万自己又搞不定信令对接WV后端音视频前端RestSharp 拦截器Interceptor完整指南在请求发送前后拦截、修改与取消 HTTP 调用RestSharp 拦截器Interceptor完整指南在请求发送前后拦截、修改与取消 HTTP 调用 RestSharp 的 Interceptors后端API设计上一篇CSS Grid Generator状态管理Vuex在项目中的应用下一篇AntiDBG实战指南10大核心反调试技巧轻松掌握创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考