opencode-skills-doctor 0.3.5 → 0.3.7

package/README.md

@@ -89,9 +89,11 @@ skills-doctor update --into .\team-skills
 ```
 
 - The output directory is a real OpenCode skill directory, so **`check` picks the update up immediately**;
+- Overwrites files in place and **deletes files that the new version no longer lists** (no stale leftovers from the old version);
 - Writes `.skills-doctor.lock.json` (schema v2: a sha1 for every file);
 - `check` reads that lock: shows managed versions, detects hand edits (`managed-drift`) and missing files (`managed-missing`);
-- Running `update` again re-downloads drifted files (self-healing).
+- Running `update` again re-downloads drifted files (self-healing);
+- Use `--prune` to delete skills that disappeared from the catalog (by default they are reported but kept).
 
 ## Configuration
 
@@ -155,6 +157,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

@@ -89,9 +89,11 @@ skills-doctor update --into .\team-skills
 ```
 
 - 落盘位置就是 opencode 的 skill 目录 → **更新完 `check` 立刻能检测到**；
+- 原地覆盖文件，并**删除新版本里已不存在的文件**（不会残留旧版本文件）；
 - 写 `.skills-doctor.lock.json`（v2：记录每个文件的 sha1）；
 - `check` 会读这个 lock：显示托管版本、发现文件被手改（`managed-drift`）、文件被删（`managed-missing`）；
-- 再跑一次 `update` 会自动重下被改坏的文件（drift 自愈）。
+- 再跑一次 `update` 会自动重下被改坏的文件（drift 自愈）；
+- 用 `--prune` 删除 catalog 中已下架的 skill（默认只提示、不删）。
 
 ## 配置
 
@@ -155,6 +157,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.7",
+  "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/catalog.mjs

@@ -68,6 +68,20 @@ function lockEntryVersion(entry) {
   return null
 }
 
