croakingtoad/context-engineering-mcp

Context Engineering MCP Server

🚀 A comprehensive MCP server that automates Cole Medin's context engineering methodology for creating high-quality Product Requirements Prompts (PRPs).

🎯 Overview

This MCP server implements the context engineering methodology created by Cole Medin in his Context Engineering Introduction repository. It provides intelligent automation for creating comprehensive Product Requirements Prompts that account for your existing codebase context.

What This Server Does

The Context Engineering MCP Server intelligently analyzes your existing codebase and automatically generates:

• 🔍 Contextual Questions based on detected patterns and frameworks
• 📋 Comprehensive INITIAL.md documentation following Cole's methodology
• 📝 Product Requirements Prompts (PRPs) using proven templates
• 🎯 Execution Guidance with agent recommendations and task breakdowns
• 💾 Persistent Storage for managing PRPs and project context
• 🔗 Archon Integration for seamless task and knowledge management

Why Use This Server?

Instead of starting with blank requirements documents:

1. Analyzes your existing code to understand architecture and patterns
2. Asks intelligent questions specific to your tech stack and domain
3. Synthesizes insights into comprehensive documentation
4. Generates actionable PRPs that account for your current context
5. Provides storage and versioning for long-term project management

📋 MCP Tools (9 Available)

Core Context Engineering Tools

1. list_templates - List all available PRP templates with optional category filtering
2. generate_prp - Generate a Product Requirements Prompt based on a template and project context
3. validate_prp - Validate a PRP against context engineering best practices
4. search_templates - Search for templates by name, description, or tags
5. create_custom_template - Create new custom PRP templates
6. analyze_context - Analyze project context to recommend suitable templates and improvements

Storage & Management Tools

7. list_prps - List all stored PRPs with filtering and search capabilities
8. update_prp - Update existing PRPs with version tracking
9. manage_storage - Manage storage operations, backup, and maintenance

📚 MCP Resources (5 Available)

