@yottameta/yotta-dev-mcp 0.0.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## v0.1.1 (2026-09-25)
+
+- 品牌改名：对外显示名统一为「元开（yotta-dev-mcp）」，不再把功能描述「开发能力 MCP」当产品名。
+- 功能与 12 个工具保持不变；协议、参数、输出与 0.1.0 兼容。
+
+## v0.1.0 (2026-09-25)
+
+- 首个本地候选：MCP 双时代协议内核（2026-07-28 modern + 2025-11-25 legacy）。
+- 十二个确定性工具：`repo_map` / `find_code` / `compress_output` /
+  `review_code` / `review_diff` / `mcp_doctor` / `scan_secrets` /
+  `scan_dependencies` / `check_publish_readiness` / `run_checks` /
+  `scaffold_skill` / `workflow_state`。
+- Python 3.8+ 标准库实现；离线默认运行；输出带证据、排序稳定。
+- `run_checks` 默认关闭执行；`scaffold_skill` / `workflow_state` 默认只预览。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YottaMeta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,7 @@
+# NOTICE - YottaMeta 品牌声明
+
+「YottaMeta」「元阁」「yotta-dev-mcp」以及本家族各技能名称（yotta-* 前缀）
+是 YottaMeta 的品牌与标识。
+
+本软件以 MIT 许可证开源。派生作品不得继续使用 YottaMeta 或本家族名称作为名称，
+不得暗示派生作品由 YottaMeta 官方维护或认可。

package/README.md

@@ -0,0 +1,76 @@
+<p align="center"><img src="assets/banner.png" alt="YuanKai banner" width="100%"></p>
+<h1 align="center">YuanKai (yotta-dev-mcp)</h1>
+<p align="center"><b>Language</b>: English · <a href="README.zh-CN.md">中文</a></p>
+
+Deterministic local development tools exposed over a stdio MCP server.
+
+## What it does
+
+| Tool | Purpose |
+|---|---|
+| `repo_map` | Map modules, imports and entrypoints in a repository. |
+| `find_code` | Locate symbols and text with bounded results. |
+| `compress_output` | Compress long logs while keeping errors and head/tail context. |
+| `review_code` | Apply deterministic review rules with file, line and evidence. |
+| `review_diff` | Review only added lines in a unified diff. |
+| `mcp_doctor` | Inspect installed skills and MCP JSON configuration files. |
+| `scan_secrets` | Scan for credentials and high-entropy tokens with redacted evidence. |
+| `scan_dependencies` | Check manifests, lockfiles, insecure sources and typosquat suspicion. |
+| `check_publish_readiness` | Check version alignment, release files and package metadata. |
+| `run_checks` | Run whitelisted tests, lint or compile checks; execution is explicit. |
+| `scaffold_skill` | Plan or create a minimal skill scaffold; dry-run by default. |
+| `workflow_state` | Read `.workflow` and optionally append an explicit log entry. |
+
+The first nine tools are read-only; `run_checks` requires `allow_execute=true`, and
+`scaffold_skill` / `workflow_state` require `apply=true` before writing. Python 3.8+
+standard library is sufficient; no network access is required.
+
+## Install
+
+### Start the MCP server
+
+```bash
+npx -y @yottameta/yotta-dev-mcp
+```
+
+### Install the skill payload
+
+```bash
+npx -y @yottameta/yotta-dev-mcp --agent codex
+npx -y @yottameta/yotta-dev-mcp --dir <skill-directory>
+npx -y @yottameta/yotta-dev-mcp --list
+```
+
+The installer uses explicit targets. `--global` additionally requires `--yes`, and
+`--dry-run` prints the target without writing.
+
+Other installation methods:
+
+```bash
+git clone https://github.com/YottaMeta/yotta-dev-mcp.git <skill-directory>/yotta-dev-mcp
+bash <skill-directory>/yotta-dev-mcp/install.sh --agent codex
+```
+
+You can also use GitHub's **Download ZIP** action and unpack the archive into the
+skill directory.
+
+## Direct CLI
+
+The engine can also be used without MCP:
+
+```bash
+python scripts/dev_engine.py repo-map .
+python scripts/dev_engine.py find-code . "helper"
+python scripts/dev_engine.py review-code .
+python scripts/dev_engine.py mcp-doctor
+```
+
+## Boundaries
+
+- No code execution, no automatic edits, no commits.
+- No network access, no package-existence lookup.
+- Static deterministic findings only; human review remains the final decision.
+
+## Current version
+
+`0.1.0` ships the protocol core and twelve deterministic tools.

