FilesLast commitLast update
5 hours ago
5 hours ago
8 hours ago
10 hours ago
README

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。

更多