opencode-skills-doctor 0.3.5 → 0.3.6

package/README.md

@@ -155,6 +155,32 @@ It registers the same `skills_doctor` tool (1.x has no `/skills-doctor` command
 
 > The package root entry is the V2 plugin and requires OpenCode 2.x. The CLI works on both lines.
 
+## MCP server (Claude Code, Codex, Kimi Code, any MCP client)
+
+`skills-doctor mcp` speaks the Model Context Protocol over stdio and exposes one tool: `skills_doctor` with arguments `directory?`, `budget?`, `lang?` and `global?`. It does not need OpenCode installed.
+
+Claude Code (`.mcp.json` in the project, or your MCP config):
+
+```json
+{
+  "mcpServers": {
+    "skills-doctor": { "command": "npx", "args": ["-y", "opencode-skills-doctor", "mcp"] }
+  }
+}
+```
+
+Codex (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.skills-doctor]
+command = "npx"
+args = ["-y", "opencode-skills-doctor", "mcp"]
+```
+
+Any other MCP client: run `npx -y opencode-skills-doctor mcp` and allow the `skills_doctor` tool.
+
+It scans `.opencode/skills`, `.claude/skills` and `.agents/skills` (project and global), so it can audit skills used by other agents too.
+
 ## Rules
 
 | Rule | Level | Meaning |

package/README.zh-CN.md

@@ -155,6 +155,32 @@ export { SkillsDoctorPlugin } from "opencode-skills-doctor/v1"
 
 > 包根入口是 V2 插件，需要 OpenCode 2.x；CLI 两条线都能用。
 
+## MCP server（Claude Code、Codex、Kimi Code、任何 MCP 客户端）
+
+`skills-doctor mcp` 用 stdio 讲 Model Context Protocol，只暴露一个工具：`skills_doctor`，参数 `directory?`、`budget?`、`lang?`、`global?`。不需要装 OpenCode。
+
+Claude Code（项目里的 `.mcp.json`，或你的 MCP 配置）：
+
+```json
+{
+  "mcpServers": {
+    "skills-doctor": { "command": "npx", "args": ["-y", "opencode-skills-doctor", "mcp"] }
+  }
+}
+```
+
+Codex（`~/.codex/config.toml`）：
+
+```toml
+[mcp_servers.skills-doctor]
+command = "npx"
+args = ["-y", "opencode-skills-doctor", "mcp"]
+```
+
+其他 MCP 客户端：启动 `npx -y opencode-skills-doctor mcp` 并允许 `skills_doctor` 工具即可。
+
+它扫描 `.opencode/skills`、`.claude/skills`、`.agents/skills`（项目和全局），所以其他 agent 用的 skill 也能一起体检。
+
 ## 检测规则
 
 | 规则 | 级别 | 含义 |

package/package.json

@@ -1,7 +1,7 @@
-{
+{
   "name": "opencode-skills-doctor",
-  "version": "0.3.5",
-  "description": "Audit, fix and update OpenCode skills: measure per-step context cost, catch shadowed duplicates, archive safely and sync from catalogs. Works on OpenCode 1.x and 2.x.",
+  "version": "0.3.6",
+  "description": "Audit, fix and update agent skills: per-step context cost, shadowed duplicates, safe archive, catalog sync. CLI, OpenCode plugin and MCP server (Claude Code / Codex / any MCP client).",
   "type": "module",
   "exports": {
     ".": "./src/plugin.mjs",
@@ -40,6 +40,8 @@
   "keywords": [
     "opencode",
     "skills",
+    "agent-skills",
+    "mcp",
     "lint",
     "fix",
     "cli",

package/src/cli.mjs

@@ -7,10 +7,13 @@ import { inspectManaged } from "./managed.mjs"
 import { planFixes, applyFixes, hideSkills } from "./fix.mjs"
 import { auditSkills } from "./audit.mjs"
 import { loadConfig } from "./config.mjs"
+import { startMcpServer } from "./mcp.mjs"
 import { padDisplay } from "./parse.mjs"
 import { detectLang, normalizeLang, translator } from "./i18n.mjs"
 
-const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"))
+const pkg = JSON.parse(
+  fs.readFileSync(new URL("../package.json", import.meta.url), "utf8").replace(/^\uFEFF/, ""),
+)
 
 const color = process.stdout.isTTY && !process.env.NO_COLOR
 const paint = (code, text) => (color ? `\x1b[${code}m${text}\x1b[0m` : text)
@@ -57,7 +60,7 @@ function parseArgs(argv) {
   }
 
   const args = [...argv]
-  const commands = new Set(["check", "scan", "update", "fix", "help"])
+  const commands = new Set(["check", "scan", "update", "fix", "mcp", "help"])
   if (args[0] && commands.has(args[0])) {
     options.command = args.shift()
   }
@@ -425,6 +428,11 @@ export async function main(argv) {
     return
   }
 
+  if (options.command === "mcp") {
+    startMcpServer({ version: pkg.version })
+    return
+  }
+
   if (options.command === "check") {
     const audit = auditSkills({
       cwd,

package/src/i18n.mjs

@@ -10,6 +10,7 @@ Usage:
   skills-doctor scan   [options]   list every skill with its source and precedence
   skills-doctor fix    [options]   archive shadowed definitions (safe structural fixes)
   skills-doctor update [options]   compare and download skills from HTTP catalogs
+  skills-doctor mcp                run as an MCP server (Claude Code, Codex, any MCP client)
 
 Options:
   --root <dir>         working directory (default: current directory)
@@ -151,6 +152,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   skills-doctor scan   [选项]   列出所有 skill 及其来源/优先级
   skills-doctor fix    [选项]   归档被遮蔽的定义（安全的结构性修复）
   skills-doctor update [选项]   对比并拉取 HTTP catalog 里的 skill
+  skills-doctor mcp            以 MCP server 方式运行（Claude Code、Codex 等任何 MCP 客户端）
 
 选项:
   --root <dir>        以该目录为工作目录（默认当前目录）

package/src/mcp.mjs

@@ -0,0 +1,150 @@
+import { auditSkills, formatMarkdown } from "./audit.mjs"
+import { normalizeLang, detectLang } from "./i18n.mjs"
+
+export const PROTOCOL_VERSION = "2025-06-18"
+export const SERVER_NAME = "skills-doctor"
+export const TOOL_NAME = "skills_doctor"
+
+export function toolDefinition() {
+  return {
+    name: TOOL_NAME,
+    description:
+      "Audit local agent skills (OpenCode / Claude Code / .agents): duplicate and shadowed definitions, per-step description token budget, oversized bodies and fix hints. Returns a markdown report.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        directory: {
+          type: "string",
+          description: "Directory to audit (default: the server process working directory)",
+        },
+        budget: {
+          type: "number",
+          description: "Description token budget per model step (default 1200)",
+        },
+        lang: {
+          type: "string",
+          enum: ["en", "zh"],
+          description: "Report language (default: auto from system locale)",
+        },
+        global: {
+          type: "boolean",
+          description: "Include global skill directories such as ~/.config/opencode and ~/.claude (default true)",
+        },
+      },
+      additionalProperties: false,
+    },
+  }
+}
+
+function ok(id, result) {
+  return { jsonrpc: "2.0", id, result }
+}
+
+function fail(id, code, message) {
+  return { jsonrpc: "2.0", id, error: { code, message } }
+}
+
+/** 处理一条 JSON-RPC 消息；通知返回 null。 */
+export async function handleMessage(message, { version = "0.0.0" } = {}) {
+  if (!message || typeof message !== "object" || typeof message.method !== "string") return null
+  const { id, method, params } = message
+  const isNotification = id === undefined || id === null
+
+  try {
+    switch (method) {
+      case "initialize":
+        return ok(id, {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: SERVER_NAME, version },
+        })
+
+      case "notifications/initialized":
+      case "notifications/cancelled":
+        return null
+
+      case "ping":
+        return ok(id, {})
+
+      case "tools/list":
+        return ok(id, { tools: [toolDefinition()] })
+
+      case "resources/list":
+        return ok(id, { resources: [] })
+
+      case "prompts/list":
+        return ok(id, { prompts: [] })
+
+      case "tools/call": {
+        const name = params?.name
+        if (name !== TOOL_NAME) return fail(id, -32602, `unknown tool: ${name}`)
+
+        const args = params?.arguments && typeof params.arguments === "object" ? params.arguments : {}
+        const directory =
+          typeof args.directory === "string" && args.directory.trim() ? args.directory.trim() : process.cwd()
+        const budget = typeof args.budget === "number" && args.budget > 0 ? args.budget : null
+        const lang = normalizeLang(args.lang) ?? detectLang()
+
+        const audit = auditSkills({ cwd: directory, budget, lang, includeGlobal: args.global !== false })
+        return ok(id, { content: [{ type: "text", text: formatMarkdown(audit) }] })
+      }
+
+      default:
+        if (isNotification) return null
+        return fail(id, -32601, `method not found: ${method}`)
+    }
+  } catch (err) {
+    if (isNotification) return null
+    return fail(id, -32603, String(err?.message ?? err))
+  }
+}
+
+/** stdio transport：newline-delimited JSON-RPC（MCP 标准）。 */
+export function startMcpServer({ version, input = process.stdin, output = process.stdout, onExit = () => process.exit(0) } = {}) {
+  let buffer = ""
+  let queue = Promise.resolve()
+
+  const write = (payload) => {
+    output.write(JSON.stringify(payload) + "\n")
+  }
+
+  const handleLine = (line) => {
+    let message
+    try {
+      message = JSON.parse(line)
+    } catch {
+      return
+    }
+    queue = queue
+      .then(() => handleMessage(message, { version }))
+      .then((response) => {
+        if (response) write(response)
+      })
+      .catch((err) => {
+        write(fail(message?.id ?? null, -32603, String(err?.message ?? err)))
+      })
+  }
+
+  input.setEncoding?.("utf8")
+  input.on("data", (chunk) => {
+    buffer += chunk
+    let index
+    while ((index = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, index).trim()
+      buffer = buffer.slice(index + 1)
+      if (line) handleLine(line)
+    }
+  })
+
+  let finished = false
+  const finish = () => {
+    if (finished) return
+    finished = true
+    // 等队列里的异步响应写完再退出，避免管道结束时丢包
+    queue.finally(onExit)
+  }
+  input.on("end", finish)
+  input.on("close", finish)
+
+  return { write, close: finish }
+}