package/README.zh-CN.md

@@ -0,0 +1,71 @@
+<p align="center"><img src="assets/banner.png" alt="元开 banner" width="100%"></p>
+<h1 align="center">元开（yotta-dev-mcp）</h1>
+<p align="center"><b>Language</b>: <a href="README.md">English</a> · 中文</p>
+
+把本地、确定性的开发工具做成 stdio MCP server，任何支持 MCP 的客户端接上即可使用。
+
+## 能做什么
+
+| 工具 | 用途 |
+|---|---|
+| `repo_map` | 代码库模块、导入关系与入口点地图。 |
+| `find_code` | 符号与文本定位，结果有数量上限。 |
+| `compress_output` | 压缩长日志，保留错误、错误栈和首尾上下文。 |
+| `review_code` | 规则化代码评审，输出文件、行号、证据与建议。 |
+| `review_diff` | 只评审 unified diff 的新增行。 |
+| `mcp_doctor` | 只读检查技能目录与 MCP JSON 配置。 |
+| `scan_secrets` | 密钥 / 凭据 / 高熵令牌扫描，证据强制脱敏。 |
+| `scan_dependencies` | 依赖清单、lockfile、来源与 typosquat 启发式检查。 |
+| `check_publish_readiness` | 版本对齐、发布文件与包元数据检查。 |
+| `run_checks` | 运行白名单测试 / lint / compile，执行必须显式开启。 |
+| `scaffold_skill` | 规划或生成最小技能脚手架，默认 dry-run。 |
+| `workflow_state` | 读取 `.workflow`，可选显式追加快照日志。 |
+
+前九个工具只读；`run_checks` 必须显式 `allow_execute=true`，`scaffold_skill` /
+`workflow_state` 必须显式 `apply=true` 才写入。核心只用 Python 3.8+ 标准库，默认不联网。
+
+## 安装
+
+### 启动 MCP server
+
+```bash
+npx -y @yottameta/yotta-dev-mcp
+```
+
+### 安装技能载荷
+
+```bash
+npx -y @yottameta/yotta-dev-mcp --agent codex
+npx -y @yottameta/yotta-dev-mcp --dir <技能目录>
+npx -y @yottameta/yotta-dev-mcp --list
+```
+
+安装器只写入显式目标。`--global` 必须同时给 `--yes`；`--dry-run` 只预览不写入。
+
+其他安装方式：
+
+```bash
+git clone https://github.com/YottaMeta/yotta-dev-mcp.git <技能目录>/yotta-dev-mcp
+bash <技能目录>/yotta-dev-mcp/install.sh --agent codex
+```
+
+也可以使用 GitHub 的 **Download ZIP**，解压到技能目录。
+
+## 直接使用 CLI
+
+```bash
+python scripts/dev_engine.py repo-map .
+python scripts/dev_engine.py find-code . "helper"
+python scripts/dev_engine.py review-code .
+python scripts/dev_engine.py mcp-doctor
+```
+
+## 边界
+
+- 不执行代码、不自动改文件、不自动提交。
+- 不联网，不查询公共仓库中包是否存在。
+- 仅做确定性静态判断，最终评审由人负责。
+
+## 当前版本
+
+`0.1.0` 提供协议内核与十二个确定性工具。

