用途:构建可被任意 MCP 兼容客户端(Claude Desktop、Claude Code、Cursor 等)消费的 MCP 服务器,把内部 API 或工具暴露给 AI 客户端,或发布为可共享的服务器(npm、PyPI、Smithery 注册表),也用于把只读数据源包装为 MCP 资源,让代理无需为每个客户端写定制胶水代码即可调用服务。
核心模型:MCP 服务器暴露三类原语——Tool(代理调用的动作,可能产生写入、网络请求等副作用)、Resource(代理读取的数据,只读,以 URI 寻址)、Prompt(可复用提示模板,无副作用,用户可调用)。应正确选择原语,把读操作误做成 Tool 会浪费上下文。
使用方式:TypeScript 可执行 npm init -y、npm i @modelcontextprotocol/sdk zod、npm i -D typescript tsx @types/node,用 McpServer 与 StdioServerTransport 注册 tool/resource;Python 可执行 uv add "mcp[cli]",用 FastMCP 装饰器定义 tool 与 resource,再 mcp.run()。注册到客户端 mcp.json 的 mcpServers 中,command 指向运行方式。
工具契约规则:名称用 snake_case 且以动词开头;描述一句话、以动词开头并提及关键参数;schema 用 Zod / Pydantic 并对每个字段加描述;返回统一为 content 文本包裹 JSON;错误直接抛出,由 SDK 转为 isError;写操作尽量接受 idempotency_key。建议采用渐进披露,暴露少量稳定工具并返回后续句柄。
测试与发布:开发期用 npx @modelcontextprotocol/inspector tsx src/server.ts 调用工具、检查资源、回放提示,并可在 CI 对 mock 后端运行以捕获 schema 回归。发布可走 npm bin 入口、Smithery 的 smithery.yaml,或私有 Docker 镜像。
限制与最佳实践:工具面建议不超过 15 个;返回文本而非二进制,大负载用带 URI 的资源;长任务通过 server.sendNotification 进度事件流式上报;破坏性变更时在服务器名加版本后缀;密钥在启动时加载而非工具调用时读取环境变量;记录每次工具调用以便审计。资料未提供具体收费、价格与平台支持范围。