Skip to main content
Glama

CI PyPI version License: MIT Python


⚑ Overview

distill-mcp-v2 is a high-performance, network-dependency-free Python FastMCP server designed to aggressively optimize Large Language Model (LLM) context windows. It provides specialized tools for compressing and analyzing massive AI‑agent payloads without losing critical semantic information.

By filtering noise, stabilizing cache prefixes, and running multi-model token cost estimations locally, Distill v2 dramatically reduces API costs and preserves LLM reasoning abilities when dealing with heavy payloads like infinite logs, monolithic API schemas, and multi-agent war room transcripts.

Related MCP server: Context Engine

πŸš€ Performance & Token Compression

Our rigorous, independent stress-testing benchmarks (audited via pytest and chaos blueprints) prove that distill-mcp-v2 achieves up to 99.7% token compression while retaining 100% of the crucial context.

Scenario

Payload Profile

Raw Tokens

Distilled Tokens

Savings %

Trace Avalanche

Heavy Java Stacktraces

150,027

546

99.6%

Schema Monolith

Massive Microservice JSON

56,588

1,355

97.6%

Incident War Room

Multi-Agent Chat Logs

117,952

371

99.7%

(Tested against Claude-3-Opus budgets. Scenario 1 reduced costs from $2.25/call to $0.008/call.)

Read the full Benchmark & Execution Report for deeper insights.

πŸ›  Features & Toolset

Distill v2 exposes 8 precise tools to agents via the Model Context Protocol:

  1. distill_json β€” Compresses raw JSON payloads, retaining anomalies, exceptions, and errors.

  2. distill_logs β€” Compresses raw .log files, preserving head/tail contexts and stack traces.

  3. distill_schema β€” Compacts massive MCP tool catalogs and JSON schemas to structural parameters.

  4. distill_response β€” Progressively prunes, minifies, and truncates outputs to fit strict token budgets.

  5. distill_conversation β€” Extracts goals, decisions, blockers, and actions from multi-agent transcripts without leaking raw ISO timestamps.

  6. stabilize_for_cache β€” Maps chaotic raw identifiers (UUIDs, hex IDs) to sequential placeholders to stabilize LLM prompt caching.

  7. analyze_tokens β€” Accurately estimates token counts using tiktoken (cl100k_base).

  8. compare β€” Computes detailed diffs and cost-savings analyses between raw and distilled payloads.

πŸ“¦ Quick Start

Installation

Distill v2 requires Python 3.10+. We recommend using uv or pip in an isolated virtual environment.

# Clone the repository
git clone https://github.com/yatinkoul/distill.git
cd distill

# Create a virtual environment and activate it
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

Running the Server

Run the FastMCP server, which natively binds to a stateless HTTP endpoint.

# Run the FastMCP server (default host: 0.0.0.0, port: 8000)
distill --host 0.0.0.0 --port 8000
# Or using uvicorn directly:
.venv/bin/uvicorn src.main:app --host 0.0.0.0 --port 8000

The server exposes a JSON‑RPC endpoint at http://localhost:8000/mcp.

πŸ§ͺ Stress Testing & Development

The repository ships with an exhaustive stress-test runner that dynamically allocates ports, executes deterministic payload scenarios, and validates the integrity of the distilled outputs.

To run the complete test suite (118/118 passing):

# Install development dependencies
pip install -e ".[dev]"

# Run the test suite
pytest

To manually execute the stress-testing blueprints and regenerate the benchmark report:

python stress_tests_blueprints/run_blueprints.py

πŸ“– Documentation

🀝 Contributing

Contributions, issues, and feature requests are welcome! Please read our CONTRIBUTING.md (coming soon) for guidelines on how to propose improvements. Ensure all tests and linting (ruff) pass before submitting pull requests.

πŸ“œ License

This project is licensed under the MIT License – see the LICENSE file for details.

Available Tools

8 tools
analyze_tokensA

Count tokens using model-aware tokenizers and estimate API costs across multiple configured models.

Inputs: text (required), model.

compareB

Generate comparison metrics (token count reduction, compression ratio, cost savings) between uncompressed and distilled text formats.

Inputs: original (required), distilled (required), model.

distill_conversationA

Extract a high-level briefing (goals, decisions, errors, current state, pending tasks) from a conversational message trace (JSON array or raw text) to fit within a token budget.

Inputs: conversation (required), format, token_budget, focus.

distill_jsonB

Compress JSON structures by collapsing large arrays and metadata while preserving error fields. Supports iterative budget-based compression.

Inputs: json_data (required), preserve_keys, collapse_keys, max_array_samples, +2 more.

distill_logsB

Filter and compress raw logs by preserving startup context, shutdown state, and matching error traces while omitting large blocks of repetitive status messages.

Inputs: log_text (required), keep_head, keep_tail, error_patterns, +2 more.

distill_responseC

Progressively compress any generic tool response (JSON, HTML, or text) to fit within a specific token budget.

Inputs: response_data (required), token_budget (required), content_type, preserve_keys.

distill_schemaA

Reduce token overhead of MCP tool schemas or JSON Schemas. Strips descriptions/examples (compact mode) or collapses to parameter names/types (minimal mode).

Inputs: schema (required), mode, keep_required.

stabilize_for_cacheA

Normalize dynamic elements like UUIDs, timestamps, and hex IDs to sequential placeholders, maximizing provider-level prompt caching hit rates.

Inputs: text (required), stabilize_uuids, stabilize_timestamps, stabilize_hex_ids, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a specific input type or operation: token analysis, comparison, distillation for conversations/JSON/logs/responses/schemas, and cache stabilization. No two tools have overlapping purposes.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun pattern (e.g., distill_conversation, distill_json). The tool 'compare' is a verb-only exception, but it is still clear and fits the domain.

    Tool Count5/5

    With 8 tools, the server covers token analysis, multiple distillation formats, comparison metrics, and cache optimization. This is well-scoped for the stated purpose without being excessive or insufficient.

    Completeness5/5

    The tool surface provides comprehensive coverage for the domain of token optimization and compression: cost estimation, multi-format distillation, schema reduction, and caching normalization. No obvious gaps are evident.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Provides reversible context compression for AI agents, reducing token usage while preserving the ability to retrieve original content, and serves as an MCP server for integration with tools like GitHub Copilot and Claude Code.
      3
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A task-aware context compression layer for Agent workflows, RAG pipelines, and AI Coding assistants, reducing noisy logs, retrieval chunks, and code context into high-signal LLM inputs via CLI, Python SDK, and MCP.
      16 PyPI
      322
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents and MCP-compliant clients to dynamically shrink long-horizon context windows, pruning verbose tool outputs, HTML boilerplate, and semantic redundancy by roughly 40-70% without frontier LLM round-trips. Runs deterministically as a zero-dependency Python stdio server, accepting a payload plus optional compression and risk-bound options.
      7
      -