package/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: yotta-dev-mcp
+description: 元开（yotta-dev-mcp）—— 本地、确定性的开发工具 MCP，把只读默认的开发能力暴露为 stdio MCP server：repo_map / find_code / compress_output / review_code / review_diff / mcp_doctor / scan_secrets / scan_dependencies / check_publish_readiness / run_checks / scaffold_skill / workflow_state。触发：让 AI 在陌生项目里先做结构盘点、定位代码、评审改动、扫描密钥/依赖、检查发布就绪、运行白名单检查、生成脚手架或读取 .workflow 状态时；或用户说 元开 / 开发能力 MCP / yotta-dev-mcp / 代码库地图 / 代码评审 MCP 等。边界：Python 3.8+ 标准库、离线默认；除 run_checks（显式 allow_execute）与 scaffold_skill / workflow_state 的显式 apply 外均为只读；不上传源码、不自动修改、不提交、不联网查询包是否存在。
+version: 0.1.1
+license: MIT
+---
+
+# 元开（yotta-dev-mcp）
+
+元开（YuanKai）把一组本地、确定性的开发工具做成一个 stdio MCP server。任何支持 MCP 的客户端接上后，
+都能在真实开发任务里调用这些工具；输出带文件、行号、规则和证据，便于直接进入修复清单。
+
+## 何时使用
+
+- 接手陌生项目：先 `repo_map` 看模块、依赖和入口，再 `find_code` 定位。
+- 评审改动：`review_diff` 只看新增行；`review_code` 对文件或仓库做规则检查。
+- 长日志 / 长命令输出：`compress_output` 保错误、错误栈和首尾上下文。
+- 本机排查：`mcp_doctor` 只读检查技能目录和 MCP JSON 配置。
+
+## MCP 接入
+
+启动命令：
+
+```bash
+npx -y @yottameta/yotta-dev-mcp
+```
+
+或直接用本地脚本：
+
+```bash
+python scripts/yotta_dev_mcp.py
+```
+
+自动接入说明：AI 首次协助配置时，必须先展示目标配置文件、完整配置片段和影响，
+并获得用户明确同意后再写入 `mcpServers`。用户拒绝时不要写文件，直接提供上面的启动命令
+让用户手动接入。
+
+## 工具
+
+| 工具 | 用途 | 写入 |
+|---|---|---|
+| `repo_map` | 模块、导入、入口点地图 | 否 |
+| `find_code` | 符号 / 文本定位，结果有上限 | 否 |
+| `compress_output` | 保留错误与首尾的长输出压缩 | 否 |
+| `review_code` | 规则化代码评审，带行号与建议 | 否 |
+| `review_diff` | 只评审 diff 的新增行 | 否 |
+| `mcp_doctor` | 技能版本与 MCP JSON 配置体检 | 否 |
+| `scan_secrets` | 密钥 / 凭据 / 高熵令牌扫描（强制脱敏） | 否 |
+| `scan_dependencies` | 依赖清单、lockfile、来源与 typosquat 启发式检查 | 否 |
+| `check_publish_readiness` | 版本四件、发布文件、仓库与 publishConfig 检查 | 否 |
+| `run_checks` | 白名单测试 / lint / compile 并返回结构化摘要 | 仅显式 allow_execute |
+| `scaffold_skill` | 生成最小技能脚手架，默认 dry-run | 仅显式 apply |
+| `workflow_state` | 读取 `.workflow`，可选显式追加日志 | 仅显式 apply |
+
+详细契约见 `references/tools.md`。
+
+## 边界
+
+- `run_checks` 是唯一会执行项目代码的工具，默认关闭，必须显式 `allow_execute=true`；只运行白名单检查。
+- `scaffold_skill` / `workflow_state` 默认只预览，显式 `apply=true` 才写入；写入前做原子替换并保留 `.bak`。
+- 不联网，不查询包是否存在于公共仓库。
+- 不读取或修改 YottaCode 仓库。
+- 结论是确定性静态判断，不替代人工评审与最终决策。
+
+## 当前版本
+
+- v0.1.1：品牌显示名统一为「元开」；功能与 12 个工具不变。

