Context MCP Server

Context-aware guidance for AI assistants via Model Context Protocol.

Overview

Provides just-in-time, context-specific guidance to AI assistants as developers move through their workflow. The server loads context-appropriate information and guidance as you transition between different development activities (design, development, debugging, PR review, deployment, operations).

Features

• 8 Base Contexts: Design, development, debugging, PR review, deployment, operations, new conversation, post-compaction
• Project-Specific Overlays: Extend base contexts with project-specific guidance
• Learning Loop: Suggest improvements and vote on guidance items
• Transition Tracking: Monitor and analyze context transition patterns
• Just-in-Time Loading: Guidance appears only when relevant to current context
• Composition: Three-layer guidance (base + project + override flags)

Quick Start

1. Installation

cd ~/development/context_mcp
npm install
npm run build

2. Claude Desktop Integration

Add to your Claude Desktop config:

• Linux: ~/.config/Claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

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

3. Restart Claude Desktop

The server will automatically:

• Create ~/.context_mcp/ directory structure
• Install 8 base context files
• Initialize learning data storage
• Start logging to ~/.context_mcp/logs/context-mcp.log

Usage

In Claude Desktop

After restarting Claude Desktop, the server provides:

Resource: context://definitions

• Auto-loads at session start
• Lists all available contexts with entry signals and transitions

Tools: 4 tools for context management

• declare_context_transition: Declare you're entering a new context (primary)
• get_context_guidance: Fetch guidance for a specific context (secondary)
• suggest_guidance: Submit a suggestion for guidance improvement
• vote_on_guidance: Vote on an existing suggestion

Manual Server Start

For testing or validation:

npm start -- --base-path ~/.context_mcp --log-level info

Configuration

CLI Arguments

node dist/index.js --base-path <path> --log-level <level>

• --base-path: Data directory (default: ~/.context_mcp/)
• --log-level: Logging verbosity (error, warn, info, debug)

Environment Variables

• CONTEXT_MCP_BASE_PATH: Override base path
• CONTEXT_MCP_CWD: Override current working directory
• CONTEXT_MCP_LOG_LEVEL: Override log level

Directory Structure

~/.context_mcp/
├── contexts/              # 8 base context markdown files
│   ├── design.md
│   ├── development.md
│   ├── debugging.md
│   ├── pr-review.md
│   ├── deployment.md
│   ├── operations.md
│   ├── new-conversation.md
│   └── post-compaction.md
├── projects/              # Project-specific context overlays (optional)
│   └── <project-name>/
│       └── contexts/
│           └── development.md  # Example project overlay
├── learning/              # Learning loop data
│   ├── suggestions.json
│   ├── votes.json
│   └── transitions.json
└── logs/                  # Server logs
    └── context-mcp.log

Available Contexts

1. design: Architecture planning, technical design, tradeoff analysis
2. development: Inner loop coding, testing, iteration
3. debugging: Issue investigation, log analysis, root cause analysis
4. pr-review: Code review, CI/CD, feedback integration
5. deployment: Release preparation, rollout, monitoring
6. operations: Production monitoring, incident response, maintenance
7. new-conversation: Starting fresh sessions, context introduction
8. post-compaction: Re-establishing context after history compaction

Each context includes:

• Entry signals (when to use this context)
• Common transitions (what contexts typically follow)
• Essential tools (recommended tools for this work)
• Common workflows (typical task sequences)
• Success criteria (what "done" looks like)
• Gotchas (common mistakes to avoid)

Testing

Run Tests

# All tests
npm test

# With coverage report
npm run test:coverage

# Watch mode
npm run test:watch

Test Coverage

Current coverage (57 tests):

• Statements: 97.00%
• Branches: 87.12%
• Functions: 100.00%
• Lines: 96.96%

MCP Inspector Validation

npx @modelcontextprotocol/inspector dist/index.js

Opens web UI at http://localhost:6274 for interactive testing.

Development

# Build
npm run build

# Watch mode
npm run watch

# Lint
npm run lint

# Format
npm run format

Project Structure

