后端MCP 服务MCP ClientsAI Agent人工智能【免费下载链接】mcp-useThe fullstack MCP framework to develop MCP Apps for ChatGPT / Claude MCP Servers for AI Agents.项目地址https://gitcode.com/gh_mirrors/mc/mcp-use点击查看免费下载本篇指南以 mcp-use 项目内置的 mcp-builder 技能验证规范为主体系统讲解在完成 TypeScript MCP Server 或 MCP AppsViews开发后如何分层执行验证先做最小化的静态检查证明目标行为再随改动波及面生成类型、认证、Views、包边界、并发逐级扩大验证范围。读完本文你将掌握mcp-use typecheck、mcp-use client、mcp-use screenshot等核心验证命令的用法与底层原理以及工具、资源、Prompt、View、Skills、通知、Elicitation、OpenAPI/代理、打包等各类改动的针对性验证清单。验证的总体原则先最小再按风险扩展验证不是把命令跑一遍而是运行能证明目标行为的最小检查然后按风险扩展。mcp-builder 技能在 verification.md 中给出的核心准则是Run the smallest checks that prove the requested behavior, then expand for changes involving generated types, authentication, Views, package boundaries, or concurrency.翻译过来就是改动越大、越靠近系统边界验证就要越完整。涉及生成的类型mcp-env.d.ts、认证authentication、Views交互式界面、包边界package exports/发布产物、并发concurrency/取消的改动必须从最小检查扩展到真实的生命周期验证。这与技能总纲 SKILL.md 中Validate the smallest real lifecycle that proves the changed behavior, then expand checks in proportion to risk的指导一脉相承。静态检查typecheck 与 build 的正确分工静态检查是验证的第一步使用项目自身的包管理器和脚本即可。对一个典型项目npx mcp-use typecheck npm run typecheck npm run build有两个容易踩的坑需要特别说明不要假设每个项目都同时定义了npx mcp-use typecheck和npm run typecheck。前者是 mcp-use CLI 提供的类型检查命令后者是项目在package.json中自带的脚本二者不是一回事需要以实际项目的package.json为准。mcp-use build做的是打包与转译bundling/transpiling不能替代类型检查。它可能成功通过但类型错误依然存在。因此交付前必须把新增的类型错误、lint 错误、包边界错误和生成注册表generated registry错误全部解决。mcp-use typecheck的底层原理从源码看mcp-use typecheck并不是简单地调用tsc。它的实现位于 cli/typecheck.ts完整流程是发现服务入口通过discoverEntry定位项目的 server entry如src/index.ts同步mcp-env.d.ts调用 mcp-env-declaration.ts 中的syncMcpEnvDeclaration刷新根目录的环境声明文件运行项目本地 TypeScript解析项目自身的typescript包并执行tsc --noEmit禁掉产物输出只做类型检查。mcp-env.d.ts是这套体系的关键。它由 mcp-use 生成文件头是// Generated by mcp-use. Do not edit.内容把 server entry 导出到mcp-use/react模块的Register接口上import mcp-use/vite-client; declare module mcp-use/react { interface Register { tools: typeof import(./src/index.js); } } export {};这样 View 代码里的useCallTool(add)就能获得与 server entry 导出 ToolRef 一致的类型推断。syncMcpEnvDeclaration遵循三条安全规则可刷新带 mcp-use 生成头包括历史版本头的文件会被自动更新用户拥有没有生成头的文件被视作用户自建绝不覆盖命令行会输出mcp-env.d.ts is user-owned; leaving it unchanged警告并发安全用独占创建exclusive creation保证多个命令同时启动时不会互相覆盖。由于tsc在项目干净时不会打印任何内容typecheck 在退出码为 0 时会额外输出一行成功信息[mcp-use] no type errors (Xms)用于区分通过与卡死。对应的测试见 tests/cli/typecheck.test.ts其中验证了三个关键行为先创建mcp-env.d.ts再让tsc检查未导出的 ToolRef能正确报出add is registered but its ToolRef is not exported、项目干净时输出成功行、tsc报错时保持静默。Server 与能力检查连真实端点驱动真实能力静态检查通过后需要启动真实的开发服务器通过其公开的 MCP 端点连接并驱动被改动的能力npm run dev npx mcp-use client connect dev http://localhost:3000/mcp npx mcp-use client dev tools list npx mcp-use client dev tools call lookup-inventory skuitem-1npm run dev对应 mcp-use CLI 的dev命令入口见 commands/dev.ts它会启动带 HMR 的开发服务器并接管 listener 与 View 渲染管线。mcp-use client则是连接并驱动 MCP 端点的命令行客户端实现在 commands/client.ts。client connect把端点保存为命名服务器client connect name url会把连接信息保存到全局状态servers.json后续所有验证命令都能用名称引用npx mcp-use client connect dev http://localhost:3000/mcp几个常用选项与约束-H Key: Value附加请求头可重复--protocol auto|legacy|modern协议协商方式默认autolegacy固定使用2025-11-25协议版本modern固定使用2026-07-28stateless/sessionless无回退--no-oauth跳过 OAuth 发现默认开启 OAuth 交互名称需满足 1-64 位、由字母数字及.-_组成、以字母数字开头。连接失败时CLI 还会对错误信息做脱敏处理redact把 URL 中的用户名密码、查询参数、hash 以及Bearertoken 等机密替换为[REDACTED]避免验证过程中的敏感信息泄漏到日志见 client.ts。按能力类型分层验证保存连接后mcp-use client name下挂着一组子命令按被改动的能力选择能力验证命令验证要点工具client dev tools list/client dev tools describe tool/client dev tools call tool [args]有效输入、schema 拒绝、预期失败、structuredContent与 schema 匹配资源client dev resources list/client dev resources read uri静态 URI 与模板 URI 均可读取并练习 completion补全建议提示client dev prompts list/client dev prompts get prompt [args]检查生成的消息与建议是否精确符合预期认证/取消client dev auth login/auth status/auth logout被改动的授权与取消路径tools call支持两种参数语法keyvalue形式的普通值或key:json形式的类型化 JSON 值也可以传一个完整的 JSON 对象调用超时默认 30 秒可用--timeout调整。这一参数解析逻辑实现在 client.ts。关于工具验证还有一条来自 server 规范的硬性要求见 server.md工具回调不能返回裸业务对象必须返回 MCP 结果信封——模型可读的摘要放contentschema 校验过的 JSON 放structuredContent只有 View 可见的调用期数据放_meta预期操作失败返回isError: true并附上有用的content只有意外失败才抛出异常表现为协议错误。View 检查在 Inspector 中渲染真实界面改动涉及 Views 时必须通过其绑定的工具在 Inspector 中渲染每一个受影响的 View逐项核对渲染状态pending加载中、ready就绪、error出错三种状态的表现交互链路View 到工具的回调view-to-tool calls与宿主动作host actions状态分层模型可见状态useViewState/ModelContext与临时的、仅 UI 可见的 ephemeral 状态React state是否正确分离呈现细节主题、尺寸、支持的展示模式display modes、可访问性accessibility资源与外联公共资源public assets、外部请求、CORS、运行时错误、CSP。这里尤其强调一点不要用tools call的某个 flag 来代替截图。捕获真实 View 必须用专门的截图命令npx mcp-use screenshot --server dev --tool show-product iditem-1screenshot 命令的完整参数与执行流程screenshot命令的实现见 commands/screenshot.ts它会调用一个 View 绑定的工具并把渲染出的 MCP App 捕获为 PNG。常用选项--server name使用mcp-use client保存的服务器--mcp url直接连接 HTTP(S) 端点二者必须二选一-H头仅对--mcp有效--tool name要调用的 View 绑定工具必填--output path输出 PNG 路径默认是时间戳命名的视图名--width px宿主/widget 宽度默认 768对齐 OpenAI 内联 MCP App 容器--height px响应式布局用视口高度默认 720PNG 最终按 widget 边界裁剪--device-scale-factor n像素密度必须大于 0 且不超过 4默认 1--theme light|dark宿主主题默认 light--wait-for selector等待指定选择器出现后再捕获--delay ms就绪后的附加延迟--timeout ms工具/浏览器超时默认 30000--inspector url/--cdp-url url复用已有 Inspector 或 Chrome DevTools 端点--json输出单条 JSON 结果或错误绝不交互提示。其底层执行流程对应代码中的runScreenshot大致是连接 →listTools找到目标工具 → 解析参数并callTool→ 从工具_meta.ui.resourceUri读取 View 的 HTML 资源 → 启动或连接 Inspector 并做健康检查协议必须为mcp-use-inspector-previewv1支持view-preview能力→ 启动 headless Chrome通过 CDP 协议连接→ 注入工具输入/输出 bundle → 导航到预览页 → 轮询document.body.dataset.viewReady等待就绪 → 读取渲染 iframe 的边界 → 按 widget 边界裁剪出 PNG。两个值得注意的实现细节就绪判定只认view_load_failed只有 MCP App 显式初始化失败坏资源、沙箱连接失败、握手失败、缺少截图 bundle才会让截图失败widget 自身初始化成功后的console.error、未捕获异常或未处理的 promise rejection不会导致捕获失败相关判定函数readyStateFailure及其测试见 tests/commands/screenshot.test.ts。浏览器查找依次检查环境变量MCP_USE_CHROME_PATH、PUPPETEER_EXECUTABLE_PATH、CHROME_PATH再按平台探测 Chrome/Chromium/Brave/Edge 的常见安装路径找不到时抛出chrome_not_found并提示设置MCP_USE_CHROME_PATH。View 侧的验证还涉及 CSP 声明详见 views.md精确声明外部来源——connectDomainsfetch/EventSource/WebSocket、resourceDomains脚本/样式/图片/字体/媒体、frameDomains嵌入帧、baseUriDomains仅在确实需要外部 base URI 时。验证时确认外部请求与 CORS 行为符合这些声明。高级与打包检查按特性逐项验证对于涉及高级特性的改动verification 文档给出了逐项的验证要点Skills over MCP验证目录查看目录清单catalog→ 检索 Skillskills/get→ 读取其支撑文件 → 跑一次严格的生产构建。注意mcp-use dev与mcp-use build对无效 Skill 的处理不同见 skills-over-mcp.mddev 模式会记录并跳过无效 Skill 直到修复而build 是严格模式目录无效会直接失败并把校验过的快照嵌入生产构建产物——所以跑一次严格的生产构建是 Skills 改动的必做项。通知Notifications保持一个监听者listener处于活跃状态确认**非持久失效non-durable invalidation**行为符合预期。mcp-use 的通知是请求作用域的见 advanced-features.mdctx.sendNotification/ctx.reportProgress/ctx.sendLog只能在回调活跃期间发送且必须在返回前await它们不是响应后的广播通道reportProgress()在调用方未提供进度 token 时返回false。跨请求的失效通过server.notifyToolsChanged()、notifyPromptsChanged()、notifyResourcesChanged()、notifyResourceUpdated(uri)发布只推送给有活跃订阅监听者的客户端且不能依赖每条事件都送达——资源/注册表本身才是权威来源。Elicitation引导式交互覆盖测试required必填、accept接受、decline拒绝、cancel取消、无效输入、回调重放callback replay与副作用顺序side-effect ordering。核心准则是见 advanced-features.md回调在 input-required 轮次会重新执行因此不可逆副作用只能在 accepted 输入之后执行每个问题使用独立稳定的 key对裸输入响应做校验涉及授权或业务逻辑连续性时使用已验证的请求状态绝不在表单引导中收集密码、API Key、支付信息或 OAuth 密钥。代理与 OpenAPI验证有代表性的生成能力与文档明确标注的不支持边界。OpenAPI 生成MCPServer.fromOpenAPI()已知边界包括cookie 参数与非 JSON 请求体不暴露、生成工具不从响应定义推导outputSchema代理server.proxy()需要可选包mcp-use/client、不运行交互式 OAuthtoken 与 header 必须显式提供且不能假定资源模板、completions、订阅、上游列表重同步等每个能力都被转发详见 advanced-features.md。导出、依赖与打包把包打包pack后在空的临时消费者目录中安装并验证。工作区构建workspace build无法证明发布后的边界——它可能隐式引用了未在package.jsonexports 中声明的模块或依赖了工作区中恰好存在的传递依赖。空目录安装是唯一能验证别人拿到发布产物能否正常使用的方式。验证的边界不要为了验证而部署最后一条原则同样重要不要仅仅为了验证源码改动而部署。如果用户没有要求部署就验证本地构建产物并明确说明未测试的外部边界untested external boundary。这是事实准确在验证环节的体现——本地验证通过只能证明本地行为不能声称生产环境同样成立任何关于线上行为、外部系统兼容性的结论都要以实际部署验证为准否则应在交付说明中如实标注。小结一张验证清单把以上内容浓缩为可执行的检查清单静态npx mcp-use typecheck或项目的 typecheck 脚本通过mcp-use build打包成功——但记住 build 不等于 typecheckServernpm run dev启动 →mcp-use client connect→ 用tools list/tools call、resources read、prompts get驱动每个被改动的能力覆盖有效输入、schema 拒绝、预期失败与structuredContent匹配View在 Inspector 中经绑定工具渲染每个受影响 View核对三态渲染、交互链路、状态分层、主题/尺寸/展示模式/无障碍、外部请求与 CSP用mcp-use screenshot捕获真实截图高级按 Skills、Notifications、Elicitation、OpenAPI/代理、打包的各自要点逐项验证尤其 elicitation 的重放与副作用顺序、打包的空目录安装边界未请求部署就不部署交付时说明未测试的外部边界。验证的深度始终与改动的风险成正比改一个工具的描述最小检查就足够改动生成的类型、认证、Views、包边界或并发路径就必须走到端到端的真实生命周期验证。这套规范同时内嵌于 mcp-builder 技能的工作流中是 mcp-use 生态中开发与交付 TypeScript MCP Server / MCP Apps 的统一质量基线。赞分享后端MCP 服务MCP ClientsAI Agent人工智能【免费下载链接】mcp-useThe fullstack MCP framework to develop MCP Apps for ChatGPT / Claude MCP Servers for AI Agents.项目地址https://gitcode.com/gh_mirrors/mc/mcp-use点击查看免费下载相关推荐mcp-use 验证清单实战从静态检查到 MCP 服务器与 MCP App 端到端验证mcp use 验证清单实战从静态检查到 MCP 服务器与 MCP App 端到端验证 本篇技术指南基于 mcp use 仓库中 skills/mcp app后端MCP 服务MCP ClientsAI Agent人工智能WeKnora API 认证与用户体系完全指南注册、登录、OIDC、令牌刷新与邀请入会实战WeKnora API 认证与用户体系完全指南注册、登录、OIDC、令牌刷新与邀请入会实战 本文以 WeKnora 的 /api/v1/auth/ 认证与 /后端MCP 服务MCP ClientsAI Agent人工智能Arthas MCP Server 集成测试指南从 as.sh 动态 attach 到 Streamable HTTP 端到端验证Arthas MCP Server 集成测试指南从 as.sh 动态 attach 到 Streamable HTTP 端到端验证 arthas mcp in开发工具可观测性调试器性能剖析上一篇Magika Rust 库在新模型发布时如何用 sync.sh 同步 model 相关文件下一篇Cosmos视觉编码器技术解析图像与视频特征提取原理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
