MCP 基础
Model Context Protocol（MCP）是一套让 AI 应用以统一方式发现和调用外部工具、资源与提示模板的开放协议。它解决的是接入边界，不替你解决权限、安全和业务正确性。
角色与原语
- Host 管理用户会话、模型和整体权限。
- Client 负责与一个 Server 建立协议连接。
- Server 暴露工具、资源和提示模板。
- Tool 执行动作，Resource 提供可读取数据，Prompt 提供可复用模板。
调用链
text
initialize
-> 能力协商
-> tools/list 或 resources/list
-> tools/call
-> 返回结构化结果
-> Host 将结果交给模型工具描述应包含名称、用途、输入 schema、错误语义和副作用说明。工具返回值也应区分文本、结构化数据和用户可见资源。
最小 Go Server 思路
下面是协议实现的结构示意，实际项目应使用对应版本的官方 SDK 或经过验证的实现：
go
type SearchInput struct {
Query string `json:"query"`
}
func Search(ctx context.Context, input SearchInput) (any, error) {
if strings.TrimSpace(input.Query) == "" {
return nil, errors.New("query is required")
}
return index.Search(ctx, input.Query)
}不要把任意 Shell 暴露成一个名为 run 的万能工具。拆成 go_test、read_file、search_symbol 等边界清楚的工具，并对每个输入做校验。
stdio 适用场景
stdio 适合本机单用户工具：
- Server 与 Host 在同一台机器；
- 进程由 Host 启动和回收；
- 不需要远程共享；
- 权限可以继承本地工作区边界。
日志不要写入协议标准输出，否则会破坏 JSON-RPC 消息；把诊断日志写到 stderr 或独立文件。
JSON-RPC 错误
把错误分为：
- 参数校验失败：调用者可以修正输入；
- 权限失败：需要审批或换身份；
- 业务失败：外部系统拒绝或状态不满足；
- 临时失败：可以在预算内重试；
- 内部错误：需要记录 trace id 并人工排查。
练习
- 设计一个只读
search_symbolTool 的输入和输出 schema。 - 解释为什么 MCP Server 的日志不能随意写 stdout。
- 为一个会修改代码的 Tool 写出三条权限和审计要求。