src/
├── services/       # Core services (ContextLoader, GuidanceManager, etc.)
├── tools/          # MCP tool implementations
├── resources/      # MCP resource implementations
├── types/          # TypeScript type definitions
└── utils/          # Utility functions

tests/
├── unit/           # Unit tests
└── integration/    # Integration tests

Architecture

Core Services

1. ContextLoader: Markdown file loading, YAML frontmatter parsing, caching
2. GuidanceManager: Three-layer composition (base + project + override flags)
3. LearningEngine: Suggestions and voting with JSON persistence
4. TransitionLogger: Transition tracking with filtering and analysis

MCP Resources

context://definitions

• Lists all available contexts with metadata
• Auto-loads at session start
• Provides entry signals and common transitions

MCP Tools

declare_context_transition

• Primary tool for context declarations
• Records transition with timestamp
• Returns composed guidance (base + project)
• Optional previous_context for transition tracking

get_context_guidance

• Secondary tool for fetching guidance
• Takes context name only
• No transition logging
• Useful for reference lookups

suggest_guidance

• Submit improvement suggestions
• Records section and description
• Returns UUID for tracking
• Enables continuous improvement

vote_on_guidance

• Vote on existing suggestions
• Fuzzy matching within sections
• Up/down voting
• Tracks voting patterns

Usage Examples

Declaring Context Transition

// When starting development work
{
  "context": "development",
  "project": "context_mcp",
  "previous_context": "design"
}

// Returns:
{
  "context": "development",
  "guidance": {
    "description": "Inner loop coding...",
    "entry_signals": [...],
    "common_transitions": [...],
    "essential_tools": [...],
    "workflows": [...],
    "success_criteria": [...],
    "gotchas": [...]
  }
}

Submitting Suggestion

{
  "context": "development",
  "section": "essential_tools",
  "description": "Add TypeScript compiler as essential tool",
  "content": "**tsc**: TypeScript compiler for type checking"
}

// Returns: { "suggestion_id": "uuid-here" }

Voting on Suggestion

{
  "context": "development",
  "section": "essential_tools",
  "description_match": "TypeScript compiler",
  "vote": "up"
}

// Returns: { "success": true, "message": "Vote recorded" }

Project-Specific Contexts

Create project-specific overlays in ~/.context_mcp/projects/<project-name>/contexts/:

---
context: development
compose_with_base: true
last_updated: 2025-12-09T00:00:00Z
---

# Project-Specific Development Context

## Project Tools
- **npm**: Package management
- **Jest**: Testing framework
- **TypeScript**: Primary language

## Project Workflows
1. Write code
2. Run tests (`npm test`)
3. Check types (`npm run type-check`)
4. Commit changes

The server will automatically compose base + project guidance when project is detected.

Monitoring

View Logs

tail -f ~/.context_mcp/logs/context-mcp.log

Learning Data

# View suggestions
cat ~/.context_mcp/learning/suggestions.json

# View votes
cat ~/.context_mcp/learning/votes.json

# View transitions
cat ~/.context_mcp/learning/transitions.json

Troubleshooting

Server not appearing in Claude Desktop

1. Check config syntax (Linux): cat ~/.config/Claude/claude_desktop_config.json
2. Verify build: cd ~/development/context_mcp && npm run build
3. Check logs: tail ~/.context_mcp/logs/context-mcp.log
4. Restart Claude Desktop completely

Context files not loading

1. Verify directory exists: ls ~/.context_mcp/contexts/
2. Check file format (YAML frontmatter + markdown)
3. Verify compose_with_base flag in frontmatter
4. Check logs for parsing errors

Tools not working

1. Verify server is running (check Claude Desktop MCP status)
2. Check tool arguments match schema
3. Review server logs for errors
4. Test with MCP Inspector

Documentation

• Project Overview - Concept and rationale
• Design Document - Detailed technical design
• Implementation Plan - Development roadmap
• Implementation Complete - Status report
• Validation & Deployment - Deployment guide

Contributing

This is currently a single-user project for personal development workflows. Future versions may support multi-user scenarios and collaboration features.

License

ISC