# AntSword MCP

> [English](README_EN.md) | 中文

> 将蚁剑（AntSword）的能力以 **MCP 服务器** 形式暴露，让任意 MCP 客户端（Claude Desktop / Cursor / Trae / Cline 等）通过一条 SSE URL 即可调用蚁剑的全部 Shell 操作能力。

- **零外部依赖**：仅用 Node 内置模块 + 蚁剑已有的 `antSword.core`
- **协议合规**：实现 MCP 2024-11 SSE 规范
- **非破坏性**：纯插件形态，不修改蚁剑核心源码
- **安全**：仅监听 `127.0.0.1` + Host/Origin 头校验

---

## 安装

1. 关闭蚁剑
2. 将本目录拷贝到蚁剑插件目录：`<蚁剑工作目录>/antData/plugins/AntSwordMCP/`
3. 启动蚁剑

## 激活服务

**方式 A：手动激活（默认）**

右键 Shell 列表中任意 Shell → 选择 **AntSword MCP 服务器**，服务即在 `http://127.0.0.1:30080/sse` 监听。每次重启蚁剑后需再次激活。

**方式 B：自启动（可选）**

在蚁剑源码 `source/app.entry.js` 末尾追加：

```javascript
try {
  const mcpPlugPath = path.join(remote.process.env.AS_WORKDIR, 'antData/plugins/AntSwordMCP');
  if (fs.existsSync(path.join(mcpPlugPath, 'package.json'))) {
    require(path.join(mcpPlugPath, 'index.js'));
  }
} catch (e) { console.error('[AntSwordMCP] autoload failed:', e); }
```

## 客户端配置

```json
{
  "mcpServers": {
    "antsword": {
      "url": "http://127.0.0.1:30080/sse"
    }
  }
}
```

支持 Claude Desktop / Cursor / Trae 等所有 MCP 客户端。端口被占用时自动重试（最多 10 次）。

---

## 工具列表

共 **37 个工具**，分为七大类。`shell_id` 由 `shell_list` 返回的 `_id` 获取。

| 类别 | 工具 |
|------|------|
| **Shell 管理** (6) | `shell_list` `shell_get` `shell_add` `shell_edit` `shell_del` `shell_capabilities` |
| **基础信息** (2) | `base_info` `base_probedb` |
| **命令执行** (3) | `cmd_exec` `cmd_list` `cmd_quote` |
| **文件管理** (13) | `file_dir` `file_read` `file_write` `file_delete` `file_copy` `file_rename` `file_retime` `file_chmod` `file_mkdir` `file_wget` `file_hash` `file_upload` `file_download` |
| **数据库** (8) | `db_list_confs` `db_get_conf` `db_add_conf` `db_del_conf` `db_show_databases` `db_show_tables` `db_show_columns` `db_query` |
| **通用接口** (1) | `raw_request` |
| **系统管理** (4) | `mcp_status` `mcp_logs` `mcp_config_get` `mcp_config_set` |

> 各工具的详细参数与说明已内置于工具描述中，AI 通过 `tools/list` 即可获取，无需查阅文档。

### 典型调用流程

```
shell_list → shell_capabilities → base_info → cmd_exec / file_dir / db_query
```

---

## 已知限制

### 中文多段路径下 filemanager 操作失效

当路径**同时**含中文目录段 + 中文文件名时，`file_write` 新建、`file_copy`、`file_delete`、`file_dir` 元数据可能失效。单段中文不受影响。

**绕过方案**：改用 `cmd_exec` 执行系统命令（`rd /s /q`、`copy`、`rm -rf` 等），命令解释器不受此限制。

### 蚁剑重启后需重新激活

蚁剑重启会销毁 MCP 服务，需右键 Shell 重新激活（或使用自启动方式 B）。

---

## 配置

默认配置见 `config.default.json`（host=127.0.0.1, port=30080）。可在蚁剑控制台执行 `antSword.storage('mcp-config-path', '/path/to/config.json')` 指定自定义配置。

---

## License

[MIT](LICENSE)

## Disclaimer

本工具仅供授权安全测试使用。使用前须获得目标系统的书面授权，使用者自行承担因不当使用造成的一切法律责任。