Skip to main content
Glama

Context-MCP

Version License Node Tests

Intelligent Context Manager for AI Coding Assistants

Hierarchical semantic compression that remembers what matters

Installation • Quick Start • Features • CLI • API


The Problem

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

Related MCP server: Heimdall MCP Server

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)

  • 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[]
}

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.

Available Tools

9 tools
context_addA

Add new context entry to the knowledge base. Use this to remember important decisions, patterns, or information about the project. The entry will be automatically categorized and compressed for efficient retrieval.

Inputs: title (required), content (required), category (required), tags, +2 more.

context_deleteB

Delete a context entry

Inputs: id (required).

context_focusA

Set the current work focus. This optimizes which context is loaded. Call this when switching between different areas of the project.

Inputs: task (required), modules.

context_getA

Get the current project context optimized for token efficiency. Returns a hierarchical view:

  • CORE: Critical decisions and patterns (always included, ~500 tokens)

  • ACTIVE: Current work context (included if relevant, ~2000 tokens)

  • ARCHIVE: Available via context_search for details

Use this at the start of conversations to understand the project.

Inputs: include_active, focus_categories.

context_relateB

Create a relationship between two context entries for better navigation

Inputs: to_id (required), from_id (required).

context_statsB

Get statistics about the context database

Inputs: no named parameters.

context_summarizeA

Generate a compressed summary of recent context. Useful for creating checkpoints or when context is getting too large.

Inputs: since, max_tokens.

context_updateC

Update an existing context entry

Inputs: id (required), tags, level, title, +3 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct action on the context knowledge base: add, get, search, update, delete, relate, stats, focus, and summarize. There is no meaningful overlap; even get and search serve clearly separate purposes (broad optimized view vs. targeted query).

    Naming Consistency5/5

    All tool names follow a uniform 'context_' prefix followed by a simple verb (add, get, search, update, delete, relate, stats, focus, summarize). This is a perfect example of consistent verb_noun convention.

    Tool Count5/5

    With 9 tools, the server is well-scoped. Each tool is meaningful and contributes to the overall context management workflow without redundancy or bloat. This is an ideal size for the stated purpose.

    Completeness5/5

    The tool set covers the full lifecycle of context entries: create (add), read (get), update, delete, search, linking (relate), statistics, focus management, and summarization. There are no obvious dead ends or missing core operations.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Provides AI assistants with persistent memory of your project architecture, development history, and technical decisions, allowing them to give context-aware coding help without needing repeated explanations.
      16
      61 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI coding assistants with persistent, context-rich memory of a codebase, including documentation and git history, enabling recall across sessions.
      105
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Intelligent context-aware memory system for AI assistants that enables persistent memory, automatic development activity tracking, and intelligent information retrieval across conversations.
      18
      MIT