@blod-nm/nuxt-mcp 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @blod-nm/nuxt-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+按 **MCP 2026-07-28**（Streamable HTTP，**不走 SSE**）把能力暴露成唯一 HTTP 出口。模块零能力，能力由外部注册。纯 JS。
+
+## 使用
+
+```js
+// nuxt.config.ts
+export default defineNuxtConfig({ modules: ['@blod-nm/nuxt-mcp'] })   // 出口：POST /api/mcp
+```
+
+```js
+// server/plugins/userkit.js —— 按大类注册（名字扁平，无 namespace）
+export default defineNitroPlugin(() => {
+  registerMcpTools(() => [{
+    name: 'user_me',
+    title: '获取当前用户',
+    description: '返回当前登录用户资料',
+    inputSchema: { type: 'object', properties: { access_token: { type: 'string' } }, required: ['access_token'] },
+    annotations: { readOnlyHint: true },
+    run: args => kit.ctx.run('user.me', args),
+  }])
+
+  registerMcpResources(() => [{
+    uri: 'userkit://readme', name: 'readme', mimeType: 'text/markdown',
+    read: async uri => ({ contents: [{ uri, mimeType: 'text/markdown', text: '# hi' }] }),
+  }])
+
+  registerMcpPrompts(() => [{
+    name: 'greet', description: '打招呼', arguments: [{ name: 'who', required: true }],
+    render: args => ({ messages: [{ role: 'user', content: { type: 'text', text: 'hi ' + args.who } }] }),
+  }])
+
+  registerMcpCompletion(async ({ argument }) => ['张三', '李四'].filter(v => v.startsWith(argument.value)))
+})
+```
+
+## 接口（HTTP MCP 全集）
+
+| 方法 | 状态 | 说明 |
+| --- | --- | --- |
+| `server/discover` | ✅ | `{ supportedVersions, capabilities, instructions, ttlMs, cacheScope }`（取代 initialize） |
+| `tools/list` · `tools/call` | ✅ | 未注册工具 → 空列表 / `-32602` |
+| `resources/list` · `resources/templates/list` · `resources/read` | ✅ | 未注册资源 → 空列表 / `-32602` |
+| `prompts/list` · `prompts/get` | ✅ | 未注册提示词 → 空列表 / `-32602` |
+| `completion/complete` | ✅ | 未注册补全器 → `-32601` |
+| `resources/subscribe` · `resources/unsubscribe` · `subscriptions/listen` | ⛔ 预留 | 需要 SSE 流 → `-32601` 并说明原因 |
+| `notifications/*` | ✅ | `202 Accepted`，无 body |
+| `initialize` · `ping` · `logging/setLevel` | ✅ 兼容层 | 2026 已移除，但为旧客户端保留：initialize 协商版本、ping 回 `{}`、setLevel 接受（无 SSE 不推送） |
+
+## 协议要点
+
+- 每个 result 都带 `resultType: "complete"`；列表/读取类带 `ttlMs`、`cacheScope`
+- 版本协商：`_meta["io.modelcontextprotocol/protocolVersion"]` 与 `MCP-Protocol-Version` 头不一致 → `400` + `-32020`；版本不支持 → `-32022`
+- 名字：MCP 只允许 `[A-Za-z0-9_-]`，非法字符注册时替换为 `_`；**重名注册直接报错**
+- `tools/call`：`structuredContent` 可为任意 JSON；工具自身错误 → `isError:true`；找不到工具 → `-32602`
+- 传输：`GET → 405`；Origin 跨域 → `403`；Accept 不含 json/event-stream → `406`
+
+## 版本兼容
+
+| 客户端版本 | 握手方式 | 支持 |
+| --- | --- | --- |
+| 2026-07-28 | `server/discover` + 每请求 `_meta` | ✅ |
+| 2025-11-25 / 2025-06-18 / 2025-03-26 | `initialize`（协商到对应版本） | ✅ 兼容层 |
+| 2024-11-05 | `initialize` | ⚠️ 未列入白名单（建议升级） |
+
+- 兼容层只加不改：新版继续走 `server/discover`；旧版走 `initialize`，两套共用同一份注册表与结果构造。
+- `initialize` 的结果不带 `resultType`（旧客户端不认这个字段）；其余请求的结果始终带。
+- 旧客户端不带 `_meta` 也能调用；版本校验只在客户端显式声明版本时生效。
+
+## 选项
+
+| 选项 | 默认 | 说明 |
+| --- | --- | --- |
+| `route` | `/api/mcp` | 唯一出口路径 |
+
+## 约定
+
+- 每个大类一次注册 = 整组替换（不是累加）；重名在注册时 fail-fast。
+- 能力惰性解析：`*/list`、`*/call` 时才实例化。
+- 不声明 `logging` / `resources.subscribe`：它们需要服务端主动推送，本实现没有 SSE。

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@blod-nm/nuxt-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "MCP protocol pipe for Nuxt: one endpoint (initialize/tools/list/tools/call), zero abilities, sources injected by other modules.",
+  "main": "./src/module.js",
+  "exports": {
+    ".": "./src/module.js",
+    "./runtime/*": "./runtime/*"
+  },
+  "dependencies": {
+    "@blod-nm/base-ctx": "^0.1.1",
+    "@nuxt/kit": "^4.5.2"
+  },
+  "devDependencies": {
+    "h3": "^1.15.11"
+  },
+  "scripts": {
+    "test": "bun test test/",
+    "test:e2e": "bun test e2e/"
+  },
+  "files": [
+    "src",
+    "runtime",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "h3": ">=1.15.0"
+  }
+}