package/bin/install.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * yotta-dev-mcp installer.
+ *
+ * Safe defaults:
+ *   --agent <name>  install to one agent's user-level skill directory
+ *   --dir <path>    install to an explicit skill directory
+ *   --list          print the supported agent directory map
+ *   --global        install to all known user-level directories, requires --yes
+ *   --dry-run       print the target without writing
+ */
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SKILL_NAME = 'yotta-dev-mcp';
+const PKG_ROOT = path.join(__dirname, '..');
+const AGENT_DIRS = {
+  claude: { label: 'Claude Code', dirs: ['.claude/skills'] },
+  cursor: { label: 'Cursor', dirs: ['.cursor/skills', '.agents/skills'] },
+  codex: { label: 'Codex', dirs: ['.codex/skills'] },
+  gemini: { label: 'Gemini CLI', dirs: ['.gemini/skills', '.agents/skills'] },
+  goose: { label: 'Goose', dirs: ['.config/goose/skills', '.agents/skills'] },
+  amp: { label: 'Amp', dirs: ['.config/agents/skills', '.agents/skills'] },
+  opencode: { label: 'OpenCode', dirs: ['.config/opencode/skills'] },
+  windsurf: { label: 'Windsurf', dirs: ['.codeium/windsurf/skills'] },
+  workbuddy: { label: 'WorkBuddy', dirs: ['.workbuddy/skills'] },
+  kiro: { label: 'Kiro', dirs: ['.kiro/skills'] },
+  trae: { label: 'Trae Code CLI', dirs: ['.traecli/skills'] },
+  'trae-cn': { label: 'Trae IDE', dirs: ['.trae-cn/skills'] },
+  qwen: { label: 'Qwen Code', dirs: ['.qwen/skills'] },
+  comate: { label: 'Comate', dirs: ['.comate/skills'] },
+  codebuddy: { label: 'CodeBuddy Code', dirs: ['.codebuddy/skills'] },
+  kimi: { label: 'Kimi Code CLI', dirs: ['.kimi/skills'] },
+  agents: { label: 'AGENTS.md', dirs: ['.agents/skills'] },
+};
+
+function codexUserDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'skills');
+}
+
+function opencodeUserDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'opencode', 'skills');
+}
+
+function resolveUserDir(rel) {
+  if (rel === '.codex/skills') return codexUserDir();
+  if (rel === '.config/opencode/skills') return opencodeUserDir();
+  return path.join(os.homedir(), rel);
+}
+
+function shouldSkip(name) {
+  return name === 'package.json' || name === 'bin' || name === 'node_modules' ||
+    name === '.git' || name === '__pycache__' || name.indexOf('test_') === 0 ||
+    name.endsWith('.pyc') || name.endsWith('.pyo');
+}
+
+function copyDir(source, target) {
+  fs.mkdirSync(target, { recursive: true });
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    if (shouldSkip(entry.name)) continue;
+    const sourcePath = path.join(source, entry.name);
+    const targetPath = path.join(target, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(sourcePath, targetPath);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(sourcePath, targetPath);
+    }
+  }
+}
+
+function installTo(directory, dryRun) {
+  const target = path.join(directory, SKILL_NAME);
+  if (dryRun) {
+    console.log('[dry-run] install -> ' + target);
+    return;
+  }
+  copyDir(PKG_ROOT, target);
+  console.log('installed -> ' + target);
+}
+
+function displayDir(rel) {
+  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
+  return '~/' + rel;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const dryRun = args.indexOf('--dry-run') !== -1;
+  const yes = args.indexOf('--yes') !== -1 || args.indexOf('-y') !== -1;
+  const list = args.indexOf('--list') !== -1 || args.indexOf('-l') !== -1;
+  const global = args.indexOf('-g') !== -1 || args.indexOf('--global') !== -1;
+  const dirIndex = args.indexOf('--dir');
+  const agentIndex = args.indexOf('--agent');
+  const explicitDir = dirIndex !== -1 ? args[dirIndex + 1] : null;
+  const agent = agentIndex !== -1 ? String(args[agentIndex + 1]).toLowerCase() : null;
+
+  if (list) {
+    for (const [key, value] of Object.entries(AGENT_DIRS)) {
+      console.log('  ' + key.padEnd(10) + value.label.padEnd(18) +
+        value.dirs.map(displayDir).join(', '));
+    }
+    return;
+  }
+  if (explicitDir) {
+    installTo(explicitDir, dryRun);
+    return;
+  }
+  if (agent) {
+    const info = AGENT_DIRS[agent];
+    if (!info) {
+      console.error('Unknown agent: ' + agent + '. Use --dir <path>.');
+      process.exitCode = 2;
+      return;
+    }
+    installTo(resolveUserDir(info.dirs[0]), dryRun);
+    return;
+  }
+  if (global) {
+    if (!yes) {
+      console.error('Refusing --global without --yes. Use --dry-run to preview.');
+      process.exitCode = 2;
+      return;
+    }
+    const seen = new Set();
+    for (const value of Object.values(AGENT_DIRS)) {
+      for (const rel of value.dirs) {
+        if (seen.has(rel)) continue;
+        seen.add(rel);
+        installTo(resolveUserDir(rel), dryRun);
+      }
+    }
+    return;
+  }
+  console.error('Choose --agent <name>, --dir <path>, or --list. Use --global --yes explicitly.');
+  process.exitCode = 2;
+}
+
+main();

