Architecture Overview

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Architecture Overview

The MCP Context Provider is a Python-based Model Context Protocol (MCP) server that provides persistent tool context to Claude Desktop. The architecture follows a singleton pattern with JSON-based context files and dynamic loading capabilities.

Core Components

1. ContextProvider Class (context_provider_server.py:24-134): Singleton that manages context loading and serves tool-specific rules
2. MCP Server (context_provider_server.py:137-264): Asyncio-based server providing 4 core tools via MCP protocol
3. Context Files (contexts/*.json): JSON files following standardized schema with tool-specific rules, syntax preferences, and auto-correction patterns
4. Session Initialization Framework: Present in memory_context.json with session_initialization actions for auto-execution on startup

Context File Schema

Each context file follows this structure:

• tool_category: Primary identifier
• description: Human-readable description
• auto_convert: Boolean for automatic syntax conversion
• session_initialization: Startup actions (already implemented in memory_context.json)
• auto_store_triggers/auto_retrieve_triggers: Pattern-based automation
• syntax_rules, preferences, auto_corrections: Tool-specific configurations
• metadata: Version, priority, inheritance information

Development Commands

Installation & Setup

# Automated installation (recommended)
curl -sSL https://raw.githubusercontent.com/doobidoo/MCP-Context-Provider/main/scripts/install.sh | bash

# Verification
python scripts/verify_install.py

# Development setup from source
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

Testing & Verification

# Comprehensive installation check
python scripts/verify_install.py

# Information about current installation
python scripts/verify_install.py --info

# Server testing with auto-loading disabled (for development)
env AUTO_LOAD_CONTEXTS=false python context_provider_server.py

Context Development

# Context files location
ls contexts/*.json

# Validate context file JSON syntax
python -m json.tool contexts/your_context.json

# Test context loading
CONTEXT_CONFIG_DIR=./contexts python context_provider_server.py

DXT Package Management

# Build DXT package
cd dxt
dxt pack

# Install DXT CLI (if needed)
npm install -g @anthropic-ai/dxt

# Unpack for testing
dxt unpack mcp-context-provider-1.2.1.dxt ~/test-installation

Key Implementation Patterns

Context Loading

• Dynamic Discovery: Server auto-discovers *_context.json files
• Singleton Pattern: ContextProvider.get_instance() ensures single context manager
• Environment Variables: CONTEXT_CONFIG_DIR and AUTO_LOAD_CONTEXTS control behavior
• Graceful Degradation: Server continues if individual context files fail to load

Session Initialization (Existing Framework)

The memory_context.json already implements session initialization patterns that can be extended:

• session_initialization.actions.on_startup: Array of actions to execute
• greeting_format: Template for context-aware greetings
• Pattern-based triggers for automatic storage/retrieval

MCP Tool Architecture

Current tools are extensible via the @app.call_tool() decorator pattern:

• get_tool_context: Retrieves complete context for a tool
• get_syntax_rules: Returns syntax-specific rules
• list_available_contexts: Lists all loaded context categories
• apply_auto_corrections: Applies regex-based text transformations

Security Considerations

• Input validation in tool handlers
• File path restrictions in context loading
• Environment variable configuration
• No direct file system access from MCP tools

Configuration Integration

Claude Desktop Configuration

The server integrates via claude_desktop_config.json:

{
  "mcpServers": {
    "context-provider": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/context_provider_server.py"],
      "env": {
        "CONTEXT_CONFIG_DIR": "/path/to/contexts",
        "AUTO_LOAD_CONTEXTS": "true"
      }
    }
  }
}

Environment Variables

• CONTEXT_CONFIG_DIR: Path to context files directory (default: ./contexts)
• AUTO_LOAD_CONTEXTS: Enable/disable automatic context loading (default: true)

Extension Points for Feature Requests

The codebase is already structured to support the planned feature requests:

1. Auto-Execution (Issue #2): Session initialization framework exists in memory_context.json
2. Dynamic Context Management (Issue #3): ContextProvider class can be extended with new MCP tools for runtime context modification
3. Synergistic Integration (Issue #4): Existing pattern matching and auto-trigger system provides foundation for learning capabilities

Context Inheritance System

The general_preferences.json serves as a fallback system with "inheritance": "fallback_for_unspecified_tools", providing a foundation for hierarchical context inheritance.