Metadata-Version: 2.5
Name: traceguard-mcp
Version: 0.1.0
Summary: TraceGuard MCP Server — 让任何 MCP 客户端（Claude Desktop / Cursor / OpenCode）在工具执行前先问一句是否允许
Project-URL: Homepage, https://github.com/ve-loma/traceguard
Project-URL: Repository, https://github.com/ve-loma/traceguard
Project-URL: Issues, https://github.com/ve-loma/traceguard/issues
Author: TraceGuard Contributors
License: MIT
Keywords: ai-agent,claude,cursor,guardrails,mcp,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Provides-Extra: core
Requires-Dist: ai-traceguard>=0.1.0; extra == 'core'
Description-Content-Type: text/markdown

# traceguard-mcp

**TraceGuard MCP Server** —— 让任何支持 MCP 的客户端（Claude Desktop、Cursor、OpenCode、Claude Code）
在执行工具**之前**先问一句「这个动作允许吗」。

零依赖，本地运行，不联网。

## 安装

```bash
pip install traceguard-mcp
# 想用你自己的策略文件，再装核心：
pip install ai-traceguard
```

## 它暴露什么

| 工具 | 作用 |
|---|---|
| `traceguard_check(tool_name, args)` | 判断该工具调用是否被允许，返回 `allowed / risk / reason` |
| `traceguard_report()` | 审计摘要（调用数 / 拦截数 / 链是否完好） |

## 配置到 MCP 客户端

```json
{
  "mcpServers": {
    "traceguard": {
      "command": "traceguard-mcp"
    }
  }
}
```

或用 Python 模块方式：

```json
{
  "mcpServers": {
    "traceguard": {
      "command": "python",
      "args": ["-m", "traceguard_mcp.server"]
    }
  }
}
```

## 环境变量

| 变量 | 说明 |
|---|---|
| `TRACEGUARD_MCP_POLICY` | 策略文件路径（默认 `policies/base.yaml`，需装 ai-traceguard） |
| `TRACEGUARD_MCP_DB` | 审计数据库路径（默认 `traceguard-mcp.db`） |

## 怎么用

在 Agent 的工具分发循环里，**执行任何有副作用的工具之前**先调 `traceguard_check`：

```python
res = mcp_call("traceguard_check", {"tool_name": name, "args": args})
if not res["allowed"]:
    return f"⛔ 被拦下：{res['reason']}"   # 把原因回传给模型
# 放行，执行真实工具
```

> 把 `reason` 回传给模型，它会自己改用安全做法，体验远好于直接报错。

## 实测

```
initialize  -> traceguard v0.1.0（协议 2024-11-05）
tools/list  -> traceguard_check, traceguard_report
check delete_file  -> {"allowed": false, "risk": "HIGH", "reason": "删除文件操作，策略阻断"}
check read_file    -> {"allowed": true,  "risk": "LOW"}
```

## 许可证

MIT
