内容
# mcp-debugger
> 透明代理，用于 **调试、记录、验证和重放** MCP（模型上下文协议）会话。
[](https://pypi.org/project/mcp-debugger/)
[](https://github.com/sushant-mutnale/mcp-debugger/actions/workflows/ci.yml)
[](https://pypi.org/project/mcp-debugger/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/sushant-mutnale/mcp-debugger/actions)
---
## ✨ 功能特点
| 功能 | 描述 |
|---|---|
| 🔍 **记录** | 捕获MCP客户端和服务器之间的每个JSON-RPC消息 |
| 📋 **检查** | 以语法高亮、格式化的终端输出浏览消息 |
| ✅ **验证** | 检查MCP协议合规性 — 握手顺序、方法名称、模式 |
| 🔄 **重放** | 通过重放记录的会话来回归测试服务器更改 |
| 📊 **统计** | 可视化工具使用情况、延迟趋势和错误率 |
| 🔀 **比较** | 两个会话之间的差异报告（延迟、错误、工具调用） |
| 📤 **导出** | JSON、Markdown或OpenTelemetry（OTLP）跟踪 |
| ⚙️ **配置** | 持久化用户偏好 — 别名、超时、默认值 |
| 🩺 **医生** | 环境诊断 — Python版本、SQLite、Node.js、路径 |
| 🚀 **本地优先** | 无云，无注册 — 所有数据保留在您的机器上 |
---
## 📦 安装
```bash
pip install mcp-debugger
```
可选地，支持OpenTelemetry（OTLP）导出：
```bash
pip install "mcp-debugger[otlp]"
```
**要求：** Python 3.11+，Node.js（用于基于`npx`的MCP服务器）
---
## 🚀 快速入门
### 1. 记录会话
```bash
mcp-debugger proxy \
--server "npx -y @modelcontextprotocol/server-filesystem /tmp" \
--name "my-first-session"
```
与您的MCP客户端（例如Claude Desktop）交互。按`Ctrl+C`停止。
### 2. 列出记录的会话
```bash
mcp-debugger list
```
### 3. 检查会话
```bash
mcp-debugger inspect 1
```
### 4. 验证协议合规性
```bash
mcp-debugger validate --server "npx -y @modelcontextprotocol/server-filesystem /tmp"
```
### 5. 重放会话
```bash
mcp-debugger replay 1 --server "npx -y @modelcontextprotocol/server-filesystem /tmp"
```
### 6. 导出到Markdown
```bash
mcp-debugger export 1 --format markdown --output session-report.md
```
---
## 🔧 与Claude Desktop一起使用
编辑Claude Desktop配置（macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`，Windows：`%APPDATA%\Claude\claude_desktop_config.json`）：
```json
{
"mcpServers": {
"my-filesystem": {
"command": "mcp-debugger",
"args": [
"proxy",
"--server",
"npx -y @modelcontextprotocol/server-filesystem /path/to/dir",
"--name",
"claude-session"
]
}
}
}
```
现在，Claude和您的服务器之间的每个消息都将被透明地记录。
---
## 📖 文档
| 文档 | 描述 |
|---|---|
| [命令参考](docs/commands.md) | 每个CLI命令，包含所有选项和示例 |
| [架构](docs/architecture.md) | 工作原理 — 组件、数据流、序列图 |
| [教程](docs/tutorials.md) | 常见用例的逐步工作流程 |
| [配置](docs/config.md) | 所有配置键、默认值和示例 |
| [FAQ](docs/faq.md) | 常见问题和故障排除 |
| [贡献](docs/contributing.md) | 开发设置、测试结构、PR流程 |
| [变更日志](CHANGELOG.md) | 版本历史 |
---
## 🧪 开发设置
```bash
git clone https://github.com/sushant-mutnale/mcp-debugger.git
cd mcp-debugger
python -m venv .venv
source .venv/bin/activate # Linux/macOS
# 或：.venv\Scripts\activate # Windows
pip install -e ".[dev]"
# 运行所有测试
pytest
# 带有覆盖率
pytest --cov=mcp_debugger --cov-report=term-missing
# lint和类型检查
ruff check .
mypy src/mcp_debugger --ignore-missing-imports
```
---
## 🤝 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取设置说明、编码风格和拉取请求流程。
---
## 📄 许可证
MIT © [Sushant Mutnale](https://github.com/sushant-mutnale)