package/runtime/server/api/mcp.post.js

@@ -0,0 +1,166 @@
+/**
+  mcp.post.js — 唯一能力出口（应用型 · MCP 2026-07-28 · Streamable HTTP 单端点 · 纯 JS）
+
+  职责: 按最新协议处理 POST /api/mcp：
+        · request（有 id）      → 200 + application/json；每个 result 都带 resultType:"complete"
+        · notification（无 id） → 202 Accepted，无 body
+        · GET                   → 405（不提供 SSE 流）
+        版本协商: server/discover（MUST）+ 每请求 _meta["io.modelcontextprotocol/protocolVersion"]，
+        与 MCP-Protocol-Version 头不一致 → 400 / -32020；版本不支持 → -32022。
+
+  位置: @feature/nuxt-mcp → src/module.js addServerHandler → 本文件
+
+  数据流:
+    body { jsonrpc, id, method, params }
+      → server/discover              → { supportedVersions, capabilities, instructions, ttlMs, cacheScope }
+      → tools/list / tools/call      → Tool[] / { content, structuredContent?, isError }
+      → resources/list|templates|read→ Resource[] / ResourceTemplate[] / { contents }
+      → prompts/list|get             → Prompt[] / { description?, messages }
+      → completion/complete          → { completion: { values } }
+      → notifications/*              → 202
+      → 其余                         → -32601
+*/
+import { defineEventHandler, readBody, setResponseStatus, getHeader, setHeader, getRequestURL } from 'h3'
+import {
+  callTool, listTools, listResources, listResourceTemplates, readResource,
+  listPrompts, getPrompt, complete, mcpCapabilities,
+} from '../utils/mcp'
+
+const PROTOCOL_VERSION = '2026-07-28'
+/** 兼容层：旧版客户端走 initialize；新版走 server/discover。都落在这张白名单里 */
+const SUPPORTED_VERSIONS = ['2026-07-28', '2025-11-25', '2025-06-18', '2025-03-26']
+const pickVersion = client => (SUPPORTED_VERSIONS.includes(client) ? client : PROTOCOL_VERSION)
+const HEADER_MISMATCH = -32020
+const UNSUPPORTED_PROTOCOL_VERSION = -32022
+const SERVER_INFO = { name: 'nuxt-mcp', title: 'Nuxt MCP', version: '0.1.0' }
+const INSTRUCTIONS = '先 server/discover 拿能力，再 tools/list 或 prompts/list；tools/call 的 name 形如 <ns>__<tool>。业务错误看 isError。'
+
+const META_VERSION = 'io.modelcontextprotocol/protocolVersion'
+/** 依赖服务端推送的接口：只在 SSE 模式下可用 */
+const SSE_METHODS = new Set(['resources/subscribe', 'resources/unsubscribe', 'subscriptions/listen'])
+/** 每个结果都必须带 resultType；可缓存结果再带 ttlMs / cacheScope */
+const plain = (id, payload) => ({ jsonrpc: '2.0', id: id ?? null, result: payload })
+const ok = (id, payload = {}) => ({ jsonrpc: '2.0', id: id ?? null, result: { resultType: 'complete', ...payload } })
+const cacheable = (id, payload, scope = 'public') => ok(id, { ttlMs: 0, cacheScope: scope, ...payload })
+const fail = (id, code, message) => ({ jsonrpc: '2.0', id: id ?? null, error: { code, message } })
+
+/** 工具结果：结构化内容可以是任意 JSON 值（2026-07-28 起放宽到 array/标量） */
+const toolResult = out => ({
+  content: [{ type: 'text', text: JSON.stringify(out ?? null) }],
+  ...(out === undefined ? {} : { structuredContent: out }),
+  isError: false,
+})
+/** 工具自身错误 → isError；协议错误（找不到工具）另走 JSON-RPC error */
+const toolError = e => ({
+  content: [{ type: 'text', text: JSON.stringify({ message: e?.message ?? String(e), code: e?.code, payload: e?.payload }) }],
+  isError: true,
+})
+
+export default defineEventHandler(async (event) => {
+  const method = event.method?.toUpperCase()
+  if (method === 'GET') { setResponseStatus(event, 405); return '' }   // 不提供服务端 SSE 流
+
+  // 规范 MUST：校验 Origin，防 DNS rebinding；同源（或无 Origin，如服务端调用）放行
+  const origin = getHeader(event, 'origin')
+  const host = getHeader(event, 'host') || getRequestURL(event).host
+  if (origin && host) {
+    let sameOrigin = false
+    try { sameOrigin = new URL(origin).host === host } catch {}
+    if (!sameOrigin) { setResponseStatus(event, 403); return '' }
+  }
+
+  // Streamable HTTP：客户端声明可接受的内容类型；两个都不接受 → 406
+  const accept = String(getHeader(event, 'accept') ?? '')
+  if (accept && !accept.includes('*/*') && !accept.includes('application/json') && !accept.includes('text/event-stream')) {   // */* 是 curl/fetch 默认值，按通配放行
+    setResponseStatus(event, 406)
+    return fail(null, -32600, 'Accept 需要 application/json 或 text/event-stream')
+  }
+
+  const body = await readBody(event).catch(() => null)
+  if (!body || typeof body !== 'object' || typeof body.method !== 'string') {
+    setResponseStatus(event, 400)
+    return fail(null, -32600, 'Invalid Request')
+  }
+
+  const { id, method: rpcMethod, params } = body
+  const isNotification = id === undefined || id === null
+
+  // 通知：接受即 202 无 body（notifications/initialized 已废除，其余通知照旧）
+  if (isNotification) {
+    if (rpcMethod.startsWith('notifications/')) { setResponseStatus(event, 202); return '' }   // h3: 返回 undefined 会被当成 404
+    setResponseStatus(event, 400)
+    return fail(null, -32600, '通知缺少 id，但不是 notifications/*')
+  }
+
+  // 版本协商（2026-07-28）：_meta 里的版本必须与 MCP-Protocol-Version 头一致
+  const metaVersion = params?._meta?.[META_VERSION]
+  const headerVersion = getHeader(event, 'mcp-protocol-version')
+  if (metaVersion && headerVersion && metaVersion !== headerVersion) {
+    setResponseStatus(event, 400)
+    return fail(id, HEADER_MISMATCH, `版本头与 body 不一致: ${headerVersion} ≠ ${metaVersion}`)
+  }
+  const requested = metaVersion ?? headerVersion
+  if (requested && !SUPPORTED_VERSIONS.includes(requested))
+    return fail(id, UNSUPPORTED_PROTOCOL_VERSION, `不支持的协议版本: ${requested}（支持: ${SUPPORTED_VERSIONS.join(', ')}）`)
+
+
+  setHeader(event, 'Content-Type', 'application/json')
+
+  // —— 兼容层（旧版客户端）——
+  // initialize：返回双方都支持的版本；initialize 结果本身不带 resultType（旧客户端不认）
+  if (rpcMethod === 'initialize') {
+    const v = pickVersion(params?.protocolVersion)
+    return plain(id, { protocolVersion: v, capabilities: mcpCapabilities(), serverInfo: SERVER_INFO, instructions: INSTRUCTIONS })
+  }
+  if (rpcMethod === 'ping') return plain(id, {})                      // 2026 已移除，旧客户端探活用
+  if (rpcMethod === 'logging/setLevel') return plain(id, {})          // 无 SSE 不推送日志，但接受调用
+
+  if (rpcMethod === 'server/discover')
+    return cacheable(id, { supportedVersions: SUPPORTED_VERSIONS, capabilities: mcpCapabilities(), instructions: INSTRUCTIONS, serverInfo: SERVER_INFO })
+
+  if (rpcMethod === 'tools/list') return cacheable(id, { tools: listTools() }, 'private')
+  if (rpcMethod === 'tools/call') {
+    if (typeof params?.name !== 'string' || !params.name) return fail(id, -32602, 'Invalid params: name 必填')
+    try {
+      return ok(id, toolResult(await callTool(params.name, params.arguments ?? {})))
+    } catch (e) {
+      if (e?.rpcCode) return fail(id, e.rpcCode, e.message)   // 找不到工具 = 协议错误
+      return ok(id, toolError(e))
+    }
+  }
+
+  if (rpcMethod === 'resources/list') return cacheable(id, { resources: listResources() }, 'private')
+  if (rpcMethod === 'resources/templates/list') return cacheable(id, { resourceTemplates: listResourceTemplates() }, 'private')
+  if (rpcMethod === 'resources/read') {
+    if (typeof params?.uri !== 'string' || !params.uri) return fail(id, -32602, 'Invalid params: uri 必填')
+    try {
+      return cacheable(id, await readResource(params.uri), 'private')
+    } catch (e) {
+      return fail(id, e?.rpcCode ?? -32603, e?.message ?? String(e))
+    }
+  }
+
+  if (rpcMethod === 'prompts/list') return cacheable(id, { prompts: listPrompts() }, 'private')
+  if (rpcMethod === 'prompts/get') {
+    if (typeof params?.name !== 'string' || !params.name) return fail(id, -32602, 'Invalid params: name 必填')
+    try {
+      return ok(id, await getPrompt(params.name, params.arguments ?? {}))
+    } catch (e) {
+      return fail(id, e?.rpcCode ?? -32603, e?.message ?? String(e))
+    }
+  }
+
+  // 需要 SSE 流的接口：位置预留，明确报不支持（本服务是 POST 单响应传输）
+  if (SSE_METHODS.has(rpcMethod))
+    return fail(id, -32601, `本服务不提供 SSE 流，不支持: ${rpcMethod}`)
+
+  if (rpcMethod === 'completion/complete') {
+    try {
+      return ok(id, await complete(params ?? {}))
+    } catch (e) {
+      return fail(id, e?.rpcCode ?? -32603, e?.message ?? String(e))
+    }
+  }
+
+  return fail(id, -32601, `Method not found: ${rpcMethod}`)
+})

