# Context-MCP

<div align="center">

![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)
![Tests](https://img.shields.io/badge/tests-306%20passing-success.svg)

**Intelligent Context Manager for AI Coding Assistants**

*Hierarchical semantic compression that remembers what matters*

[Installation](#installation) • [Quick Start](#quick-start) • [Features](#features) • [CLI](#cli) • [API](#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

```bash
# 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:

```json
{
  "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

```bash
# 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.

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

### context_add
Add new context entry.

```typescript
{
  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.

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

### context_focus
Set current work focus to optimize context loading.

```typescript
{
  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](LICENSE) for details.