内容
# TOMAPE
作为MCP服务器暴露的面向Token优化的多智能体编排。TOMAPE拥有会话状态，在智能体跳转之间压缩上下文，在安全时将工作路由到较小的模型，并报告估计的Token节省。
## 功能特点
- **会话拥有编排器** — 客户端发送任务，而不是完整的转录记录
- **上下文压缩** — 结构化的状态在规划器/工作器/审查器跳转之间（通常压缩3-5倍）
- **动态路由** — 基于规则的小/大模型选择和升级
- **Token指标** — 每次跳转的详细情况和估计的基准节省
- **双重传输** — stdio（Cursor/Claude Desktop）和HTTP（托管团队）
- **API密钥身份验证** — HTTP模式的Bearer令牌身份验证
- **MCP资源** — 检查会话的交接状态和跳转日志
## 快速开始
> 完整教程： **[docs/SETUP.md](docs/SETUP.md)**
### 前置条件
- Python 3.11+
- [uv](https://github.com/astral-sh/uv) （推荐）
### 安装
```bash
git clone https://github.com/sudharsanbabu83/TOMAPE.git
cd TOMAPE
uv sync --extra dev
cp .env.example .env
uv run tomape init-db
```
将您的LLM API密钥添加到 `.env` （参见 [模型配置](#模型配置)）。
### 本地运行（模拟 — 无API密钥）
```powershell
# Windows PowerShell
$env:TOMAPE_MOCK_LLM="1"; uv run tomape serve --transport stdio
```
```bash
# macOS / Linux
TOMAPE_MOCK_LLM=1 uv run tomape serve --transport stdio
```
### 本地运行（实时LLM）
```bash
uv run tomape serve --transport stdio
```
### 运行（HTTP — 托管）
```bash
uv run tomape serve --transport http --port 8080
```
健康检查： `GET http://localhost:8080/health`
## Cursor MCP设置
1. 将示例配置复制到您的项目中：
| 平台 | 模板 |
|----------|----------|
| macOS / Linux | [`examples/cursor-mcp.json`](examples/cursor-mcp.json) |
| Windows | [`examples/cursor-mcp.windows.json`](examples/cursor-mcp.windows.json) |
```bash
mkdir -p .cursor
cp examples/cursor-mcp.json .cursor/mcp.json # 根据您的操作系统进行调整
```
2. 编辑 `.cursor/mcp.json`：
- 将 `cwd` 设置为您的TOMAPE仓库根目录（必需，以便加载配置和 `.env`）
- 在 `env` 中添加 `OPENAI_API_KEY` 或 `ANTHROPIC_API_KEY`
- 在Windows上，如果 `uv` 不在PATH中，请使用 `uv.exe` 的完整路径
3. 重新启动Cursor并确认 `tomape` MCP服务器已连接。
### 示例配置（macOS / Linux）
```json
{
"mcpServers": {
"tomape": {
"command": "uv",
"args": ["run", "tomape", "serve", "--transport", "stdio"],
"cwd": "/path/to/TOMAPE",
"env": {
"OPENAI_API_KEY": "your-key",
"TOMAPE_MOCK_LLM": "0"
}
}
}
}
```
## MCP工具
| 工具 | 描述 |
|------|-------------|
| `submit_task` | 启动会话（`task`, `constraints`, `budget_tokens`, `profile`, `compaction_policy`） |
| `continue_session` | 在不重新发送历史记录的情况下跟进 |
| `get_session_status` | 查询运行/完成/失败状态 |
| `get_result` | 最终输出 + `token_report` |
| `cancel_session` | 终止会话 |
| `get_token_report` | Token指标和节省 |
### MCP资源
| 资源 | 描述 |
|----------|-------------|
| `session://{session_id}/handoff` | 当前的紧凑交接JSON |
| `session://{session_id}/logs` | 每个跳转的截断原始输出 |
### 示例提示（在Cursor中）
```
使用TOMAPE submit_task：总结上下文压缩的好处。预算5000个Token。配置文件economy。
```
```
使用TOMAPE get_result获取会话sess_abc123
```
### Token报告
`get_result` 和 `get_token_report` 返回一个 `token_report`，包含：
- `total_tokens` — 会话中使用的Token
- `budget_tokens` — 会话上限
- `estimated_baseline` — 没有压缩的估计成本
- `savings_percent` — 与基准相比的减少百分比
- `hops[]` — 每个跳转的模型、Token和 `compaction_ratio`
## HTTP API
使用 `Authorization: Bearer <api-key>` 进行身份验证。
```bash
# 列出工具
curl -H "Authorization: Bearer dev-key-change-me" http://localhost:8080/tools
# 提交任务
curl -X POST http://localhost:8080/tools/call \
-H "Authorization: Bearer dev-key-change-me" \
-H "Content-Type: application/json" \
-d '{"name":"submit_task","arguments":{"task":"Classify these items: apple, car, dog","profile":"economy","budget_tokens":5000}}'
```
## Docker
```bash
cd docker
TOMAPE_API_KEYS=dev-key-change-me OPENAI_API_KEY=sk-... docker compose up --build
```
## 配置
- 环境： [.env.example](.env.example)
- 策略： [`config/default.yaml`](config/default.yaml)
### 模型配置
默认模型（OpenAI via LiteLLM）：
| 层级 | 模型 |
|------|-------|
| small | `openai/gpt-4o-mini` |
| large | `openai/gpt-4o` |
通过编辑 `config/default.yaml` 并在 `.env` 中设置匹配的API密钥，切换到Anthropic或任何LiteLLM支持的提供商。
### 配置文件
| 配置文件 | 行为 |
|---------|----------|
| `economy` | 小模型，激进压缩，无升级 |
| `balanced` | 默认小模型，失败时升级 |
| `quality` | 大模型，轻度压缩 |
### 压缩策略
| 策略 | 适用情况 |
|--------|----------|
| `default` | 一般任务 |
| `code-agent` | 编码，文件编辑，测试输出 |
| `research-agent` | 搜索，来源，关键发现 |
## 开发
```bash
uv run pytest
uv run ruff check tomape tests
```
设置 `TOMAPE_MOCK_LLM=1` 以在没有API密钥的情况下运行。
## 架构
```
客户端 → MCP（stdio/HTTP）→ 编排器 → 路由器 → LLM
↓
压缩 → 会话存储 → 指标
```
内部代理： **规划器** → **工作器**（每个步骤）→ **审查器**
## 许可证
MIT
