distill-mcp-v2
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@distill-mcp-v2 distill these server logs keeping stack traces"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
β‘ 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:
distill_jsonβ Compresses raw JSON payloads, retaining anomalies, exceptions, and errors.distill_logsβ Compresses raw.logfiles, preserving head/tail contexts and stack traces.distill_schemaβ Compacts massive MCP tool catalogs and JSON schemas to structural parameters.distill_responseβ Progressively prunes, minifies, and truncates outputs to fit strict token budgets.distill_conversationβ Extracts goals, decisions, blockers, and actions from multi-agent transcripts without leaking raw ISO timestamps.stabilize_for_cacheβ Maps chaotic raw identifiers (UUIDs, hex IDs) to sequential placeholders to stabilize LLM prompt caching.analyze_tokensβ Accurately estimates token counts usingtiktoken(cl100k_base).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 8000The 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
pytestTo manually execute the stress-testing blueprints and regenerate the benchmark report:
python stress_tests_blueprints/run_blueprints.pyπ Documentation
Project Goals & Strategy β High-level strategy and milestones.
Benchmark Report β Exhaustive stress-test results.
Testing Infrastructure β Notes on the testing architecture and CI/CD readiness.
π€ 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 toolsanalyze_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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
LLM cost optimization gateway, repo token-waste auditor & model arbitrage MCP server.
MCP server for building and testing AI agents with multi-model experimentation and insights.
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
InfoLang semantic memory MCP β investigate, memorize, and recall compressed agent context.
Related MCP Servers
- AlicenseAqualityCmaintenanceProvides 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.31Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA 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 PyPI322MIT
- AlicenseNot gradedqualityDmaintenanceThis MCP server provides tools to manage, score, compress, and prune AI agent conversation context, helping keep agents focused and reduce token costs. It is a free, local, pure Python solution for any MCP client.MIT
- FlicenseNot gradedqualityBmaintenanceEnables 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-