smart-context-mcp

MCP server that reduces AI agent token usage by up to 90% through intelligent context compression (measured on this project).

What it is

An MCP (Model Context Protocol) server that provides specialized tools for reading, searching, and managing code context efficiently. Instead of loading full files or returning massive search results, it compresses information while preserving what matters for the task.

Real metrics from production use:

• ~7M tokens → ~800K tokens (approximately 89% reduction)
• 1,500+ operations tracked across development
• Compression ratios: 3x to 46x depending on tool
• Context overhead is tracked separately so reports can show gross and net savings

Workflow-level savings:

• Debugging: ~85-90% token reduction
• Code Review: ~85-90% token reduction
• Refactoring: ~85-90% token reduction
• Testing: ~85-90% token reduction
• Architecture: ~85-90% token reduction

Real adoption in non-trivial tasks:

• Approximately 70-75% of complex tasks use devctx tools
• Most used: smart_read (850+ uses), smart_search (280+ uses), smart_shell (220+ uses)
• Primary reasons for non-usage: task too simple, no index built, native tools preferred

See Workflow Metrics and Adoption Metrics for details.

Latest Release: 1.13.0

Major features:

• Auto-build index on first use - Zero-configuration search (bug fixed in v1.12.0)
• Streaming progress notifications for real-time visibility into long-running operations
• Fast path for simple tasks to skip orchestration overhead (3-5x faster)
• Inline metrics display with human-readable summaries in every tool response
• Shared orchestration layer for automatic context management
• 90% token reduction through intelligent compression

See CHANGELOG.md for full release history.

When to Use (and When Not To)

Use devctx when:

• You're exploring an unfamiliar codebase
• The task spans multiple sessions (checkpoints save context)
• You need to understand how files relate to each other (graph/imports)
• The context is too large to manage manually
• You're doing complex multi-file refactors or debugging across layers

Skip devctx when:

• You already know exactly which files to touch
• It's a single-file or surgical change (2-3 edits max)
• You have the full mental map from a recent exploration
• Native tools (Grep, Read, StrReplace) are more direct for the task

Honest verdict from real users:

"The MCP shines in long, multi-session tasks or when you don't know the codebase. For contained refactors where you already know what to touch, native tools are just as fast or faster. The real value was smart_read(outline) for the initial analysis and checkpoints to not lose the thread between sessions."

The 90% token savings are real, but they require the right task type to materialize.

Why it exists

AI agents waste tokens in three ways:

1. Reading full files when they only need structure or specific functions
2. Massive search results with hundreds of irrelevant matches
3. Repeating context across conversation turns

This MCP solves all three by providing tools that return compressed, ranked, and cached context.

🚨 Agent Ignored devctx? → Paste This Next

Use smart-context-mcp for this task.
Start with smart_turn(start), then use smart_context or smart_search before reading full files.
End with smart_turn(end) if you make progress.

Use devctx: smart_turn(start) → smart_context → smart_turn(end)

When to use: Agent

... View full README on GitHub