# @sofagent/mcp

> sofagent MCP Server —— 暴露审计能力给 MCP Client（JSON-RPC 2.0 over stdio）

独立进程，依赖 `@sofagent/audit`。可被 Claude Desktop / Cursor / Continue / 任何 MCP Client 调用。

---

## 安装

```bash
npm install -g @sofagent/mcp
```

或与 MCP 能力一起经伞包安装（npm 通道唯一形态，含完整依赖树）：

```bash
npm install -g sofagent
```

---

## 用法

```bash
# 直接启动 MCP Server
sofagent mcp

# 或通过 audit 包的 --mcp 参数
sofagent audit --mcp
```

MCP Server 通过 stdio 通信（JSON-RPC 2.0）。最小运行时依赖。

---

## MCP Client 配置

```json
{
  "mcpServers": {
    "sofagent": {
      "command": "npx",
      "args": ["-y", "@sofagent/audit", "--mcp"]
    }
  }
}
```

---

## 暴露的 Tools（104 个）

> 🗑️ 浏览器四件套（`playwright_*`）已于 2026-09-26 注销（[v2.0.0 §七 B 表](../../docs/changelog/v2.0/v2.0.0.md) 裁定退役，UI 审计实做窗口已关）——107→103；v1.5.7 章二实现底座（orchestrator 侧 `browser-tools.ts`）一并退役删除（[可行性报告](../../docs/eval/ui-audit-feasibility.md)落盘触发）。

> 完整清单（按域分组 + 每工具说明）见 [docs/API.md](../../docs/API.md)——由 tool-registry.ts 生成，门禁对账永不漂移。

| Tool | 说明 |
|---|---|
| `run_audit` | 对 git diff 跑全量审计规则（A1-A11、A14-A24 + E1-E2/E4-E7，共 28 条——v1.5.7 新增 E5 SMB 数据产物 / E6 提示注入 / E7 决策质量），返回结构化报告 |
| `get_think` | 读取 think.md 最近 N 条反思条目 |
| `write_think` | 向 think.md 追加一条反思记录 |
| `device_register` / `device_list` | G9 设备注册面（v1.4.9）：Ed25519 验签注册 + 清单在线态 |
| `worklog_query` / `cost_query` / `fde_*` / `train_*` / `snapshot_*` / `ontology_*` / `pr_*` / `workflow_*` / `data_push` / … | 其余 103 个——审计/编排/后训/治理/成本/知识/PR 生命周期/workflow CRUD/数据推送各域，见 API.md 分域清单 |

> 注：A12/A13 已在 v0.99.4 合并入 A11（不滥资源），编号不再使用。v1.5.7 章四起 `report_tools --stats --tools` 提供三视图工具使用率（含 `status` 成败与 `durationMs` 耗时——退役决策数据面）。

---

## 角色收窄（SOFAGENT_MCP_ROLES）

专职面部署形态——按角色过滤 tools/list 暴露面，两种配置形态：

```bash
# 形态一：环境变量（进程级）
SOFAGENT_MCP_ROLES=audit sofagent mcp

# 形态二：JSON 配置（客户端级——mcpServers 条目内）
{ "command": "npx", "args": ["-y", "@sofagent/audit", "--mcp"], "env": { "SOFAGENT_MCP_ROLES": "audit" } }
```

多角色逗号分隔（如 `fde,audit`）；缺省 / `all` = 全量暴露。调用未暴露 tool 返回结构化错误（含恢复全量的配置提示）。

### audit 专职面（11 tools）

`SOFAGENT_MCP_ROLES=audit` 时的暴露清单（与 tool-registry `roles` 打标逐项一致——门禁断言防漂移）：

| Tool | 语义 |
|---|---|
| `run_audit` | 全量审计规则跑批（28 条规则 + HMAC 链） |
| `audit_file` | 单文件定点审计（不改链） |
| `audit_query` | 审计数据只读查询（history 三维过滤 + decision 因果链，不写链） |
| `ruleset_export` | 规则集导出（默认规则 + 扩展 → 标准 JSON，双向可逆 + 内容指纹） |
| `search_knowledge` | 审计知识库检索（lessons/规则语料） |
| `read_lessons` | 经验教训条目读取 |
| `data_sovereignty_report` | 数据主权审计报告 |
| `audit_data_change` | 数据变更审计（表/行级追溯） |
| `notify_session` | 会话通知（审计事件面） |
| `list_rules` | 规则清单（28 条——名称/分级/启用态） |
| `audit_trail` | 审计链查询（HMAC 校验 + 时间窗过滤） |

完整文档见主仓库：https://github.com/KongFangXun/sofagent

## License

MIT