package/bin/yotta-dev-mcp.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * yotta-dev-mcp launcher.
+ *
+ * Default: start the stdio MCP server.
+ * Install flags: delegate to bin/install.js.
+ */
+'use strict';
+const { spawn, spawnSync } = require('child_process');
+const path = require('path');
+
+const PKG_ROOT = path.join(__dirname, '..');
+const SERVER = path.join(PKG_ROOT, 'scripts', 'yotta_dev_mcp.py');
+const INSTALL_FLAGS = ['--agent', '--dir', '--list', '-l', '-g', '--global', '--dry-run', '--yes'];
+
+function isInstallRequest(args) {
+  return args.some(function (item) {
+    if (INSTALL_FLAGS.indexOf(item) !== -1) return true;
+    return item.indexOf('--agent=') === 0 || item.indexOf('--dir=') === 0;
+  });
+}
+
+function findPython() {
+  const candidates = [];
+  if (process.env.YOTTA_MCP_PYTHON) candidates.push(process.env.YOTTA_MCP_PYTHON);
+  candidates.push('python3', 'python', 'py');
+  for (let i = 0; i < candidates.length; i++) {
+    try {
+      const result = spawnSync(candidates[i], ['--version'], { encoding: 'utf8', timeout: 5000 });
+      if (result.status === 0) return candidates[i];
+    } catch (error) {
+      // Try the next candidate.
+    }
+  }
+  return 'python';
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.indexOf('--version') !== -1 || args.indexOf('-v') !== -1) {
+    process.stdout.write(require(path.join(PKG_ROOT, 'package.json')).version + '\n');
+    return;
+  }
+  if (isInstallRequest(args)) {
+    require(path.join(__dirname, 'install.js'));
+    return;
+  }
+  const python = findPython();
+  const child = spawn(python, [SERVER].concat(args), { stdio: 'inherit' });
+  child.on('exit', function (code) { process.exit(code || 0); });
+  child.on('error', function (error) {
+    process.stderr.write('yotta-dev-mcp: cannot start Python MCP server: ' + error.message + '\n');
+    process.exit(1);
+  });
+}
+
+main();

package/install.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+case "$(uname -s)" in
+  MINGW*|MSYS*) SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)" ;;
+esac
+
+exec node "$SOURCE_DIR/bin/install.js" "$@"

package/package.json

