Content
# TOMAPE
Token-optimized multi-agent orchestration exposed as an MCP server. TOMAPE owns session state, compacts context between agent hops, routes work to smaller models when safe, and reports estimated token savings.
## Features
- **Session-owning orchestrator** — clients send tasks, not full transcripts
- **Context compaction** — structured handoff state between planner/worker/reviewer hops (typically 3–5× compression)
- **Dynamic routing** — rule-based small/large model selection with escalation
- **Token metrics** — per-hop breakdown and estimated baseline savings
- **Dual transport** — stdio (Cursor/Claude Desktop) and HTTP (hosted teams)
- **API key auth** — Bearer token authentication for HTTP mode
- **MCP resources** — inspect handoff state and hop logs per session
## Quick Start
> Full walkthrough: **[docs/SETUP.md](docs/SETUP.md)**
### Prerequisites
- Python 3.11+
- [uv](https://github.com/astral-sh/uv) (recommended)
### Install
```bash
git clone https://github.com/sudharsanbabu83/TOMAPE.git
cd TOMAPE
uv sync --extra dev
cp .env.example .env
uv run tomape init-db
```
Add your LLM API key to `.env` (see [Model configuration](#model-configuration)).
### Run locally (mock — no API key)
```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
```
### Run locally (live LLM)
```bash
uv run tomape serve --transport stdio
```
### Run (HTTP — hosted)
```bash
uv run tomape serve --transport http --port 8080
```
Health check: `GET http://localhost:8080/health`
## Cursor MCP Setup
1. Copy an example config into your project:
| Platform | Template |
|----------|----------|
| 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 # adjust for your OS
```
2. Edit `.cursor/mcp.json`:
- Set `cwd` to your TOMAPE repo root (required so config and `.env` load)
- Add `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` in `env`
- On Windows, use the full path to `uv.exe` if `uv` is not on PATH
3. Restart Cursor and confirm the `tomape` MCP server is connected.
### Example config (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 Tools
| Tool | Description |
|------|-------------|
| `submit_task` | Start a session (`task`, `constraints`, `budget_tokens`, `profile`, `compaction_policy`) |
| `continue_session` | Follow-up without resending history |
| `get_session_status` | Poll running/completed/failed status |
| `get_result` | Final output + `token_report` |
| `cancel_session` | Abort a session |
| `get_token_report` | Token metrics and savings |
### MCP Resources
| Resource | Description |
|----------|-------------|
| `session://{session_id}/handoff` | Current compact handoff JSON |
| `session://{session_id}/logs` | Truncated raw output per hop |
### Example prompts (in Cursor)
```
Use TOMAPE submit_task: summarize the benefits of context compaction. Budget 5000 tokens. Profile economy.
```
```
Use TOMAPE get_result for session sess_abc123
```
### Token report
`get_result` and `get_token_report` return a `token_report` with:
- `total_tokens` — tokens used in the session
- `budget_tokens` — session cap
- `estimated_baseline` — estimated cost without compaction
- `savings_percent` — reduction vs baseline
- `hops[]` — per-hop model, tokens, and `compaction_ratio`
## HTTP API
Authenticate with `Authorization: Bearer <api-key>`.
```bash
# List tools
curl -H "Authorization: Bearer dev-key-change-me" http://localhost:8080/tools
# Submit task
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
```
## Configuration
- Environment: [`.env.example`](.env.example)
- Policies: [`config/default.yaml`](config/default.yaml)
### Model configuration
Default models (OpenAI via LiteLLM):
| Tier | Model |
|------|-------|
| small | `openai/gpt-4o-mini` |
| large | `openai/gpt-4o` |
Switch to Anthropic or any LiteLLM-supported provider by editing `config/default.yaml` and setting the matching API key in `.env`.
### Profiles
| Profile | Behavior |
|---------|----------|
| `economy` | Small models, aggressive compaction, no escalation |
| `balanced` | Small default, escalate on failure |
| `quality` | Large models, light compaction |
### Compaction policies
| Policy | Best for |
|--------|----------|
| `default` | General tasks |
| `code-agent` | Coding, file edits, test output |
| `research-agent` | Search, sources, key findings |
## Development
```bash
uv run pytest
uv run ruff check tomape tests
```
Set `TOMAPE_MOCK_LLM=1` to run without API keys.
## Architecture
```
Client → MCP (stdio/HTTP) → Orchestrator → Router → LLM
↓
Compaction → Session Store → Metrics
```
Internal agents: **Planner** → **Worker** (per step) → **Reviewer**
## License
MIT