• Templates (context-engineering://templates) - Collection of PRP templates
• Patterns (context-engineering://patterns) - Code analysis patterns and rules
• Initial (context-engineering://initial) - INITIAL.md generation templates
• Rules (context-engineering://rules) - Global context engineering rules
• PRPs (context-engineering://prps) - Stored Product Requirements Prompts

🚀 Quick Start

Installation

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

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Start the MCP server
npm start

Demo Integration

# Run the comprehensive demo
node demo-integration.js

⚙️ Claude Desktop Configuration

Add this configuration to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "context-engineering": {
      "command": "node",
      "args": ["/path/to/context-engineering-mcp-server/dist/index.js"],
      "env": {
        "TEMPLATES_DIR": "/path/to/context-engineering-mcp-server/templates",
        "EXTERNAL_TEMPLATES_DIR": "/path/to/context-engineering-mcp-server/external/context-engineering-intro",
        "DATA_DIR": "/path/to/context-engineering-mcp-server/data"
      }
    }
  }
}

Claude Code Integration

# Add to Claude Code via MCP
claude-code mcp add context-engineering /path/to/context-engineering-mcp-server/dist/index.js

🔧 Configuration Options

Environment Variables

• TEMPLATES_DIR - Directory containing internal templates (default: ./templates)
• EXTERNAL_TEMPLATES_DIR - Directory for Cole's external templates (default: ./external/context-engineering-intro)
• DATA_DIR - Directory for persistent storage (default: ./data)
• NODE_ENV - Environment mode (development, production, test)

Server Capabilities

• Archon Integration - Automatic integration with Archon MCP for task and knowledge management
• Version Control - Full version tracking for PRPs with diff generation
• Concurrent Operations - Supports up to 10 concurrent storage operations
• Template Synchronization - Automatic syncing with Cole's upstream templates

📖 Usage Examples

Basic PRP Generation

// List available templates
const templates = await mcp.call('list_templates', { category: 'web-app' });

// Generate a PRP for a Next.js project
const prp = await mcp.call('generate_prp', {
  templateId: 'nextjs-app-template',
  projectContext: {
    name: 'E-commerce Platform',
    domain: 'retail',
    stakeholders: ['Product Manager', 'Engineering Team', 'Design Team'],
    objectives: ['Build scalable e-commerce platform', 'Implement modern UX'],
    constraints: ['Budget: $50k', 'Timeline: 3 months']
  },
  saveToStorage: true,
  outputFormat: 'markdown'
});

Context Analysis Workflow

// Analyze project context
const analysis = await mcp.call('analyze_context', {
  projectContext: {
    name: 'Mobile Banking App',
    domain: 'fintech',
    description: 'Secure mobile banking application with real-time transactions',
    stakeholders: ['Bank Executives', 'Compliance Team', 'Customers'],
    constraints: ['PCI DSS Compliance', 'SOX Compliance', 'High Security Requirements']
  }
});

// Use recommended template
const prp = await mcp.call('generate_prp', {
  templateId: analysis.recommendedTemplates[0].id,
  projectContext: analysis.enhancedContext
});

Storage Management

// List stored PRPs
const prps = await mcp.call('list_prps', {
  category: 'fintech',
  status: 'active',
  limit: 10
});

// Update a PRP
const updated = await mcp.call('update_prp', {
  id: 'prp-123',
  updates: {
    status: 'completed',
    metadata: { version: '2.0' }
  },
  comment: 'Updated requirements based on stakeholder feedback'
});

🏗️ Architecture

Transport & Protocol

• Protocol: MCP (Model Context Protocol) v0.6.0
• Transport: StdioServerTransport for client communication
• Security: Input validation with Zod schemas

Core Components

TemplateManager

• Loads templates from internal and external directories
• Provides search, filtering, and categorization
• Handles template validation and caching
• Syncs with Cole Medin's upstream repository

PRPGenerator

• Generates PRPs from templates with context substitution
• Supports multiple output formats (Markdown, JSON, HTML)
• Handles custom sections and metadata
• Integrates with storage and version control

StorageSystem

• Persistent storage for PRPs and project context
• Version tracking with diff generation
• Concurrent operation management
• Backup and recovery capabilities

IntegrationsManager

• Seamless integration with Archon MCP server
• Automatic task creation from PRP sections
• Knowledge synchronization
• Health monitoring and fallback handling

External Integration

The project uses git subtree to integrate Cole Medin's original templates:

# Sync with upstream templates
./scripts/sync-templates.sh

🧪 Testing

The project follows Test-Driven Development (TDD) principles:

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test suites
npm run test:unit        # Unit tests
npm run test:integration # Integration tests
npm run test:e2e        # End-to-end tests
npm run test:performance # Performance tests

# Watch mode for development
npm run test:watch

Test Coverage

• Project Structure Tests: Validate directory structure and configuration
• Unit Tests: Test individual components and functions
• Integration Tests: Test MCP tool and resource handlers
• End-to-End Tests: Test complete workflows
• Performance Tests: Test under load and stress conditions

Current test status: 58 tests passing with comprehensive coverage.

🛠️ Development

Prerequisites

• Node.js 18+
• npm or yarn
• TypeScript 5.3+

Development Commands

# Watch mode for development
npm run dev

# Type checking
npm run type-check

# Linting and formatting
npm run lint
npm run lint:fix
npm run format
npm run format:check

# Validation pipeline
npm run validate  # Runs lint + type-check + all tests

# Template synchronization
npm run sync-templates

Project Structure

├── src/
│   ├── tools/              # MCP tool implementations (9 tools)
│   │   ├── generate-prp.ts
│   │   ├── validate-prp.ts
│   │   ├── list-templates.ts
│   │   ├── search-templates.ts
│   │   ├── create-custom-template.ts
│   │   ├── analyze-context.ts
│   │   ├── list-prps.ts
│   │   ├── update-prp.ts
│   │   └── manage-storage.ts
│   ├── resources/          # MCP resource handlers (5 resources)
│   │   ├── handlers/
│   │   └── resource-manager.ts
│   ├── lib/                # Core logic components
│   │   ├── template-manager.ts
│   │   ├── prp-generator.ts
│   │   ├── storage.ts
│   │   ├── change-tracker.ts
│   │   ├── integrations.ts
│   │   └── execution-guidance.ts
│   ├── types/              # TypeScript type definitions
│   └── index.ts            # Main server entry point
├── templates/              # Internal PRP templates
├── external/               # Git subtree for Cole's templates
│   └── context-engineering-intro/
├── data/                   # Persistent storage directory
├── scripts/                # Utility scripts
│   ├── sync-templates.sh   # Template synchronization
│   └── test-coverage-report.js
├── test/                   # Test suites
│   ├── unit/
│   ├── integration/
│   ├── e2e/
│   └── performance/
└── dist/                   # Built JavaScript output

🤝 Contributing

We welcome contributions! This project builds upon Cole Medin's excellent foundation.

Development Workflow

1. Follow TDD approach - write tests first
2. Use TypeScript with strict mode
3. Follow ESLint and Prettier configurations
4. Update tests when adding new features
5. Keep external templates synced via git subtree
6. Ensure all CI checks pass

Code Style

• TypeScript strict mode enabled
• ESLint + Prettier for consistent formatting
• Comprehensive type definitions
• Extensive test coverage required
• Documentation for all public APIs

🙏 Credits & Attribution

This project is built upon the excellent context engineering methodology created by Cole Medin:

• Original Repository: context-engineering-intro
• Methodology: Cole Medin's context engineering approach for PRP generation
• Templates: Integrated via git subtree from Cole's repository
• Inspiration: Cole's systematic approach to requirements engineering

Contributors

• Cole Medin - Original context engineering methodology and templates
• Claude/Anthropic - MCP server implementation and automation
• croakingtoad - Project coordination and testing

📄 License

MIT License - see file for details.

This project incorporates templates and methodology from Cole Medin's context-engineering-intro repository, used with attribution under open source principles.

🔗 Related Resources

• MCP Specification - Model Context Protocol documentation
• Cole's Context Engineering - Original methodology
• Archon MCP - Task and knowledge management integration
• Claude Desktop - Primary MCP client

📞 Support & Issues

• Issues: Report bugs and feature requests via GitHub Issues
• Discussions: Use GitHub Discussions for questions and ideas
• Documentation: Comprehensive docs in the /docs directory (coming soon)

Made with ❤️ by the Locomotive Agency team, built upon Cole Medin's excellent foundation