内容
# 观察者
透明的MCP代理，用于代理的可观察性。
观察者位于您的MCP客户端（Claude Desktop、Cline、Goose、Codex等）和实际的MCP服务器之间。它记录每个工具调用到SQLite数据库，并通过额外的MCP工具公开跟踪历史记录，这样您就可以清楚地看到您的代理正在执行什么操作。
## 为什么
在8个主要的人工智能代理社区（MCP、Codex、Cline、Goose、Anthropic SDK、OpenAI Python）中进行的1665次讨论中，#1的 recurring 问题是代理的可观察性。没有人可以查看他们的代理实际正在执行什么操作。没有标准的方法来跟踪代理操作、工具调用或决策。
观察者解决了这个问题。
## 功能
- **透明代理** - 替换任何MCP服务器。您的客户端不知道它正在与代理通信。
- **工具调用记录** - 每个工具调用都记录了输入、输出、持续时间、错误状态和令牌估计。
- **跟踪工具** - 公开4个额外的MCP工具用于查询历史记录：
- `trace.history` - 列出最近的工具调用
- `trace.stats` - 使用情况统计信息，包含每个工具的详细分析
- `trace.search` - 通过工具调用历史记录进行搜索
- `trace.replay` - 按ID重放以前的工具调用
- **工具过滤** - 从客户端隐藏工具以减少令牌开销（解决了研究中发现的第二大问题，即工具膨胀）。
- **SQLite存储** - 所有数据都存储在本地的SQLite数据库中。没有外部依赖。
- **零配置** - 一个二进制文件，一个环境变量指向您的上游服务器。
## 快速入门
```bash
# 安装
go install github.com/valtors/observer@latest
# 运行（包装任何MCP服务器）
OBSERVER_TARGET="npx -y @modelcontextprotocol/server-filesystem /tmp" observer
```
或与Claude Desktop一起使用：
```json
{
"mcpServers": {
"filesystem": {
"command": "observer",
"env": {
"OBSERVER_TARGET": "npx -y @modelcontextprotocol/server-filesystem /tmp"
}
}
}
}
```
或与Cline / Goose / 任何MCP客户端 - 只需将服务器命令替换为`observer`，并将`OBSERVER_TARGET`设置为原始命令。
## 配置
所有配置都通过环境变量进行：
| 变量 | 描述 | 默认值 |
|---|---|---|
| `OBSERVER_TARGET` | 运行上游MCP服务器的命令（必需） | - |
| `OBSERVER_DB_PATH` | SQLite数据库路径 | `~/.observer/trace.db` |
| `OBSERVER_LOG_LEVEL` | 日志级别：debug、info、warn、error | `info` |
| `OBSERVER_MAX_TOOLS` | 向客户端公开的最大工具数量（0 = 所有） | `0` |
| `OBSERVER_FILTER` | 以逗号分隔的要隐藏的工具名称 | - |
| `OBSERVER_RAW_PAYLOAD` | 设置为1，以在跟踪响应中包含原始输入/输出 | `0` |
| `OBSERVER_REDACT_PATTERNS` | 以逗号分隔的模式，用于在存储前进行编辑 | - |
## 工作原理
```
MCP客户端（Claude、Cline等）
|
| JSON-RPC over stdio
|
观察者（此代理）
|-- 记录每个工具调用到SQLite数据库
|-- 将跟踪工具注入tools/list响应
|-- 可选地过滤工具以减少令牌开销
|
| JSON-RPC over stdio
|
上游MCP服务器（文件系统、git等）
```
观察者会使用MCP协议在两侧进行通信。它会拦截`initialize`、`tools/list`和`tools/call`以添加日志记录和跟踪工具。所有其他请求都会透明地传递。
## 跟踪工具
观察者会在`tools/list`响应中注入4个额外的工具。这些工具在本地处理，永远不会转发到上游服务器。
默认情况下，跟踪工具只返回**元数据**（工具名称、时间戳、持续时间、错误状态、输入/输出的SHA-256哈希值）。这可以防止旧工具结果中的机密或提示注入泄漏回模型的上下文。设置`OBSERVER_RAW_PAYLOAD=1`，以在跟踪响应中包含原始输入/输出。
跟踪工具**默认情况下按会话范围** - 它们只返回当前观察者会话的调用。传递显式的`session_id`以查询不同的会话。
### trace.history
```json
{"name": "trace.history", "arguments": {"limit": 10}}
```
返回当前会话的最近N次工具调用，包含元数据、持续时间和时间戳。
### trace.stats
```json
{"name": "trace.stats", "arguments": {}}
```
返回当前会话的总调用次数、唯一工具、错误计数、平均持续时间和每个工具的详细分析。
### trace.search
```json
{"name": "trace.search", "arguments": {"query": "filesystem", "limit": 20}}
```
通过工具名称、输入或输出内容搜索当前会话的工具调用历史记录。
### trace.replay
```json
{"name": "trace.replay", "arguments": {"call_id": 42}}
```
按ID检索以前的工具调用，以进行比较或调试。
## 数据库架构
三个表：
- `tool_calls` - 每次工具调用，包含输入、输出、持续时间、错误状态
- `sessions` - MCP会话，包含客户端/服务器信息
- `tool_registry` - 已发现的工具，包含可见性标志和调用计数
所有数据都存储在本地。没有任何数据离开您的机器。
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。我们欢迎各种形式的贡献 - 错误修复、新跟踪工具、过滤策略、传输支持、文档。
适合新手的问题被标记为`good first issue`。我们有一份AI代理贡献指南，适用于使用AI编码工具的贡献者。
## 许可证
MIT
