内容
<p align="center">
<img src="https://raw.githubusercontent.com/irmia2026/irmia_devkit_open/main/logo.png" width="120" alt="Irmia DevKit" />
</p>
<h1 align="center">Irmia DevKit MCP</h1>
<p align="center">
<strong>44种权限注释的AI编码代理开发工具 — 本地传输，无需配置。</strong><br />
<sub>安全编辑 · 语义代码索引 · 文件搜索 · 测试运行 · 系统信息</sub>
</p>
<p align="center">
<a href="https://github.com/irmia2026/irmia_devkit_mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg" /></a>
<a href="#"><img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg" /></a>
<a href="#"><img src="https://img.shields.io/badge/MCP-1.0%2B-green.svg" /></a>
<a href="#"><img src="https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg" /></a>
</p>
<p align="center">
<a href="README.md">English</a> | <a href="README.zh-CN.md">简体中文</a>
</p>
---
`irmia_devkit_mcp` 将 [`irmia_devkit_open`](https://github.com/irmia2026/irmia_devkit_open) 中的44种经过充分测试的开发工具打包成一个独立的 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器。同时，它通过 `reasonix-plugin.json` 声明了配套的 `dev-workflow` 技能，以便支持插件的主机可以一起安装工具和安全编码工作流。任何与MCP兼容的代理 — 如 Claude Code、Cursor、Codex、Windsurf — 都可以将 `safe_edit`、`code_explore`、`rg_search` 等作为一流工具，并具有默认的安全防护。
## 为什么需要这个服务器
| 功能 | 说明 |
|---------|---------------|
| 🔒 **本地传输** | 拒绝非环回HTTP绑定。MCP客户端仍然可以将工具输入和输出发送到其配置的模型提供程序。 |
| ⚡ **零配置** | 包括针对Windows/Linux的验证x86-64搜索二进制文件，然后在其他平台上回退到PATH或纯Python。 |
| 🛡️ **深度防御** | 四层SSRF过滤，自动编辑备份和回滚，每个文件操作都进行统一路径遍历检查。 |
| 🧠 **语义索引** | Python AST + SQLite FTS5 — 符号搜索、调用链和影响分析，毫秒级。 |
| 📦 **44种工具** | 编辑、搜索、测试、代码智能、网络、文件、编码、时间、文本处理、系统信息。 |
| 🌍 **跨平台** | Windows、Linux、macOS，具有平台原生启动器和可执行文件解析。 |
## 快速开始
**要求：** Python ≥ 3.10（在Windows上，安装时勾选 *Add python.exe to PATH* 或安装 `py` 启动器）。启动器调用一个标准库Python启动脚本，它在首次启动时创建项目本地的 `.venv`，并将依赖项安装到其中 — 任何操作都不会影响您的全局站点包。npm命令使用包含的Node启动器，在每个平台上正确定位Python。首次启动时会在插件目录下写入内容，并需要访问PyPI，除非已在该venv中安装了固定的依赖项。
Reasonix用户可以在安装前预览组合的Skill + MCP插件：
```bash
reasonix plugin install https://github.com/irmia2026/irmia_devkit_mcp --dry-run
reasonix plugin install https://github.com/irmia2026/irmia_devkit_mcp --yes
```
原生Reasonix清单在Linux/macOS上有效。Reasonix v1.17.18尚未在Windows上将插件本地的`.cmd` MCP命令包装为`cmd.exe`；Windows用户应使用npm启动器或直接配置`python server.py`。
```bash
git clone https://github.com/irmia2026/irmia_devkit_mcp.git
cd irmia_devkit_mcp
bin/irmia-devkit.sh # Linux/macOS
bin\irmia-devkit.cmd # Windows — 或：npx irmia-devkit-mcp
```
首次启动时，服务器会扫描 `vendor/` 和 PATH 以查找 `rg` / `fd` / `es`，并写入 `~/.irmia/mcp_config.json`。将您的MCP客户端指向启动脚本（或 `server.py`）：
### Cursor — `~/.cursor/mcp.json`
```json
{
"mcpServers": {
"irmia-devkit": {
"command": "python",
"args": ["D:\\path\\to\\irmia_devkit_mcp\\server.py"]
}
}
}
```
### Claude Desktop — `~/.claude/settings.json`
```json
{
"mcpServers": {
"irmia-devkit": {
"command": "python",
"args": ["/path/to/irmia_devkit_mcp/server.py"]
}
}
}
```
### HTTP模式（本地浏览器客户端）
```bash
python server.py --http --port 8000
# → http://127.0.0.1:8000/mcp
```
> ⚠️ `--host` 仅接受 `127.0.0.1` / `localhost` / `::1`。远程绑定在启动时被拒绝 — 这是设计使然，而不是错误。
## 工具概览
| # | 分组 | 工具 |
|---|-------|-------|
| 10 | 🔒 安全编辑 | `safe_edit` `safe_write` `safe_backups` `safe_rollback` `file_patch` `file_preview` `syntax_check` `lint_runner` `test_runner` `multi_edit` |
| 13 | 📂 文件系统 | `safe_read` `es_search` `rg_search` `dir_tree` `dir_list` `file_diff` `file_hash` `file_zip` `file_unzip` `file_move` `file_remove` `disk_info` `config_diff` |
| 6 | 🧠 代码智能 | `code_index` `code_explore` `code_pack` `code_diff_impact` `code_status` `symbol_rename` |
| 3 | 📊 系统信息 | `port_check` `proc_list` `sys_snapshot` |
| 4 | 📝 文本处理 | `html_extract` `json_query` `text_filter` `diff_strings` |
| 5 | 🔧 编码/时间/杂项 | `encode_decode` `time` `db_query` `dep_scan` `uuid_gen` |
| 3 | 🌐 网络 | `http_get` `http_post` `http_download` |
## 捆绑的搜索工具和解析
运行时搜索顺序为：**环境/手动配置 → 验证项目 `vendor/` → PATH → 纯Python回退**。存储库捆绑了针对Windows/Linux的x86-64版本的ripgrep和fd，以及针对Windows的Everything CLI。存档网址、存档哈希、提取成员、许可证和提取文件SHA-256哈希记录在 [`vendor/README.txt`](vendor/README.txt)、[`vendor/SHA256SUMS`](vendor/SHA256SUMS) 和 [`vendor/THIRD_PARTY_LICENSES.txt`](vendor/THIRD_PARTY_LICENSES.txt) 中；打包测试固定了每个提取的哈希。对于macOS、ARM和其他不支持的目标，自动使用PATH或Python回退。
```json
// ~/.irmia/mcp_config.json （自动生成，用户可编辑）
{
"es_path": "D:\\path\\to\\irmia_devkit_mcp\\vendor\\es.exe",
"rg_path": "D:\\path\\to\\irmia_devkit_mcp\\vendor\\rg.exe",
"fd_path": "D:\\path\\to\\irmia_devkit_mcp\\vendor\\fd.exe",
"backup_dir": "C:\\Users\\...\\.irmia\\backups"
}
```
| 工具 | Windows | Linux / macOS | 无外部依赖 |
|------|---------|---------------|------------------------|
| `es_search` | Everything CLI（需要Everything服务） | `locate` → `fd` → Python回退 | Python `os.walk` |
| `rg_search` | ripgrep | ripgrep | 纯Python扫描器 |
优先级：环境变量（`IRMIA_ES_PATH`、`IRMIA_RG_PATH`、`IRMIA_FD_PATH`、`IRMIA_BACKUP_DIR`）→ 手动 `mcp_config.json` 值 → 自动扫描 → 内置默认值。
## 安全模型
| 层 | 机制 |
|-------|-----------|
| 编辑 | 备份 → 替换 → 语法检查 → 失败回滚 |
| 网络 | SSRF深度防御：方案允许列表、IP范围阻止列表、DNS答案固定、代理绕过和每次重定向重新验证 |
| SQL | `db_query` 只读，SELECT/PRAGMA允许列表，参数化查询 |
| 路径 | `..` 遍历拒绝 + 规范前缀验证 + 文件系统根，用户主目录和系统目录阻止列表 |
| 部署 | 启动时拒绝非本地主机绑定 |
| 启动 | 源/插件启动器可以创建 `.venv`，从PyPI安装固定的直接依赖项，并在 `~/.irmia/` 下写入检测到的工具配置 |
### 所需功能和数据流
该服务器设计上具有强大的功能。根据所选工具的不同，它可以读取、创建、覆盖、移动、存档或删除本地文件；执行测试和lint子进程；检查进程、端口、磁盘和系统元数据；以及进行出站HTTP请求或下载。MCP模式明确标记了只读、变异、破坏性和开放世界工具，以便兼容的主机可以应用适当的审批策略。工具结果返回给MCP客户端，并可能传输到由该客户端配置的模型提供程序。
## 文档
| 文档 | 内容 |
|----------|----------|
| [ARCHITECTURE.md](ARCHITECTURE.md) | 项目布局、数据流、设计决策 |
| [CHANGELOG.md](CHANGELOG.md) | 版本历史（Keep a Changelog） |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 添加工具、返回值约定、安全检查清单 |
| [LICENSE](LICENSE) | AGPL-3.0 |
| [vendor/THIRD_PARTY_LICENSES.txt](vendor/THIRD_PARTY_LICENSES.txt) | 捆绑搜索二进制文件的许可证 |
## 常见问题
**它与 `irmia_devkit_open` 有什么关系？**
`irmia_devkit_mcp` 是MCP打包版本。工具实现从上游同步；服务器独立运行，无需AstrBot。
**我需要安装什么？**
Python ≥ 3.10。启动器将 `requirements.txt` 中的确切版本安装到项目本地虚拟环境中。捆绑的搜索二进制文件加速了支持的x86-64系统，但从不要求。
**我可以在共享服务器上部署它吗？**
不可以 — 按设计。服务器仅绑定到localhost，每个文件工具都在其运行的机器上操作。共享部署将泄露主机路径和文件内容。
## 许可证
AGPL-3.0 © irmia2026
