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

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

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

# 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):

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

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