FilesLast commitLast update
9 hours ago
12 hours ago
12 hours ago
README

soulsoft_web_mcp

让仓颉 MCP 服务端跑在 Spire Web 宿主里,写法对照 C# 的 ModelContextProtocol.AspNetCore。

协议版本只支持 2026-07-28:HTTP 上只有一个 POST 入口,没有会话,也没有旧版 HTTP+SSE。

快速开始

import stdx.encoding.json.*
import soulsoft_extensions_injection.*
import soulsoft_web_http.*
import soulsoft_web_routing.*
import soulsoft_web_hosting.*
import soulsoft_web_mcp.*
import model_context_protocol.protocol.*
import model_context_protocol.server.*

func echoTool(): McpServerTool {
    let schema = JsonObject()
    schema.put("type", JsonString("object"))
    McpServerTool(Tool("echo", schema), {params, _ =>
        CallToolResult([TextContent(params.name)])
    })
}

main(): Int64 {
    let builder = WebHost.createBuilder()
    builder.services.addRouting()
    builder.services.addMcpServer().withHttpTransport().withTools([echoTool()])

    let host = builder.build()
    host.useRouting()
    host.mapMcp(pattern: "/mcp")
    host.run()
    0
}

启动后,MCP 客户端连接 http://127.0.0.1:5000/mcp 即可。

配置

服务器信息、工具、处理器、过滤器都在 addMcpServer 的回调里设置:

builder.services.addMcpServer(configureOptions: {options =>
    options.serverInfo = Implementation("demo", "1.0.0", None, None, None, None)
}).withHttpTransport().withTools([echoTool()])

需要学习客户端列表时追加工具:

builder.services.addMcpServer().withTools([echoTool(), pingTool()])

浏览器跨域和 Origin 校验按 Spire 的 CORS 中间件配置,不在 MCP 选项里:

import soulsoft_web_cors.*

builder.services.addCors {options =>
    options.addPolicy("mcp") {policy =>
        policy.withOrigins(["https://app.example.com"]).allowAnyMethod().allowAnyHeader()
    }
}

let host = builder.build()
host.useRouting()
host.useCors("mcp")
host.mapMcp(pattern: "/mcp")

客户端看到的行为

客户端必须同时接受 application/json 和 text/event-stream,否则返回 406。每次请求都要带 MCP-Protocol-Version 和 Mcp-Method;tools/call、prompts/get、resources/read 还要带 Mcp-Name。工具参数如果标了 x-mcp-header,对应的 Mcp-Param-<名称> 必须匹配请求体。

响应是该请求专属的 SSE 流;通知返回 202 Accepted。2026-07-28 已移除的 initialize、ping、logging/setLevel、resources/subscribe、resources/unsubscribe 在 HTTP 层直接返回 404。

认证

MCP 端点就是普通路由,认证和授权交给 Spire 的中间件与 endpoint 约定:

import soulsoft_web_authentication.*
import soulsoft_web_authentication_jwtbearer.*
import soulsoft_web_authorization.*

builder.services.addAuthentication(JwtBearerDefaults.Scheme)
    .addJwtBearer(JwtBearerDefaults.Scheme) {options =>
        options.requireHttpsMetadata = false
    }
builder.services.addAuthorization()

let host = builder.build()
host.useRouting()
host.useAuthentication()
host.useAuthorization()
host.mapMcp(pattern: "/mcp").requireAuthorization()

适配层不读取 Authorization,也不自己返回 401;拒绝请求、挑战头、策略判断都由 Spire 完成。需要使用 OAuth 元数据端点时,按 Spire 常规方式自行映射。

不提供的内容

  • 会话、Mcp-Session-Id、GET/DELETE 端点:2026-07-28 已移除。
  • 旧版 /sse + /message 传输。
  • 自动映射 /.well-known/oauth-protected-resource:由应用决定暴露哪些元数据。

依赖

[dependencies]
model_context_protocol = { path = "../mcp" }
soulsoft_extensions_injection = { path = "${SPIRE_PATH}/soulsoft_extensions_injection" }
soulsoft_extensions_options = { path = "${SPIRE_PATH}/soulsoft_extensions_options" }
soulsoft_extensions_hosting = { path = "${SPIRE_PATH}/soulsoft_extensions_hosting" }
soulsoft_web_hosting = { path = "${SPIRE_PATH}/soulsoft_web_hosting" }
soulsoft_web_http = { path = "${SPIRE_PATH}/soulsoft_web_http" }
soulsoft_web_routing = { path = "${SPIRE_PATH}/soulsoft_web_routing" }

SPIRE_PATH 指向 Spire 源码根目录。