@yottameta/yotta-dev-mcp-plugin 0.0.0 → 0.1.1

package/.agents/plugins/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "name": "yotta-dev-mcp",
+  "interface": {
+    "displayName": "元开 yotta-dev-mcp (YottaMeta)"
+  },
+  "plugins": [
+    {
+      "name": "yotta-dev-mcp",
+      "source": ".",
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools",
+      "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.",
+      "interface": {
+        "displayName": "元开 yotta-dev-mcp",
+        "shortDescription": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, find_code, compress_ou",
+        "developerName": "YottaMeta",
+        "category": "Developer Tools"
+      }
+    }
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "name": "yotta-dev-mcp",
+  "interface": {
+    "displayName": "元开 yotta-dev-mcp (YottaMeta)"
+  },
+  "plugins": [
+    {
+      "name": "yotta-dev-mcp",
+      "source": ".",
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools",
+      "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.",
+      "interface": {
+        "displayName": "元开 yotta-dev-mcp",
+        "shortDescription": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, find_code, compress_ou",
+        "developerName": "YottaMeta",
+        "category": "Developer Tools"
+      }
+    }
+  ]
+}

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/README.md

@@ -0,0 +1,107 @@
+# 元开 yotta-dev-mcp — Agent Plugin
+
+YuanKai (yotta-dev-mcp): deterministic local development tools over stdio MCP, covering code map, review, secret/dependency scan, release checks, whitelisted checks, scaffold and workflow state.
+
+[English](#english) | [中文](#中文)
+
+## English
+
+This repository is a standalone [Agent Plugins 1.0](https://agent-plugins.org) plugin. It packages one skill and one MCP server in the standard layout (`plugin.json`, `skills/`, `mcp.json`).
+
+### Install
+
+#### Codex (verified)
+
+```bash
+codex plugin marketplace add YottaMeta/yotta-dev-mcp-plugin
+codex plugin add yotta-dev-mcp@yotta-dev-mcp
+```
+
+#### Other compatible clients
+
+Agent Plugins defines the package format, not a universal installer command. Use your client’s official setup instructions:
+
+| Client | Setup instructions |
+| --- | --- |
+| VS Code | [Agent Plugins in VS Code](https://code.visualstudio.com/docs/agent-customization/agent-plugins) |
+| Cursor | [Cursor plugins](https://cursor.com/docs/plugins) |
+| GitHub Copilot | [About plugins](https://docs.github.com/en/copilot/concepts/agents/about-plugins) |
+| ChatGPT & Codex | [OpenAI plugins](https://developers.openai.com/plugins) |
+| Kiro | [Powers](https://kiro.dev/docs/powers/) |
+| Hermes Agent | [Portable Agent Plugins v1 packages](https://hermes-agent.nousresearch.com/docs/developer-guide/plugins#portable-agent-plugins-v1-packages) |
+| OpenClaw | [Plugin bundles](https://docs.openclaw.ai/plugins/bundles) |
+| Grok Bot | [Skills, routines, and automations](https://docs.x.ai/grok-bot/skills-routines-and-automations) |
+| NanoClaw | [Templates](https://github.com/nanocoai/nanoclaw/blob/main/docs/templates.md) |
+
+Codex is verified by YottaMeta. Other clients are linked from the official Agent Plugins compatibility page and are not yet verified here.
+
+### What you get
+
+- **Skill** — `yotta-dev-mcp` skill instructions (`skills/yotta-dev-mcp/SKILL.md`)
+- **MCP server** — started automatically by the client (stdio; requires Python 3.8+)
+
+### Boundaries
+
+- The MCP server runs fully local over stdio; no telemetry, no remote calls from the plugin itself.
+- If the required runtime is missing, the MCP component may fail to start; the skill payload remains available.
+- The skill payload is copied from the source repository release; for full documentation see [YottaMeta/yotta-dev-mcp](https://github.com/YottaMeta/yotta-dev-mcp).
+
+### Source
+
+Upstream skill repository: [YottaMeta/yotta-dev-mcp](https://github.com/YottaMeta/yotta-dev-mcp)
+Plugin repository: [YottaMeta/yotta-dev-mcp-plugin](https://github.com/YottaMeta/yotta-dev-mcp-plugin)
+
+### License
+
+MIT — see `LICENSE` and the license inside the skill payload.
+
+## 中文
+
+本仓库是一个独立的 [Agent Plugins 1.0](https://agent-plugins.org) 插件，按标准目录结构打包一项技能和一个 MCP server（`plugin.json`、`skills/`、`mcp.json`）。
+
+### 安装
+
+#### Codex（已实测）
+
+```bash
+codex plugin marketplace add YottaMeta/yotta-dev-mcp-plugin
+codex plugin add yotta-dev-mcp@yotta-dev-mcp
+```
+
+#### 其他兼容客户端
+
+Agent Plugins 只定义包格式，不定义统一安装命令。请按你所用客户端的官方说明接入：
+
+| 客户端 | 官方说明 |
+| --- | --- |
+| VS Code | [Agent Plugins in VS Code](https://code.visualstudio.com/docs/agent-customization/agent-plugins) |
+| Cursor | [Cursor plugins](https://cursor.com/docs/plugins) |
+| GitHub Copilot | [About plugins](https://docs.github.com/en/copilot/concepts/agents/about-plugins) |
+| ChatGPT & Codex | [OpenAI plugins](https://developers.openai.com/plugins) |
+| Kiro | [Powers](https://kiro.dev/docs/powers/) |
+| Hermes Agent | [Portable Agent Plugins v1 packages](https://hermes-agent.nousresearch.com/docs/developer-guide/plugins#portable-agent-plugins-v1-packages) |
+| OpenClaw | [Plugin bundles](https://docs.openclaw.ai/plugins/bundles) |
+| Grok Bot | [Skills, routines, and automations](https://docs.x.ai/grok-bot/skills-routines-and-automations) |
+| NanoClaw | [Templates](https://github.com/nanocoai/nanoclaw/blob/main/docs/templates.md) |
+
+Codex 已由 YottaMeta 实测；其他客户端仅链接官方说明，尚未在本仓库逐项实测。
+
+### 内容
+
+- **技能** — `yotta-dev-mcp` 技能指令（`skills/yotta-dev-mcp/SKILL.md`）
+- **MCP server** — 由客户端自动启动（stdio；需要 Python 3.8+）
+
+### 边界
+
+- MCP server 完全本地 stdio 运行；插件本身不做遥测、不发起远程调用。
+- 若运行时缺失，MCP 组件可能启动失败；技能内容仍可使用。
+- 技能内容来自源仓库发布版；完整文档见 [YottaMeta/yotta-dev-mcp](https://github.com/YottaMeta/yotta-dev-mcp)。
+
+### 来源
+
+上游技能仓库：[YottaMeta/yotta-dev-mcp](https://github.com/YottaMeta/yotta-dev-mcp)
+插件仓库：[YottaMeta/yotta-dev-mcp-plugin](https://github.com/YottaMeta/yotta-dev-mcp-plugin)
+
+### 许可证
+
+MIT — 见 `LICENSE` 与技能目录内许可证。

package/mcp.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "yotta-dev-mcp": {
+      "type": "stdio",
+      "command": "python",
+      "args": [
+        "${PLUGIN_ROOT}/skills/yotta-dev-mcp/scripts/yotta_dev_mcp.py"
+      ]
+    }
+  }
+}

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "@yottameta/yotta-dev-mcp-plugin",
-  "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) Agent Plugin: deterministic local development tools over stdio MCP.",
   "license": "MIT",
-  "type": "commonjs",
   "repository": {
+    "type": "git",
     "url": "git+https://github.com/YottaMeta/yotta-dev-mcp-plugin.git"
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "files": [
+    ".agents",
+    ".claude-plugin",
+    "LICENSE",
+    "README.md",
+    "mcp.json",
+    "plugin.json",
+    "skills"
+  ]
 }

package/plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "yotta-dev-mcp",
+  "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.",
+  "author": {
+    "name": "YottaMeta",
+    "url": "https://github.com/YottaMeta"
+  },
+  "homepage": "https://github.com/YottaMeta/yotta-dev-mcp-plugin",
+  "repository": "https://github.com/YottaMeta/yotta-dev-mcp-plugin",
+  "license": "MIT",
+  "keywords": [
+    "yottameta",
+    "agent-plugins",
+    "agent-skills",
+    "mcp",
+    "yotta-dev-mcp"
+  ]
+}

package/skills/yotta-dev-mcp/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/skills/yotta-dev-mcp/NOTICE

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

package/skills/yotta-dev-mcp/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/skills/yotta-dev-mcp/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/skills/yotta-dev-mcp/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.