model_context_protocol
用仓颉写 MCP 客户端和服务端的库,面向 2026-07-28 版本。你可以用它连接一个 MCP 服务端,也可以自己实现一个服务端,把工具、资源、提示词暴露给模型。内置 stdio 与 Streamable HTTP 传输,客户端和服务端都可使用。
本项目是独立的仓颉实现,不是 MCP 官方组织发布或维护的 SDK。文中对 MCP 官方 C# SDK 的引用仅用于说明命名和行为参考。
使用前
需要仓颉工具链 cjc / cjpm,以及扩展标准库 stdx。设置好 CANGJIE_STDX_PATH;Windows 下还要把它加入 PATH,否则运行时找不到动态库。
快速上手
先写一个客户端
import stdx.encoding.json.*
import model_context_protocol.client.*
import model_context_protocol.protocol.*
func main(): Int64 {
let client = McpClient.create(
StdioClientTransport("server-executable", []))
try {
// listTools() 会自动翻页,把所有工具合并成一个数组
for (tool in client.listTools()) {
println(tool.name)
}
let arguments = JsonObject()
arguments.put("text", JsonString("hello"))
let result = client.callTool("echo", arguments: arguments)
println(result.content.size)
} finally {
client.close()
}
0
}
McpClient.create 会建立传输、调用 server/discover、确认服务端支持 2026-07-28。之后每个请求都会自动带上协议版本、客户端能力和客户端信息,你不需要手动拼 _meta。
再写一个服务端
import stdx.encoding.json.*
import model_context_protocol.protocol.*
import model_context_protocol.server.*
func echoTool(): Tool {
// Tool 描述一个工具:名称、说明,以及参数长什么样
let inputSchema = JsonObject()
inputSchema.put("type", JsonString("object"))
Tool("echo", inputSchema, description: "Echo the provided text")
}
func main(): Int64 {
let options = McpServerOptions()
options.serverInfo = Implementation("demo-server", "1.0.0", None, None, None, None)
// 一个工具 = 它的描述 + 被调用时执行的代码
options.toolCollection.add(McpServerTool(echoTool(), {params, _ =>
let text = match (params.arguments) {
case Some(arguments) => arguments.get("text").getOrThrow().asString().getValue()
case None => ""
}
CallToolResult([TextContent(text)])
}))
McpServer.create(StdioServerTransport(), options).run()
0
}
注册之后,tools/list、tools/call 和 tools 能力声明都由库自动处理,不需要再写工具路由。
客户端怎么用
选择连接方式
最常见的是 stdio:传一个可执行文件和参数,库会替你启动子进程。
let client = McpClient.create(StdioClientTransport("server-executable", ["--flag"]))
连接前需要更多配置时,用 StdioClientTransportOptions;要连 Streamable HTTP 服务端,用 HttpClientTransport:
let http = HttpClientTransport(HttpClientTransportOptions(
"http://127.0.0.1:8080/mcp",
additionalHeaders: [("Authorization", "Bearer ...")]))
let client = McpClient.create(http)
如果输入输出流由你自己提供,用 StreamClientTransport(input, output, ...)。想接其他传输,实现 ClientTransport 的 name 和 connect() 即可。
HTTP 客户端支持 JSON 与 per-request SSE 响应,并自动附加协议版本和 Mcp-Method/Mcp-Name 头。
客户端配置
McpClientOptions 里常用的是:
clientInfo:客户端名称和版本,会写进_meta.clientInfo。capabilities:客户端能力;注册elicitationHandler时会自动声明 form elicitation。protocolVersion:只能填2026-07-28,或留空。handlers.addNotificationHandler(...):连接前注册通知处理器。
单次请求想加 _meta 字段或指定进度 token,用 RequestOptions(meta:, progressToken:)。
调用能力
工具、资源、提示词和补全都在 McpClient 上:
// 工具
let tools = client.listTools() // 自动翻页
let onePage = client.listTools(ListToolsRequestParams()) // 只取一页
let result = client.callTool("echo", arguments: arguments)
// 资源
let resources = client.listResources()
let read = client.readResource("memory://item")
// 提示词
let prompt = client.getPrompt("hello", arguments: arguments)
// 补全
let completion = client.complete(
CompleteRequestParams(PromptReference("hello"), Argument("name", "h")))
无参列表方法会一直取 nextCursor,把所有页合并;带参数的版本返回原始的 ListToolsResult 这类单页结果。callTool、readResource、getPrompt 会自动处理服务端的 input_required 重试。
报告进度
给调用传一个进度回调即可。库会自动生成 token,只把这次调用的进度通知给你:
client.callTool("long-task", progress: {value =>
println("${value.progress} / ${value.total} ${value.message ?? ""}")
})
处理需要用户输入的工具
如果工具需要用户确认,客户端会自动与服务端往返。你只需要注册一个 elicitationHandler:
let options = McpClientOptions()
options.handlers.elicitationHandler = {params =>
ElicitResult("accept", content: JsonObject())
}
let client = McpClient.create(transport, options: options)
服务端返回 input_required 时,库会调用这个处理器、把结果放进 inputResponses,带着 requestState 重试,最多 10 轮。
接收通知
let registration = client.registerNotificationHandler(
NotificationMethods.ToolListChangedNotification, {notification =>
// notification.method、notification.params
})
// 不再需要时注销
registration.close()
同一个方法可以注册多个处理器;其中一个抛异常不会影响其他处理器。需要在连接前注册时,用 options.handlers.addNotificationHandler(method, handler)。
订阅变化
let subscription = client.listen(
SubscriptionsListenNotifications(toolsListChanged: true))
// 服务端先发确认,之后的通知才有效
let ack = McpJsonUtilities.parse<SubscriptionsListenResult>(subscription.awaitResult())
// 结束订阅
subscription.cancel()
提前发请求、稍后取结果
beginRequest 会立刻返回一个句柄,不影响当前线程继续做别的事:
let pending = client.beginRequest(RequestMethods.ToolsCall,
CallToolRequestParams("long-task"))
// ...
let raw = pending.awaitResult()
// 也可以中断
pending.cancel("no longer needed")
listen 返回的也是同一个句柄类型。取消会发送 notifications/cancelled。stdio 下立即生效;HTTP 的 JSON 响应只能尽力取消,SSE 通过关闭响应流取消。
服务端怎么用
启动
let options = McpServerOptions()
options.serverInfo = Implementation("demo-server", "1.0.0", None, None, None, None)
options.serverInstructions = "Use echo for testing."
let transport = StdioServerTransport()
McpServer.create(transport, options).run()
如果输入输出流由你自己提供,使用 McpServer.create(StreamServerTransport(input, output, 1048576), options)。
服务端会并行处理请求,直到传输关闭。关闭时,所有 subscriptions/listen 会收到取消通知,普通请求会等处理完再退出。
如果你自己写客户端而不是用 McpClient,每个请求都必须带 _meta.protocolVersion 和 _meta.clientCapabilities。
HTTP 服务端
使用 stdx 创建 HTTP 主机,注册 MCP handler:
import stdx.net.http.*
let transport = StreamableHttpServerTransport()
let handler = StreamableHttpHandler(transport,
allowedOrigins: ["http://localhost:3000"],
tools: options.toolCollection)
let server = McpServer.create(transport, options)
let http = ServerBuilder().addr("127.0.0.1").port(8080).build()
http.distributor.register("/mcp", handler)
http.distributor.register("/health",
FuncHandler({ctx => ctx.responseBuilder.body("ok")}))
spawn { server.run() }
try {
http.serve()
} finally {
server.close()
http.close()
}
StreamableHttpServerTransport只负责 MCP 消息收发,不涉及 HTTP 或路径。StreamableHttpHandler实现HttpRequestHandler,负责头校验、JSON/SSE、202/404。- 路径和共存路由由 stdx
HttpRequestDistributor负责,因此可以和/health等 endpoint 共用同一个服务端。 - 请求按
Accept返回 JSON 或 SSE;subscriptions/listen始终 SSE。 - 通知 POST 返回 202;
MCP-Protocol-Version/Mcp-Method/Mcp-Name与请求体不一致返回 400 +-32020。 allowedOrigins为空时允许没有 Origin 的客户端,拒绝带 Origin 的请求。
能力是自动推断的
没有显式设置 options.capabilities 时:
- 注册了工具(
toolCollection非空),或同时提供了listToolsHandler和callToolHandler,就声明tools; - 同时提供资源列表和读取处理器,就声明
resources; - 同时提供提示词列表和获取处理器,就声明
prompts; - 提供
completeHandler,就声明completions; - 提供
subscriptionsListenHandler时,listChanged/subscribe置为 true。
需要完全自定义时,直接设置 options.capabilities。
声明一个工具
Tool 就是工具的描述,其中最重要的是 inputSchema:告诉模型这个工具接受什么参数,必须是 JSON Schema 2020-12 对象,根节点为 type: "object"。
func echoTool(): Tool {
// 参数 text:字符串
let textSchema = JsonObject()
textSchema.put("type", JsonString("string"))
textSchema.put("description", JsonString("Text to echo"))
// 参数集合
let properties = JsonObject()
properties.put("text", textSchema)
// 必填参数
let required = JsonArray()
required.add(JsonString("text"))
// 整个工具参数 Schema
let inputSchema = JsonObject()
inputSchema.put("type", JsonString("object"))
inputSchema.put("properties", properties)
inputSchema.put("required", required)
Tool("echo", inputSchema, title: "Echo", description: "Echo the provided text")
}
然后用 toolCollection 注册,把描述和调用逻辑放在一起:
options.toolCollection.add(McpServerTool(echoTool(), {params, context =>
// params.arguments 就是客户端传来的参数
let text = match (params.arguments) {
case Some(arguments) => arguments.get("text").getOrThrow().asString().getValue()
case None => ""
}
CallToolResult([TextContent(text)])
}))
列表按注册顺序返回;调用时按名称命中,未命中再交给 callToolHandler。如果希望动态生成工具列表,仍然可以使用 listToolsHandler 和 callToolHandler,注册的工具会与 handler 返回的结果合并。
工具返回什么
正常返回 CallToolResult;业务失败返回 isError: true 的结果,让模型看到原因并自我修正:
CallToolResult([TextContent("done")])
CallToolResult([TextContent("invalid input")], isError: true)
参数非法、未知工具这类协议错误,抛 McpProtocolException,它会变成 JSON-RPC 错误。其他未处理异常会被工具管道转成 isError: true 的结果。
工具声明了 outputSchema 时,结构化结果放进 structuredContent,同时建议保留一份文本内容:
let structured = JsonObject()
structured.put("value", JsonString("done"))
CallToolResult([TextContent("done")], structuredContent: structured)
工具内也可以直接发进度,或要求用户输入:
// 进度:token 来自请求的 _meta.progressToken
context.sendProgress(ProgressNotificationParams(token, 0.5, 1.0, None, None))
// 需要用户补充信息:客户端会自动重试
let requests = HashMap<String, InputRequest>()
requests.add("confirm", InputRequest(ElicitRequestParams("Continue?",
requestedSchema: RequestSchema(HashMap<String, PrimitiveSchemaDefinition>()))))
InputRequiredResult(inputRequests: requests)
资源、提示词和补全
import model_context_protocol.protocol.Resource as McpResource
options.handlers.listResourcesHandler = {_, _ =>
ListResourcesResult([McpResource("memory://item", "item")], Duration.Zero, CacheScope.Private)
}
options.handlers.readResourceHandler = {params, _ =>
ReadResourceResult([TextResourceContents(params.uri, "value")], Duration.Zero, CacheScope.Private)
}
options.handlers.listPromptsHandler = {_, _ =>
ListPromptsResult([Prompt("hello")], Duration.Zero, CacheScope.Private)
}
options.handlers.getPromptHandler = {params, _ =>
GetPromptResult([PromptMessage(Role.User, TextContent(params.name))])
}
options.handlers.completeHandler = {_, _ =>
CompleteResult(Completion(["hello"]))
}
还有 listResourceTemplatesHandler 用于资源模板。列表结果可以设置 nextCursor 做分页。
订阅
options.handlers.subscriptionsListenHandler = {params, context =>
// 先确认,之后才能发通知
context.acknowledgeSubscription(params.notifications)
// 只在客户端请求过、且能力允许时发送
context.sendToolsListChanged()
// 保持连接,业务事件发生时继续调用 context.sendXxx(...)
while (!context.isCancelled) {
sleep(Duration.second)
}
let meta = JsonObject()
match (context.id) {
case RequestId.IntegerId(value) => meta.put(MetaKeys.SubscriptionId, JsonInt(value))
case RequestId.StringId(value) => meta.put(MetaKeys.SubscriptionId, JsonString(value))
}
SubscriptionsListenResult(meta)
}
确认之前发通知会抛异常;未请求过的通知会被拒绝。可用通知包括 sendToolsListChanged、sendPromptsListChanged、sendResourcesListChanged、sendResourceUpdated、sendProgress 和通用的 sendNotification。
过滤器与工具执行顺序
如果你需要鉴权、日志或改写结果,可以挂过滤器。一次 tools/call 的大致顺序是:
入站消息过滤器
→ 版本与客户端能力校验
→ 绑定命中工具(context.matchedPrimitive)
→ 外层错误转换
→ callToolWithAlternateFilters
→ 内层错误转换
→ callToolFilters
→ 工具或 callToolHandler
→ 结果校验 → 出站消息过滤器 → 发送
消息过滤器直接看 JsonRpcMessage:
options.filters.message.incomingFilters.add({next => {message =>
next(message)
}})
options.filters.message.outgoingFilters.add({next => {message =>
next(message)
}})
按方法包装处理器:
options.filters.request.listToolsFilters.add({next => {params, context =>
let result = next(params, context)
result
}})
callToolWithAlternateFilters 在外层,能看到包含 input_required 在内的最终结果:
options.filters.request.callToolWithAlternateFilters.add(
{params: CallToolRequestParams, context: RequestContext,
next: McpRequestHandler<CallToolRequestParams, Result> =>
let result = next(params, context)
if (result.resultType == "input_required") {
// MRTR 往返也经过这里
}
result
})
请求进入管道前,context.matchedPrimitive 会绑定命中的工具;没有命中就是 None。工具或过滤器抛出 McpProtocolException 时保持为 JSON-RPC 错误;请求已取消时原样抛出;其他异常转成 isError: true 的工具结果。
缓存提示
列表、读取和发现结果都带 timeToLive(线上字段 ttlMs)和 cacheScope。服务端构造结果时自己决定,例如:
ListToolsResult(tools, Duration.Zero, CacheScope.Private)
库本身不缓存,用不用由你决定。
认证(OAuth)
客户端按 0728 的 OAuth 2.1 流程接入:Protected Resource Metadata → Authorization Server Metadata → PKCE(必须 S256)→ 授权码交换 → Bearer Token;访问令牌过期时自动刷新,HTTP 401/403 会失效缓存并重试一次。
import model_context_protocol.auth.*
let oauth = ClientOAuthOptions(
"http://localhost:3000/callback",
{context =>
// 打开浏览器;用户回调后把 code 和 state 返回给库。
AuthorizationResult(code: readCallbackCode(), state: queryValue(context.authorizationUri, "state"))
},
clientId: "my-client",
scopes: ["mcp"])
let transport = HttpClientTransport(HttpClientTransportOptions(
"https://mcp.example.com/mcp", oauth: oauth))
let client = McpClient.create(transport)
服务端可以声明受保护资源并校验 Bearer:
let metadata = ProtectedResourceMetadata(
["https://auth.example.com"],
resource: "https://mcp.example.com/mcp",
scopesSupported: ["mcp"])
let handler = StreamableHttpHandler(transport,
tokenValidator: {token => validateAccessToken(token)},
resourceMetadataUrl: "https://mcp.example.com/.well-known/oauth-protected-resource",
tools: options.toolCollection)
http.distributor.register("/mcp", handler)
http.distributor.register("/.well-known/oauth-protected-resource",
ProtectedResourceMetadataHandler(metadata))
tokenValidator 由应用校验签名、issuer、audience 和 scopes;返回 false 会得到 401 和 WWW-Authenticate: Bearer resource_metadata="..."。受保护资源元数据路由由 HTTP 主机注册。
已实现:PRM 与 AS 元数据发现、PKCE S256、授权码交换、resource 参数、token 缓存与刷新、Bearer 头、401/403 重试。未实现:Dynamic Client Registration(0728 已弃用)、scope step-up 的完整 WWW-Authenticate 解析、内置 JWT/JWKS 校验(由 tokenValidator 负责)。
并发与关闭
服务端并行处理请求,处理器和过滤器可能同时运行,需要自己保证线程安全。客户端可以从多个线程同时发起请求。client.close() 会关闭传输并让未完成请求失败;服务端关闭时会先结束订阅、等待普通请求处理完。
出错时
自定义客户端一般只需要关心这些异常:
McpProtocolException:JSON-RPC 错误,带errorCode和errorData。UnsupportedProtocolVersionException:版本不支持,带requested和supported。MissingRequiredClientCapabilityException:缺少必需的客户端能力。ClientTransportClosedException:传输已关闭,请求无法完成。
常见错误码:ParseError -32700、InvalidRequest -32600、MethodNotFound -32601、InvalidParams -32602、InternalError -32603、HeaderMismatch -32020、MissingRequiredClientCapability -32021、UnsupportedProtocolVersion -32022。
客户端会把服务端的 -32021、-32022 转成对应的类型化异常,其余错误转成 McpProtocolException。
限制
- 只实现
2026-07-28,没有旧版initialize握手,也不包含已废弃的 Roots、Sampling、Logging、ping、resources/subscribe。 - 工具
inputSchema需要手写,没有 C# 式的反射自动生成。 - 未实现
Mcp-Param-*/x-mcp-header。 - 未实现 JSON Schema 2020-12 方言校验,参数和结构化结果由应用校验。
- 非 SSE 的 HTTP 请求无法在响应前中断,取消是尽力而为。
- OAuth 客户端流程已实现;服务端 token 校验通过
tokenValidator由应用完成,未内置 JWT/JWKS 校验和 Dynamic Client Registration。 - stdio 服务端读取标准输入时使用单字节读取(平台管道缓冲行为限制)。
致谢
本项目的公开 API 命名和部分行为参考了 MCP 官方组织的 C# SDK(ModelContextProtocol.Core),包括 McpJsonUtilities、McpHttpHeaders/McpHeaderEncoder、McpServerTool/ToolCollection、请求与通知方法常量、过滤器与工具调用管道、错误码约定等。协议模型以 MCP 2026-07-28 官方 schema 与规范为准。实现代码为仓颉独立编写,未复制 C# SDK 源码;第三方声明与许可证副本见 THIRD_PARTY_NOTICES.md。
更多
- 示例与跨语言验证:examples/README.md
- 开发约定
- 顶层设计
- C# 管道参考