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

Related MCP server: Headroom Mini

Quick Start

Full walkthrough: docs/SETUP.md

Prerequisites

• Python 3.11+

• uv (recommended)

Install

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).

Run locally (mock — no API key)

# Windows PowerShell
$env:TOMAPE_MOCK_LLM="1"; uv run tomape serve --transport stdio

# macOS / Linux
TOMAPE_MOCK_LLM=1 uv run tomape serve --transport stdio

Run locally (live LLM)

uv run tomape serve --transport stdio

Run (HTTP — hosted)

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
   Windows	examples/cursor-mcp.windows.json

   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)

{
  "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

MCP Resources

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>.

# 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

cd docker
TOMAPE_API_KEYS=dev-key-change-me OPENAI_API_KEY=sk-... docker compose up --build

Configuration

• Environment: .env.example

• Policies: config/default.yaml

Model configuration

Default models (OpenAI via LiteLLM):

Switch to Anthropic or any LiteLLM-supported provider by editing config/default.yaml and setting the matching API key in .env.

Profiles

Compaction policies

Development

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