Context-MCP

<div align="center">

Intelligent Context Manager for AI Coding Assistants

Hierarchical semantic compression that remembers what matters

Installation • Quick Start • Features • CLI • API

</div>

---

The Problem

AI coding assistants forget your project context with every new conversation. You waste time re-explaining architecture, decisions, and patterns.

The Solution

Context-MCP provides a 3-level memory system that intelligently manages what the AI remembers:

┌─────────────────────────────────────────┐
│  CORE (~500 tokens)                     │
│  Always loaded • Key decisions          │
│  Architecture • Critical patterns       │
├─────────────────────────────────────────┤
│  ACTIVE (~2000 tokens)                  │
│  Current work context                   │
│  Related modules • Recent changes       │
├─────────────────────────────────────────┤
│  ARCHIVE (unlimited)                    │
│  Full history • Searchable              │
│  Auto-retrieved when relevant           │
└─────────────────────────────────────────┘

Installation

# Clone the repository
git clone https://github.com/vshavlidze/context-mcp.git
cd context-mcp

# Install dependencies
npm install

# Build
npm run build

# Run tests (optional)
npm test

Quick Start

1. Add to your MCP configuration

Create or edit .mcp.json in your project:

{
  "mcpServers": {
    "context": {
      "command": "node",
      "args": ["/path/to/context-mcp/dist/index.js"]
    }
  }
}

2. Start using context tools

In your AI assistant, use these tools:

context_get     → Load project context at conversation start
context_add     → Save important decisions/patterns
context_search  → Find specific information
context_focus   → Set current work area

3. Or use the CLI

# Interactive terminal interface
npm run cli
# or after npm link:
ctx

Features

Intelligent Compression

• Automatic summarization of large contexts
• Token-aware storage (~500 tokens for core)
• Semantic relevance scoring

Auto-Management

• Auto-archive: Old, low-relevance entries move to archive
• Auto-promote: Frequently accessed entries rise to active
• Smart caching: LRU cache with TTL for fast retrieval

Multi-language Support

• English and Russian interfaces
• Language selection on startup
• Localized prompts and messages

Prompt Templates

• Store reusable prompts in prompts/ folder
• Variable substitution ({code}, {problem})
• Categorized templates (coding, review, debug, docs)

Full-Text Search

• SQLite FTS5 powered search
• Search across all context levels
• Relevance-ranked results

CLI Commands

Command	Description
/get	Load project context
/add	Add new context entry
/search	Search context
/list	List entries by level
/delete	Delete an entry
/focus	Set current work focus
/import	Import from file
/prompts	Browse prompt templates
/stats	Show statistics
/health	System health check
/export	Export to JSON/Markdown
/lang	Change language
/help	Show all commands

API (MCP Tools)

context_get

Load project context. Use at conversation start.

{
  include_active?: boolean  // Include ACTIVE level (default: true)
  focus_categories?: string[] // Filter by categories
}

context_add

Add new context entry.

{
  title: string
  content: string
  category: 'architecture' | 'pattern' | 'decision' | 'api' |
            'dependency' | 'bug' | 'feature' | 'config' |
            'security' | 'performance'
  level?: 'core' | 'active' | 'archive'  // default: 'active'
  priority?: 'critical' | 'high' | 'medium' | 'low'
  tags?: string[]
}

context_search

Search for specific context.

{
  query: string
  categories?: string[]
  tags?: string[]
  limit?: number  // default: 10
}

context_focus

Set current work focus to optimize context loading.

{
  task: string      // What you're working on
  modules?: string[] // Related module names
}

Project Structure

context-mcp/
├── src/
│   ├── core/           # Core logic
│   │   ├── compressor.ts    # Semantic compression
│   │   ├── relevance.ts     # Scoring algorithms
│   │   ├── telemetry.ts     # Performance monitoring
│   │   └── types.ts         # TypeScript types
│   ├── storage/
│   │   └── database.ts      # SQLite + FTS5 storage
│   ├── mcp/
│   │   └── server.ts        # MCP server implementation
│   └── cli/
│       ├── index.ts         # CLI entry point
│       ├── commands.ts      # Command handlers
│       ├── interface.ts     # Terminal UI
│       └── i18n.ts          # Translations
├── prompts/            # Prompt templates
├── tests/              # Test suites (306 tests)
└── dist/               # Compiled output

Configuration

Environment variables:

Variable	Description	Default
CONTEXT_MCP_DATA	Data directory path	~/.context-mcp

Performance

• Bulk insert: ~0.8ms per entry
• Search: <2ms for 100 results
• Core snapshot: <5ms generation
• Cache hit rate: >90% typical usage

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE for details.