@@ -1,23 +1,48 @@
 {
   "name": "@yottameta/yotta-dev-mcp",
-  "version": "0.0.0",
-  "description": "Placeholder package for Trusted Publisher setup.",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
+  "version": "0.1.1",
+  "description": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, find_code, compress_output, review_code, review_diff, mcp_doctor, scan_secrets, scan_dependencies, check_publish_readiness, run_checks, scaffold_skill and workflow_state. Python 3.8+ standard library, offline by default; writes and command execution require explicit flags.",
   "license": "MIT",
-  "type": "commonjs",
+  "keywords": [
+    "agent-skills",
+    "yottaskills",
+    "mcp",
+    "developer-tools",
+    "code-review"
+  ],
+  "files": [
+    "SKILL.md",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "install.sh",
+    "server.json",
+    "references",
+    "scripts",
+    "assets",
+    "bin",
+    "!scripts/test_*.py",
+    "!**/__pycache__",
+    "!**/*.pyc",
+    "!**/*.pyo"
+  ],
   "repository": {
+    "type": "git",
     "url": "git+https://github.com/YottaMeta/yotta-dev-mcp.git"
   },
   "publishConfig": {
     "access": "public"
   },
-  "bugs": {
-    "url": "https://github.com/YottaMeta/yotta-dev-mcp/issues"
+  "bin": {
+    "yotta-dev-mcp": "bin/yotta-dev-mcp.js",
+    "yotta-dev-mcp-install": "bin/install.js"
+  },
+  "scripts": {
+    "test": "python scripts/test_dev_engine.py && python scripts/test_yotta_dev_mcp.py"
   },
-  "homepage": "https://github.com/YottaMeta/yotta-dev-mcp#readme"
+  "engines": {
+    "node": ">=18"
+  }
 }

package/references/tools.md

@@ -0,0 +1,111 @@
+# Tool contracts
+
+All tools are local, deterministic and read-only in v0.1.0.
+
+## repo_map
+
+Input:
+
+- `path` (required): repository or source directory.
+- `max_files` (optional, default 2000): source file limit.
+
+Output: `root`, `modules`, `imports`, `entrypoints`, `truncated`.
+
+## find_code
+
+Input:
+
+- `path` (required): repository, directory or file.
+- `query` (required): symbol or text.
+- `extensions` (optional): file extensions such as `.py`.
+- `max_results` (optional, default 100).
+- `context_lines` (optional, 0-5).
+
+Output: `query`, `matches` (`path`, `line`, `kind`, `text`, `context`), `truncated`.
+
+## compress_output
+
+Input:
+
+- `text` or `file` (one required).
+- `max_chars` (optional, default 4000).
+- `head_lines` / `tail_lines` (optional).
+
+Output: text plus `original_lines`, `kept_lines`, `error_lines`, `truncated`.
+
+## review_code
+
+Input:
+
+- `path` or `text` (one required).
+- `max_findings` (optional, default 200).
+
+Rules: bare-except, eval-exec, shell-true, debug-print, todo-comment,
+mutable-default.
+
+Each finding contains `path`, `line`, `rule`, `severity`, `evidence`, `suggestion`.
+
+## review_diff
+
+Input:
+
+- `diff_text` or `path` (one required).
+- `base` (optional git revision when `path` is used).
+- `max_findings` (optional).
+
+Only added lines are reviewed. Output: `files`, `findings`, `truncated`.
+
+## mcp_doctor
+
+Input:
+
+- `skills_dirs` (optional array).
+- `config_paths` (optional array).
+
+Output: `skills`, `mcp_configs`, `issues`, `checked_skills`, `checked_configs`.
+
+## scan_secrets
+
+Input: `path` or `text`, optional `max_findings`, optional `include_git_history`
+(bounded, default false).
+
+Output: `findings` with `path`, `line`, `rule`, `severity`, redacted `evidence`,
+`suggestion`; `truncated`.
+
+## scan_dependencies
+
+Input: `path`.
+
+Output: `manifests`, `lockfiles`, `issues` (`missing-lockfile`,
+`unpinned-dependency`, `insecure-source`, `local-dependency`,
+`typosquat-suspicion`), and counts. Offline heuristics only.
+
+## check_publish_readiness
+
+Input: `path`.
+
+Output: `ok`, `files`, `versions` (package / skill / changelog / engine when
+present), `issues`.
+
+## run_checks
+
+Input: `kind` (`python-unittest` / `pytest` / `python-compile` / `npm-test` /
+`npm-lint`), `cwd`, optional `timeout`, explicit `allow_execute=true`.
+
+Output: `exit_code`, `passed`, bounded `summary`, compressed `output`,
+`timed_out`.
+
+## scaffold_skill
+
+Input: `name`, `output_dir`, optional `description`, explicit `apply=true`.
+
+Output: `target`, `files`, `applied`. Default is dry-run; existing non-empty
+targets are rejected.
+
+## workflow_state
+
+Input: `root`, `action` (`read` / `append-log` / `append-file`), optional
+`date`, `text`, `file`, explicit `apply=true`.
+
+Output: `ok`, `files`, `missing`, `excerpts` for read; `target`, `applied`,
+`preview` for writes. Writes are atomic and keep a `.bak` of an existing file.