Tool Reference

Complete reference for all 19 MCP tools provided by ensemble-mcp, grouped by category. Every tool returns the standard response envelope.

Response Envelope

All tools return a JSON object with this structure:

{
  "ok": true,
  "data": { ... },
  "error": null,
  "meta": {
    "duration_ms": 5,
    "source": "sqlite",
    "confidence": "exact"
  }
}

On error:

{
  "ok": false,
  "data": null,
  "error": {
    "code": "VALIDATION_MISSING_FIELD",
    "message": "...",
    "retryable": false,
    "details": { ... }
  },
  "meta": { ... }
}

Tool Categories

Pattern Memory (3 tools)

patterns_search

Search stored patterns by semantic similarity. Returns top-K matches above the minimum score threshold. Increments match_count and updates last_matched_at on returned patterns (used by patterns_prune to identify unused patterns).

Supports progressive disclosure via detail_level and category filtering via category. Results include token_count metadata (approximate token cost of the pattern text).

Response data (detail_level="full"):

{
  "matches": [
    {
      "id": 1,
      "name": "pattern-name",
      "context": "when this applies",
      "approach": "what was done",
      "outcome": "what happened",
      "category": "problem-solution",
      "score": 0.85,
      "token_count": 42
    }
  ]
}

Response data (detail_level="index"):

{
  "matches": [
    {
      "id": 1,
      "name": "pattern-name",
      "category": "problem-solution",
      "score": 0.85,
      "token_count": 42
    }
  ]
}

patterns_store

Store a new pattern from a successful pipeline for future semantic search. The pattern text is embedded using the ONNX model and stored in SQLite.

Response data:

{
  "id": 42,
  "stored": true,
  "category": "problem-solution"
}

patterns_prune

Remove old/unused patterns (zero match_count, older than max_age_days).

Response data:

{
  "pruned": 5,
  "remaining": 42
}

Drift Detection (1 tool)

drift_check

Check if code changes drift from the original task. Embeds both the task description and the diff summary, then computes cosine similarity. Returns a 0–1 score (0 = no drift, 1 = complete drift) with specific flags and a verdict.

Also flags suspicious file changes (migrations, configs, etc.) that don't match the task description.

Response data:

{
  "score": 0.25,
  "similarity": 0.75,
  "flags": ["Unexpected file change: migrations/001.sql"],
  "verdict": "aligned"
}

Verdicts:

• aligned — score < 0.3 (configurable via drift_threshold_aligned)
• minor_drift — score < 0.6 (configurable via drift_threshold_minor)
• significant_drift — score ≥ 0.6

Results are persisted to the drift_history table for dashboard viewing.

Model Routing (1 tool)

model_recommend

Recommend a model tier (best/mid/cheapest) for an agent and task. Uses a rule-based routing table mapping (agent, classification) pairs to tiers.

Response data:

{
  "tier": "best",
  "reason": "Complex task requiring strongest reasoning capability",
  "agent": "craft",
  "classification": "complex"
}

Routing table (built-in agents):

Unknown agents default to mid tier.

Skill Intelligence (3 tools)

skills_discover

Scan tool-native skill locations and return relevant skills via semantic search. Scans these directories:

• .ai/skills/
• .claude/skills/
• .cursor/rules/
• .github/copilot-instructions/
• .opencode/skills/

Uses mtime-based caching — file reads and embedding computation are skipped for unchanged files.

Response data:

{
  "detected": [
    {
      "name": "my-skill",
      "source_tool": "opencode",
      "path": ".opencode/skills/my-skill/SKILL.md",
      "confidence": 0.85
    }
  ],
  "snippets": [
    {
      "content": "First 500 chars of skill content...",
      "relevance": 0.85
    }
  ]
}

skills_suggest

Detect recurring patterns and suggest them as reusable skills. Clusters patterns by embedding similarity (≥ 0.75 threshold) and proposes clusters with ≥ min_cluster_size members as skill suggestions.

Response data:

{
  "suggestions": [
    {
      "id": 1,
      "pattern_ids": [5, 12, 18],
      "theme": "Cluster of 3 similar patterns",
      "confidence": 0.82,
      "proposed_name": "testing-patterns-api",
      "proposed_content": "# testing-patterns-api\n..."
    }
  ],
  "stale_skills": [
    {
      "path": ".ai/skills/old-skill.md",
      "last_matched_at": "2025-01-15T10:00:00",
      "days_unused": 90
    }
  ]
}