package/runtime/server/utils/mcp.js

@@ -0,0 +1,176 @@
+/**
+  mcp.js — MCP 能力注册表（能力型 · 协议层自己的 ctx · 纯 JS）
+
+  职责: 按 MCP 能力大类注册/查询；名字是**扁平**的（MCP 无 namespace 概念），
+        重名在注册时就报错（fail-fast），不做隐式覆盖。
+
+  注册（外部注入）:
+    registerMcpTools(() => [{ name, title?, description?, inputSchema?, outputSchema?, annotations?, run }])
+    registerMcpResources(() => [{ uri, name, title?, description?, mimeType?, read }])
+    registerMcpPrompts(() => [{ name, title?, description?, arguments?, render }])
+    registerMcpCompletion(async ({ ref, argument }) => string[])
+
+  调用（handler 用）:
+    listTools() / callTool(name, args)
+    listResources() / listResourceTemplates() / readResource(uri)
+    listPrompts() / getPrompt(name, args)
+    complete(params)
+    capabilities()          // 只声明已注册的大类
+
+  示例:
+    registerMcpTools(() => [{
+      name: 'user_me', title: '获取当前用户', inputSchema: { type: 'object', properties: {} },
+      run: args => kit.ctx.run('user.me', args),
+    }])
+
+  说明: 需要服务端主动推送的类别（logging、resources/subscribe、subscriptions/listen）依赖 SSE，
+        本实现是 POST 单响应传输，故不声明这些能力，调用返回 -32601。
+*/
+import { createCtx } from '@blod-nm/base-ctx'
+
+const DEFAULT_INPUT_SCHEMA = { type: 'object', properties: {} }
+const safe = s => String(s).replace(/[^A-Za-z0-9_-]/g, '_')   // MCP 名字只允许 [A-Za-z0-9_-]
+export const toolNameOf = name => safe(name)
+
+const dup = (kind, name) => {
+  const e = new Error(`${kind} 重名: ${name}`)
+  e.rpcCode = -32602
+  return e
+}
+
+export function createMcpRegistry() {
+  const ctx = createCtx({})                       // tools 的执行总线（自己的 ctx）
+  const tools = new Map()                         // name → def
+  const resources = new Map()                     // uri → def
+  const prompts = new Map()                       // name → def
+  let completion = null
+  let generation = 0
+
+  const rebuildTools = () => {
+    for (const name of [...ctx.keys()]) if (!tools.has(name)) ctx.unregister(name)
+    for (const [name, def] of tools) ctx.register(name, { run: args => def.run(args ?? {}) })
+  }
+
+  return {
+    /* ---------- 注册面（整组替换；组内重名 fail-fast） ---------- */
+    registerTools(resolve) {
+      const next = new Map()
+      for (const def of resolve()) {
+        const name = toolNameOf(def.name)
+        if (next.has(name)) throw dup('tool', name)
+        next.set(name, def)
+      }
+      tools.clear()
+      for (const [k, v] of next) tools.set(k, v)
+      rebuildTools(); generation++
+    },
+    registerResources(resolve) {
+      const next = new Map()
+      for (const def of resolve()) {
+        if (next.has(def.uri)) throw dup('resource', def.uri)
+        next.set(def.uri, def)
+      }
+      resources.clear()
+      for (const [k, v] of next) resources.set(k, v)
+      generation++
+    },
+    registerPrompts(resolve) {
+      const next = new Map()
+      for (const def of resolve()) {
+        const name = toolNameOf(def.name)
+        if (next.has(name)) throw dup('prompt', name)
+        next.set(name, def)
+      }
+      prompts.clear()
+      for (const [k, v] of next) prompts.set(k, v)
+      generation++
+    },
+    registerCompletion(fn) { completion = fn; generation++ },
+
+    /* ---------- 能力声明 ---------- */
+    capabilities() {
+      const caps = {}
+      if (tools.size) caps.tools = {}
+      if (resources.size) caps.resources = { subscribe: false }   // 无 SSE → 不支持订阅推送
+      if (prompts.size) caps.prompts = {}
+      if (completion) caps.completions = {}
+      return caps
+    },
+
+    /* ---------- tools ---------- */
+    listTools() {
+      return [...tools.entries()].map(([name, def]) => {
+        const tool = {
+          name,
+          title: def.title ?? name,
+          description: String(def.description ?? ''),
+          inputSchema: def.inputSchema ?? DEFAULT_INPUT_SCHEMA,
+        }
+        if (def.outputSchema) tool.outputSchema = def.outputSchema
+        if (def.annotations) tool.annotations = def.annotations
+        return tool
+      })
+    },
+    callTool(name, args) {
+      if (!tools.has(name)) throw Object.assign(new Error(`未知工具: ${name}`), { rpcCode: -32602 })
+      return ctx.run(name, args ?? {})
+    },
+
+    /* ---------- resources ---------- */
+    listResources() {
+      return [...resources.values()].map(def => ({
+        uri: def.uri,
+        name: def.name ?? def.uri,
+        ...(def.title ? { title: def.title } : {}),
+        ...(def.description ? { description: def.description } : {}),
+        ...(def.mimeType ? { mimeType: def.mimeType } : {}),
+      }))
+    },
+    listResourceTemplates() { return [] },
+    readResource(uri) {
+      const def = resources.get(uri)
+      if (!def) throw Object.assign(new Error(`未知资源: ${uri}`), { rpcCode: -32602 })
+      return def.read(uri)
+    },
+
+    /* ---------- prompts ---------- */
+    listPrompts() {
+      return [...prompts.entries()].map(([name, def]) => ({
+        name,
+        ...(def.title ? { title: def.title } : {}),
+        ...(def.description ? { description: def.description } : {}),
+        ...(def.arguments ? { arguments: def.arguments } : {}),
+      }))
+    },
+    getPrompt(name, args) {
+      const def = prompts.get(name)
+      if (!def) throw Object.assign(new Error(`未知提示词: ${name}`), { rpcCode: -32602 })
+      return def.render(args ?? {})
+    },
+
+    /* ---------- completions ---------- */
+    async complete(params) {
+      if (!completion) throw Object.assign(new Error('未注册补全处理器'), { rpcCode: -32601 })
+      return { completion: { values: await completion(params) } }
+    },
+
+    /* ---------- 自检 ---------- */
+    stats: () => ({ generation, tools: tools.size, resources: resources.size, prompts: prompts.size, completion: !!completion }),
+  }
+}
+
+export const mcp = createMcpRegistry()
+export const registerMcpTools = resolve => mcp.registerTools(resolve)
+export const registerMcpResources = resolve => mcp.registerResources(resolve)
+export const registerMcpPrompts = resolve => mcp.registerPrompts(resolve)
+export const registerMcpCompletion = fn => mcp.registerCompletion(fn)
+export const listTools = () => mcp.listTools()
+export const callTool = (name, args) => mcp.callTool(name, args)
+export const listResources = () => mcp.listResources()
+export const listResourceTemplates = () => mcp.listResourceTemplates()
+export const readResource = uri => mcp.readResource(uri)
+export const listPrompts = () => mcp.listPrompts()
+export const getPrompt = (name, args) => mcp.getPrompt(name, args)
+export const complete = params => mcp.complete(params)
+export const mcpCapabilities = () => mcp.capabilities()
+export const mcpStats = mcp.stats