+function pruneEmptyDirs(dir, stopDir) {
+  const stop = path.resolve(stopDir)
+  let current = path.resolve(dir)
+  while (current !== stop && current.startsWith(stop + path.sep)) {
+    try {
+      if (fs.readdirSync(current).length > 0) return
+      fs.rmdirSync(current)
+    } catch {
+      return
+    }
+    current = path.dirname(current)
+  }
+}
+
 /** 本地文件是否仍与 lock 里的哈希一致（无哈希时视为一致）。 */
 function filesMatch(into, name, files, t) {
   if (!files || typeof files !== "object") return true
@@ -93,14 +107,27 @@ export async function fetchCatalogIndex(url, { fetchImpl = fetch, timeoutMs = 15
  * 更新器：对比 HTTP catalog 的 version，必要时下载到 into 目录并写 lock。
  * lock 里记录每个文件的 sha1，检测器据此判断「更新后是否被改过」。
  */
-export async function updateCatalogs(catalogs, { into = process.cwd(), checkOnly = false, fetchImpl = fetch, t = translator("en") } = {}) {
+export async function updateCatalogs(
+  catalogs,
+  { into = process.cwd(), checkOnly = false, fetchImpl = fetch, t = translator("en"), prune = false } = {},
+) {
   const lockPath = path.join(into, LOCK_NAME)
   const lock = readLockFile(into) ?? { version: LOCK_VERSION, catalogs: {} }
   const lockTooNew = Number(lock.version ?? 1) > LOCK_VERSION
   const results = []
 
   for (const catalog of catalogs) {
-    const result = { url: catalog.url, error: null, updated: [], unchanged: [], invalid: [], files: 0 }
+    const result = {
+      url: catalog.url,
+      error: null,
+      updated: [],
+      unchanged: [],
+      invalid: [],
+      orphaned: [],
+      pruned: [],
+      removedFiles: [],
+      files: 0,
+    }
     try {
       const { base, skills } = await fetchCatalogIndex(catalog.url, { fetchImpl, t })
       const baseUrl = new URL(base + "/")
@@ -144,10 +171,43 @@ export async function updateCatalogs(catalogs, { into = process.cwd(), checkOnly
           hashes[file] = sha1Buffer(buffer)
           result.files++
         }
+
+        // 新版本里已被删除的文件：从本地清掉，避免旧文件残留
+        if (prevHashes) {
+          for (const oldFile of Object.keys(prevHashes)) {
+            if (entry.files.includes(oldFile)) continue
+            const target = resolveInside(path.join(into, entry.name), oldFile, t)
+            if (!fs.existsSync(target)) continue
+            fs.rmSync(target, { force: true })
+            result.removedFiles.push({ name: entry.name, file: oldFile })
+            pruneEmptyDirs(path.dirname(target), path.join(into, entry.name))
+          }
+        }
+
         nextSkills[entry.name] = { version, files: hashes }
         result.updated.push({ name: entry.name, version, previous: previousVersion, reason: drifted ? "drift" : null })
       }
 
+      const validNames = new Set(
+        skills.filter((entry) => validateCatalogEntry(entry, t).length === 0).map((entry) => entry.name),
+      )
+      const orphaned = Object.keys(previousSkills).filter((name) => !validNames.has(name))
+      result.orphaned = orphaned
+
+      if (!checkOnly) {
+        if (prune) {
+          for (const name of orphaned) {
+            const dir = resolveInside(into, name, t)
+            if (!fs.existsSync(dir)) continue
+            fs.rmSync(dir, { recursive: true, force: true })
+            result.pruned.push(name)
+          }
+        } else {
+          // 不 prune 时保留 lock 记录，方便下次继续跟踪
+          for (const name of orphaned) nextSkills[name] = previousSkills[name]
+        }
+      }
+
       if (!checkOnly) lock.catalogs[catalog.url] = { skills: nextSkills }
     } catch (err) {
       result.error = String(err?.message ?? err)

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)
@@ -52,12 +55,13 @@ function parseArgs(argv) {
     hide: [],
     into: null,
     checkOnly: false,
+    prune: false,
     help: false,
     version: false,
   }
 
   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()
   }
@@ -109,6 +113,9 @@ function parseArgs(argv) {
       case "--check-only":
         options.checkOnly = true
         break
+      case "--prune":
+        options.prune = true
+        break
       case "-h":
       case "--help":
         options.help = true
@@ -296,11 +303,12 @@ async function runUpdate(discovered, options, cwd, t) {
   const { lockPath, results, lockTooNew } = await updateCatalogs(discovered.catalogs, {
     into,
     checkOnly: options.checkOnly,
+    prune: options.prune,
     t,
   })
 
   if (options.json) {
-    console.log(JSON.stringify({ lockPath, checkOnly: options.checkOnly, results }, null, 2))
+    console.log(JSON.stringify({ lockPath, checkOnly: options.checkOnly, prune: options.prune, results }, null, 2))
     return results.some((r) => r.error) ? 1 : 0
   }
 
@@ -326,6 +334,12 @@ async function runUpdate(discovered, options, cwd, t) {
     }
     if (result.unchanged.length) console.log(dim(t("update.unchanged", { count: result.unchanged.length })))
     if (result.files) console.log(dim(t("update.files", { count: result.files })))
+    if (result.removedFiles.length) console.log(dim(t("update.removedFiles", { count: result.removedFiles.length })))
+    if (result.pruned.length) {
+      console.log(yellow(t("update.pruned", { count: result.pruned.length, names: result.pruned.join(", ") })))
+    } else if (result.orphaned.length) {
+      console.log(yellow(t("update.orphaned", { count: result.orphaned.length })))
+    }
     for (const invalid of result.invalid) {
       console.log(yellow(t("update.skipped", { name: invalid.name, problems: invalid.problems.join("; ") })))
     }
@@ -425,6 +439,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)
@@ -25,6 +26,7 @@ Options:
   --hide <ids>         fix: hide skills with metadata.opencode/autoinvoke: false (comma separated)
   --into <dir>         update: output directory (default: .opencode/skills)
   --check-only         update: only report available updates
+  --prune              update: delete skills that disappeared from the catalog
   -h, --help           show this help
   -v, --version        print version
 
@@ -68,6 +70,9 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "update.files": "  · files written {count}",
     "update.skipped": "  ! skipped {name}: {problems}",
     "update.empty": "  · catalog is empty",
+    "update.removedFiles": "  · removed {count} stale files",
+    "update.pruned": "  · pruned {count} skills no longer in the catalog: {names}",
+    "update.orphaned": "  ! {count} skills are no longer in the catalog (use --prune to delete them)",
     "update.lock": "  lock: {path} ({name})",
     "update.lockTooNew": "  ! lock is newer than this tool; parsed in compatibility mode (unknown fields ignored)",
     "update.detector": "  check now sees these skills ({dir} is where opencode reads)",
@@ -151,6 +156,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>        以该目录为工作目录（默认当前目录）
@@ -166,6 +172,7 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
   --hide <ids>        fix: 给指定 skill 加 metadata.opencode/autoinvoke: false（逗号分隔）
   --into <dir>        update 的落盘目录（默认 .opencode/skills）
   --check-only        update 只报告可用更新，不下载
+  --prune             update: 删除 catalog 中已移除的 skill
   -h, --help          帮助
   -v, --version       版本
 
@@ -209,6 +216,9 @@ Exit codes: 0 ok; 1 errors (and warnings with --strict); 2 bad arguments or runt
     "update.files": "  · 写入文件 {count}",
     "update.skipped": "  ! 跳过 {name}: {problems}",
     "update.empty": "  · catalog 为空",
+    "update.removedFiles": "  · 删除旧版本残留文件 {count} 个",
+    "update.pruned": "  · 清理 catalog 中已移除的 skill {count} 个: {names}",
+    "update.orphaned": "  ! {count} 个 skill 已不在 catalog 中（加 --prune 可删除本地残留）",
     "update.lock": "  lock: {path}（{name}）",
     "update.lockTooNew": "  ! lock 版本比本工具新，已按兼容模式解析（未知字段忽略）",
     "update.detector": "  check 现在可以直接检测到这些 skill（{dir} 是 opencode 会读取的目录）",

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 }
+}