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 源码根目录。