package/src/module.js

@@ -0,0 +1,37 @@
+/**
+  module.js — MCP 协议管道（Nuxt 模块 · 零能力 · 纯 JS）
+
+  职责: 只挂一个出口与一个注入点；本模块不认识任何业务包，能力全靠外部注入。
+
+  装载:
+    nuxt.config.ts: modules: ['@blod-nm/nuxt-mcp']          // 出口 POST /api/mcp
+
+  注入（名字扁平，无 namespace；重名 fail-fast）:
+    // runtime/server/plugins/xxx.js
+    registerMcpTools(() => [{ name, title, description, inputSchema, run }])
+    registerMcpResources(() => [{ uri, name, mimeType, read }])
+    registerMcpPrompts(() => [{ name, description, arguments, render }])
+    registerMcpCompletion(async ({ ref, argument }) => string[])
+
+  数据流:
+    POST /api/mcp → server/discover / tools.* / resources.* / prompts.* / completion.* → 注册表执行 → MCP 结果
+*/
+import { defineNuxtModule, addServerHandler, addServerImports, createResolver } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  meta: { name: 'nuxt-mcp', configKey: 'mcp' },
+  defaults: { route: '/api/mcp' },
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
+    addServerHandler({ route: options.route, method: 'post', handler: resolve('../runtime/server/api/mcp.post.js') })
+    // 注入面只暴露注册函数；能力注册表本身不出模块
+    const from = resolve('../runtime/server/utils/mcp.js')
+    addServerImports([
+      { name: 'registerMcpTools', from },
+      { name: 'registerMcpResources', from },
+      { name: 'registerMcpPrompts', from },
+      { name: 'registerMcpCompletion', from },
+    ])
+    nuxt.options.runtimeConfig.mcp = { route: options.route }
+  },
+})