skills_generate

Accept, dismiss, or defer a skill suggestion.

Response data (accept):

{
  "generated": true,
  "path": ".ai/skills/testing-patterns-api.md",
  "content": "# testing-patterns-api\n...",
  "status": "accepted"
}

Response data (dismiss/defer):

{
  "generated": false,
  "status": "dismissed"
}

Session Management (3 tools)

session_save

Save pipeline checkpoint state with optimistic versioning. If version is provided, it must match the current database version (otherwise CONFLICT_VERSION_MISMATCH is raised). When original_request is provided, an embedding is generated for semantic search via session_search.

Response data:

{
  "saved": true,
  "version": 3
}

session_load

Load latest or specific pipeline checkpoint.

Response data (found):

{
  "found": true,
  "session_id": "abc-123",
  "state": { ... },
  "version": 3,
  "original_request": "Add user authentication",
  "task_classification": "standard",
  "status": "running",
  "project": "/path/to/project"
}

Response data (not found):

{
  "found": false
}

session_search

Search sessions by semantic similarity. Embeds the query and compares against stored session embeddings using cosine similarity.

Response data:

{
  "matches": [
    {
      "session_id": "abc-123",
      "score": 0.82,
      "version": 3,
      "created_at": "2025-03-15T10:00:00",
      "original_request": "Add user authentication",
      "task_classification": "standard",
      "status": "completed",
      "project": "/path/to/project"
    }
  ]
}

Codebase Indexer (4 tools)

project_index

Build or refresh the codebase index. Scans the filesystem, extracts language, role, exports, and imports for each file. Uses mtime-based incremental indexing.

Ignored directories: node_modules, vendor, .git, __pycache__, .mypy_cache, .ruff_cache, .pytest_cache, dist, build, .next, .nuxt, target, .tox, .venv, venv, env, .env

Ignored extensions: .pyc, .pyo, .so, .dylib, .dll, .exe, .bin, .wasm, .jpg, .jpeg, .png, .gif, .svg, .ico, .woff, .woff2, .ttf, .eot, .mp3, .mp4, .avi, .mov, .zip, .tar, .gz, .lock

project_query

Query the project index — find files by type, path pattern, or semantic query.

project_dependencies

Get the import/dependency graph for a specific file.

project_snapshot

Generate a compact project baseline summary from the codebase index. Returns language, framework, conventions, directory structure, test setup, build tools, and key files. Results are cached with mtime-based invalidation (24-hour expiry).

Context Optimization (2 tools)

context_compress

Compress verbose natural language text into terse, token-efficient form while preserving all technical content (code blocks, URLs, file paths, headings, tables). Rule-based, zero LLM calls.

Response data:

{
  "compressed_text": "Compressed version...",
  "original_tokens": 500,
  "compressed_tokens": 320,
  "savings_pct": 36.0,
  "preserved_count": 15
}

context_prepare

Prepare and order prompt sections for optimal LLM cache hit rates. Sorts sections by priority (static → project → task) to maximize the stable prefix that LLM providers can cache across calls.

Each section object:

Response data:

{
  "prepared_text": "Combined ordered text...",
  "section_count": 3,
  "prefix_stable_bytes": 1024,
  "sections": [
    {
      "name": "system-prompt",
      "priority": "static",
      "original_bytes": 500,
      "prepared_bytes": 480
    }
  ]
}

Utility (2 tools)

health

Server health check — returns status, version, database size, and pattern count.

Response data:

{
  "status": "ok",
  "version": "0.1.0b4",
  "db_size_bytes": 524288,
  "pattern_count": 42,
  "server_name": "ensemble-mcp"
}

reset

Reset all stored data. Destructive — deletes all patterns, sessions, project indexes, drift history, skill suggestions, and idempotency keys.

Response data:

{
  "reset": true
}

Idempotency

All mutating tools accept an optional idempotency_key parameter. When provided:

• The first call executes normally and stores the result keyed by the idempotency key
• Subsequent calls with the same key return the previously stored result without re-executing
• Keys expire after 24 hours (configurable via idempotency_key_ttl_hours)

Next Steps

• Integration Guide — how to use these tools in AI pipelines
• Configuration — customize thresholds and defaults
• Troubleshooting — understanding error codes