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

Quick Start

Prerequisites

• Python 3.11+
• uv (recommended)

Install

cd TOMAPE
uv sync --extra dev
cp .env.example .env
tomape init-db

Run (stdio — for Cursor)

TOMAPE_MOCK_LLM=1 tomape serve --transport stdio

Run (HTTP — hosted)

TOMAPE_MOCK_LLM=1 tomape serve --transport http --port 8080

Health check: GET http://localhost:8080/health

Cursor MCP Config

{
  "mcpServers": {
    "tomape": {
      "command": "uv",
      "args": ["run", "tomape", "serve", "--transport", "stdio"],
      "env": {
        "ANTHROPIC_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

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

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"}}'

Docker

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

Configuration

• Environment: see .env.example
• Policies: config/default.yaml

Profiles

Profile	Behavior
economy	Small models, aggressive compaction
balanced	Small default, escalate on failure
quality	Large models, light compaction

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