Context-Pods

The comprehensive MCP development suite with advanced protocol features

Context-Pods is a production-ready development framework for creating, testing, and managing Model Context Protocol (MCP) servers. Built with TypeScript and powered by TurboRepo, it provides everything from basic templates to advanced MCP protocol features including sampling/LLM integration, multi-modal content support, resource subscriptions, and comprehensive testing frameworks.

🚀 Quick Start

# Install and run Context-Pods CLI
npx @context-pods/create

# Or install globally
npm install -g @context-pods/cli
context-pods generate

# For developers: Use the convenient shell shortcut
git clone https://github.com/conorluddy/ContextPods.git
cd ContextPods
npm install && npm run build
./pods wizard  # Interactive setup with all features

✨ Features

🎯 Multiple Language Support

Create MCP servers in your preferred language:

TypeScript - Full type safety with TurboRepo optimization
Python - Async support with built-in data science tools
Rust - High-performance servers with Tokio async runtime
Shell - Wrap existing CLI tools and scripts as MCP servers
JavaScript - Simple, no-build-step servers (coming soon)

🤖 Meta-MCP Server

The Meta-MCP Server exposes Context-Pods functionality through the MCP protocol itself, providing 7 powerful tools:

{
  "tools": [
    "create-mcp", // Generate MCP servers from templates
    "wrap-script", // Convert existing scripts to MCP servers
    "list-mcps", // List and manage existing MCP servers
    "validate-mcp", // Validate MCP protocol compliance
    "analyze-codebase" // AI-powered MCP opportunity detection
  ],
  "capabilities": {
    "tools": true,
    "resources": { "subscribe": true, "listChanged": true },
    "prompts": { "listChanged": true },
    "sampling": true,
    "roots": { "listChanged": true },
    "completion": { "wordCompletion": true, "lineCompletion": true }
  }
}

Key Features:

Server Generation - Create production-ready MCP servers with advanced features
Script Wrapping - Convert Python, Shell, TypeScript, and other scripts
Server Management - List, validate, and manage existing MCP servers
AI Analysis - Intelligent codebase analysis with AST parsing and pattern detection
Registry System - SQLite-based server registry with metadata tracking
Template System - 5 optimized templates with TurboRepo integration

🛠️ Advanced MCP Protocol Features

Modern MCP SDK 1.17.4 Implementation:

Sampling & LLM Integration - Built-in LLM capabilities with model preferences and temperature control
Multi-Modal Content - Support for text, images, audio, video, and embedded resources
Resource Subscriptions - Real-time resource updates with subscription management
Roots Capability - Secure file system navigation with sandboxed access
Completion Providers - Auto-complete functionality for enhanced user experience
Progress Notifications - Long-running operation tracking with real-time updates
Prompt Templates - Dynamic prompt management with argument support

Development & Quality Assurance:

AI-Powered Analysis - Automatically identify MCP opportunities in existing codebases
TurboRepo Optimization - Advanced caching, hot reloading, and incremental builds
Comprehensive Testing - 805+ tests across packages with 85-95%+ coverage
MCP Protocol Compliance - Automated validation against official MCP schemas
Quality Gates - Pre-commit hooks ensuring build, lint, type-check, and test success
Multi-Language Support - TypeScript, Python, Rust, and Shell templates

📦 Templates

Basic Templates

`basic` (TypeScript)

Minimal TypeScript MCP server with essential features:

context-pods generate basic --name my-server

`python-basic`

Self-contained Python server with async support:

context-pods generate python-basic --name my_python_server

`rust-basic`

High-performance Rust server with Tokio:

context-pods generate rust-basic --name my_rust_server

`shell-wrapper`

Expose shell scripts and CLI tools via MCP:

context-pods generate shell-wrapper --name my_cli_wrapper

Advanced Templates

`typescript-advanced`

Production-ready TypeScript server with complete MCP SDK 1.17.4 feature implementation:

Advanced MCP Protocol Features:

Sampling & LLM Integration - Built-in AI capabilities with configurable models
Multi-Modal Content - Text, image, audio, video, and embedded resource support
Resource Subscriptions - Real-time updates with subscription management
Roots Capability - Secure sandboxed file system access
Completion Providers - Auto-complete functionality
Progress Notifications - Long-running operation tracking
Prompt Templates - Dynamic prompt management system

Development Features:

TurboRepo Optimization - Hot reloading and intelligent caching
Comprehensive Utilities - Data validation, file operations, error handling
Advanced Tools - File, data, and utility tool categories
Schema Validation - Zod-based runtime validation
Structured Logging - Production-ready logging with Context-Pods logger
Testing Ready - Built-in test structure and MCP compliance validation

context-pods generate typescript-advanced --name my-advanced-server

🤖 AI-Powered Codebase Analysis

Context-Pods includes an intelligent codebase analyzer that identifies functions in your existing code that would make excellent MCP tools. This feature helps you discover MCP opportunities and provides implementation guidance.

How It Works

The analyzer uses a multi-phase approach:

File Discovery - Recursively scans your codebase with intelligent filtering
AST Parsing - Extracts function metadata using language-specific parsers
Pattern Detection - Identifies MCP-suitable patterns (API calls, file operations, etc.)
Scoring Algorithm - Ranks functions using a sophisticated scoring system (0-100)
Template Matching - Suggests the best template for each opportunity

Supported Languages

TypeScript/JavaScript - Full AST analysis with type information
Python - AST-based function extraction (coming soon)
Rust/Go - Pattern-based analysis (planned)
Shell - Script pattern detection (planned)

Usage Examples

# Basic analysis
context-pods analyze ./src

# With filtering and output options
context-pods analyze ./src --min-score 80 --format summary --max-results 5

# Language-specific analysis
context-pods analyze ./src --languages typescript,python

# Include test files
context-pods analyze ./src --include-tests

Via Meta-MCP Server

{
  "tool": "analyze-codebase",
  "arguments": {
    "path": "./src",
    "minScore": 70,
    "outputFormat": "detailed",
    "maxResults": 10
  }
}

What It Detects

The analyzer identifies functions with:

API Integration Patterns - HTTP clients, REST calls, GraphQL queries
File Processing Operations - File I/O, data transformation, parsing
Database Interactions - SQL queries, ORM operations, data validation
Utility Functions - Data validation, formatting, conversion
External Service Integrations - Third-party API usage

Scoring Factors

Functions are scored based on:

Complexity - Sweet spot is medium complexity (3-15 cyclomatic complexity)
Accessibility - Exported functions score higher
Documentation - Well-documented functions are preferred
Parameters - Clear input parameters (1-5 params optimal)
Patterns - Detected MCP-suitable patterns boost scores
Async Nature - Async functions often perform useful I/O operations

Sample Output

🎯 Top MCP Opportunities Found (Score: 85+)

📁 src/api/weather.ts
└── fetchWeatherData (Score: 92/100)
    ├── Category: API Integration
    ├── Template: typescript-advanced
    ├── Complexity: Medium (8 cyclomatic)
    ├── Patterns: HTTP calls, JSON parsing
    └── Reasoning:
        • Exported async function with clear parameters
        • Makes external API calls (confidence: 0.9)
        • Well-documented with TypeScript types
        • Optimal complexity for MCP tool

📁 src/utils/validator.ts
└── validateUserInput (Score: 88/100)
    ├── Category: Validation
    ├── Template: basic
    ├── Complexity: Low (4 cyclomatic)
    ├── Patterns: Zod validation, error handling
    └── Implementation Guidance:
        • Tool Name: validate-user-input
        • Input Schema: { data: object, rules: string[] }
        • Dependencies: zod, validator
        • Estimated Effort: Low

🔧 CLI Commands

Context-Pods provides a comprehensive command-line interface with 11 commands, enhanced interactive features, and extensive help documentation.

Complete Command Overview

Command	Purpose	Key Features
generate	Create MCP servers from templates	5 templates, interactive selection, MCP config generation
wrap	Convert scripts to MCP servers	Auto-detection, Python/Shell/TS/JS support
init	Initialize project configuration	Interactive setup, template preferences
list	Manage MCP servers	Active/inactive status, JSON output
templates	Explore available templates	Built-in and custom templates, detailed info
wizard	Interactive guided setup	Step-by-step server creation, all features
doctor	System health diagnostics	Dependency checks, auto-fix issues
dev	Development mode	Hot reloading, custom ports, file watching
build	Build packages	Clean builds, TurboRepo optimization
test	Run test suites	Coverage reports, watch mode, 805+ tests
server	Meta-MCP server management	Start/stop/status, development mode

Quick Access

Use the convenient shell shortcut from the project root:

# Quick access without typing the full command
./pods --help
./pods generate typescript-basic --name my-server
./pods wizard  # Interactive setup

Or use the full CLI:

npx @context-pods/cli <command>
context-pods <command>  # If installed globally

Core Commands

🎯 generate - Create MCP servers from templates

# Interactive template selection
context-pods generate

# Quick generation with specific template
context-pods generate typescript-basic --name weather-api

# Advanced options
context-pods generate python-basic --name data-processor --output ./servers

# With template variables
context-pods generate rust-advanced --name file-manager --var "port=3001"

# Generate with MCP config file
context-pods generate --generate-mcp-config --config-name my-server

Options:

-n, --name <name> - MCP server name (required)
-o, --output <path> - Output directory
-d, --description <text> - Server description
-f, --force - Overwrite existing files
--var <key=value...> - Template variables
--generate-mcp-config - Generate .mcp.json config
--config-name <name> - Name for MCP config
--command <command> - Run command for server
--env <key=value...> - Environment variables

🔧 wrap - Convert existing scripts to MCP servers

# Basic script wrapping
context-pods wrap ./my-script.py --name python-tools

# With custom output location
context-pods wrap ./data-processor.js --name data-tools --output ./generated

# Include description
context-pods wrap ./backup.sh --name backup-server --description "Server for backup operations"

Supported Script Types:

Python (.py) - Creates async MCP wrapper
Shell (.sh, .bash) - Command-line MCP interface
JavaScript (.js, .mjs) - Node.js MCP wrapper
TypeScript (.ts) - Transpiled MCP wrapper
Executable files - Generic command-line wrapper

Options:

-n, --name <name> - MCP server name (required)
-t, --template <name> - Template to use (auto-detected)
-o, --output <path> - Output directory
-d, --description <text> - Server description
-f, --force - Overwrite existing files

📋 list - Manage MCP servers

# Show active MCP servers
context-pods list

# Show all servers including inactive
context-pods list --all

# JSON output for scripting
context-pods list --format json

📚 templates - Explore available templates

# Show available templates
context-pods templates

# Show all templates including custom ones
context-pods templates --all

# JSON format for integration
context-pods templates --format json

⚙️ init - Initialize project configuration

# Interactive project setup
context-pods init

# Quick setup with name
context-pods init my-mcp-project

# With preferred template
context-pods init --template typescript-basic --description "My MCP project"

🏥 doctor - System health checks and diagnostics

# Run all health checks
context-pods doctor

# Detailed information
context-pods doctor --verbose

# Automatically fix issues
context-pods doctor --fix

Health Checks:

Node.js and npm versions
Workspace structure integrity
Package build status
Template availability
Git repository status
Dependencies installation
MCP server functionality

🧙‍♂️ wizard - Interactive guided setup

# Full interactive wizard
context-pods wizard

# Skip welcome message
context-pods wizard --skip-intro

Wizard Features:

Server Generation - Guided template selection with language preferences
Script Wrapping - Step-by-step script conversion
Project Initialization - Interactive configuration setup
Template Explorer - Browse and preview available templates
Advanced Options - Custom variables, output paths, and configurations

Development Commands

🚀 dev - Development mode with hot reloading

# Start development server
context-pods dev

# Custom port
context-pods dev --port 3001

# Disable hot reload
context-pods dev --no-hot-reload

🔨 build - Build packages

# Build all packages
context-pods build

# Clean build
context-pods build --clean

# Build specific target
context-pods build my-server

🧪 test - Run tests

# Run all tests
context-pods test

# With coverage
context-pods test --coverage

# Watch mode
context-pods test --watch

Management Commands

💾 cache - Cache management

# Clear all cache
context-pods cache clear

# Show cache statistics
context-pods cache stats

# Clean expired entries
context-pods cache clean

🖥️ server - Meta-MCP Server management

# Start Meta-MCP Server
context-pods server start

# Development mode
context-pods server dev

# Check status
context-pods server status

# Stop server
context-pods server stop

⚙️ config - Configuration management

# Show current configuration
context-pods config show

# Reset to defaults
context-pods config reset

Advanced Features

📊 analyze - AI-powered codebase analysis

# Basic analysis
context-pods analyze ./src

# High-value opportunities only
context-pods analyze ./src --min-score 80

# Quick summary
context-pods analyze ./src --format summary --max-results 5

# Language-specific
context-pods analyze ./src --languages typescript,python

# Include test files
context-pods analyze ./src --include-tests

✅ validate - MCP compliance validation

# Basic validation
context-pods validate ./my-server

# Full validation including build
context-pods validate ./my-server --check-build

# Schema validation only
context-pods validate ./my-server --check-schema

Help and Documentation

Every command includes comprehensive help with examples:

# Global help
context-pods --help

# Command-specific help
context-pods generate --help
context-pods wrap --help
context-pods wizard --help

Shell Integration

The ./pods shortcut provides enhanced output with colors and progress indicators:

./pods                    # Shows usage help
./pods doctor            # System diagnostics
./pods wizard            # Interactive setup
./pods generate --help   # Command help

Scripting and Automation

Use JSON output for integration with other tools:

# Get server list as JSON
context-pods list --format json | jq '.servers[] | .name'

# Get template information
context-pods templates --format json | jq '.templates[] | select(.language=="typescript")'

# Health check automation
context-pods doctor --format json | jq '.summary'

🏗️ Architecture

Context-Pods uses a TurboRepo monorepo structure with optimized caching and build pipelines:

context-pods/
├── packages/
│   ├── core/         # Core utilities, schemas, and AI-powered codebase analysis
│   ├── cli/          # Feature-rich CLI with 11 commands and interactive wizards
│   ├── templates/    # 5 production-ready templates (TypeScript, Python, Rust, Shell)
│   ├── testing/      # Comprehensive MCP protocol compliance testing framework
│   ├── server/       # Meta-MCP server with 7 tools for server management
│   └── create/       # npx create-context-pods runner
├── docs/             # Comprehensive documentation (12+ guides)
├── examples/         # Real-world usage examples and integrations
└── coverage/         # Test coverage reports and metrics

Package Overview

Package	Purpose	Key Features	Test Coverage
@context-pods/core	Core engine and analysis	Template processing, AI codebase analysis, schema validation	160 tests, 90%+
@context-pods/cli	Command-line interface	11 commands, interactive wizards, TurboRepo integration	251 tests, 90%+
@context-pods/server	Meta-MCP server	7 tools, server registry, MCP protocol implementation	285 tests, 95%+
@context-pods/templates	Template collection	5 languages, advanced MCP features, production-ready	91 tests, 85%+
@context-pods/testing	Testing framework	Protocol compliance, wrapper testing, report generation	Framework ready
@context-pods/create	Package runner	npx integration, dependency management, CLI bootstrapping	22 tests, 75%+

🔌 Integration

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "context-pods": {
      "command": "npx",
      "args": ["@context-pods/server"]
    }
  }
}

VS Code (Cody, Continue)

Configure in your extension settings:

{
  "mcp.servers": {
    "context-pods": {
      "command": "npx",
      "args": ["@context-pods/server"]
    }
  }
}

🧪 Testing Framework

Context-Pods includes a comprehensive testing framework with 805+ tests across all packages:

MCP Protocol Compliance Testing

Validate servers against official MCP specifications:

import {
  MCPComplianceTestSuite,
  validateMCPServer,
  MCPMessageTestHarness,
} from '@context-pods/testing';

// Full compliance test suite
const suite = new MCPComplianceTestSuite('./my-server');
const results = await suite.runFullSuite();

// Individual compliance checks
const validation = await validateMCPServer('./my-server', {
  checkTools: true,
  checkResources: true,
  checkProtocol: true,
  timeout: 30000,
});

// Test harness for communication testing
const harness = new MCPMessageTestHarness({
  serverPath: './my-server',
  transport: 'stdio',
  timeout: 5000,
});

await harness.initialize();
const toolResult = await harness.callTool('my-tool', { input: 'test' });

Script Wrapper Testing

Test wrapped scripts across multiple languages:

import { testScriptWrapper } from '@context-pods/testing';

// Test Python script wrapper
const pythonResults = await testScriptWrapper('./script.py', {
  language: 'python',
  testCases: [{ input: { data: 'test' }, expectedOutput: 'processed' }],
});

// Test shell script wrapper
const shellResults = await testScriptWrapper('./script.sh', {
  language: 'shell',
  testEnvironment: { NODE_ENV: 'test' },
});

Test Categories

Unit Tests - Individual function and class testing (599+ tests)
Integration Tests - End-to-end workflow validation (156+ tests)
Protocol Compliance - MCP specification adherence (50+ tests)
Template Validation - Generated code quality assurance
Performance Tests - Scalability and resource usage benchmarks
Error Handling - Resilience and recovery testing

📚 Documentation

🧪 Test Coverage & Quality Assurance

Context-Pods maintains exceptional test coverage with 805+ total tests across all packages:

Coverage by Package

Package	Coverage	Tests	Focus Areas
`@context-pods/server`	95%+	285	MCP protocol implementation, tools, registry, validation
`@context-pods/cli`	90%+	251	All 11 CLI commands, caching, TurboRepo integration
`@context-pods/core`	90%+	160	Template engine, AI analysis, schema validation
`@context-pods/templates`	85%+	91	Template validation, MCP feature coverage, SDK compliance
`@context-pods/create`	75%+	22	NPX runner, dependency management, error handling
`@context-pods/testing`	Framework	Ready	MCP compliance testing, wrapper validation

Test Categories

Unit Tests - Individual function and class testing
Integration Tests - End-to-end workflow validation
Protocol Compliance - MCP specification adherence
Template Validation - Generated code quality assurance
Error Handling - Resilience and recovery testing
Performance Tests - Scalability and resource usage

Quality Gates & Standards

All quality gates must pass before any commit:

Build (npm run build) - All 6 packages compile successfully
Type Check (npm run type-check) - Strict TypeScript validation
Lint (npm run lint) - Zero ESLint errors across all files
Format (npm run format) - Consistent code formatting
Test (npm run test) - All 805+ tests pass

Additional Quality Features:

TurboRepo Caching - Intelligent build and test result caching
Pre-commit Hooks - Automated quality gate enforcement
MCP Protocol Validation - Schema compliance testing against official specs
Template Integrity - Generated code quality assurance
Performance Benchmarks - Build time and execution optimization

Run tests locally:

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific package tests
npm test --workspace=@context-pods/server

# Run integration tests
npm run test:e2e

Development Setup

# Clone the repository
git clone https://github.com/conorluddy/ContextPods.git
cd ContextPods

# Install dependencies (uses npm workspaces)
npm install

# Build all packages (TurboRepo optimized)
npm run build

# Run comprehensive test suite (805+ tests)
npm test

# Start development with hot reloading
npm run dev

# Quick access via shell shortcut
./pods --help
./pods wizard  # Interactive setup

Quality Development Commands:

# Run all quality gates
npm run lint && npm run type-check && npm test

# Clean build (clears TurboRepo cache)
npm run clean && npm run build

# Generate coverage reports
npm run test:coverage

# MCP server development and testing
npm run mcp:start    # Start Meta-MCP server
npm run mcp:test     # Test MCP connection
npm run mcp:status   # Check server status

📈 Roadmap

Current Status: Production-ready MCP development framework with advanced protocol features

Upcoming Enhancements:

Additional Language Templates - Go, Ruby, Java support
Visual Template Builder - Web-based template customization interface
MCP Server Marketplace - Community template and server sharing
Cloud Deployment - AWS Lambda, Vercel, and Docker deployment options
Advanced Analytics - Performance profiling and usage analytics
Extended Transport Support - HTTP, WebSocket, and GraphQL transports
IDE Extensions - VS Code, JetBrains integration for enhanced developer experience

Recently Completed (v0.1.10):

✅ MCP SDK 1.17.4 - Full modern MCP protocol implementation
✅ Advanced Protocol Features - Sampling, multi-modal, subscriptions, roots, completion
✅ Comprehensive Testing - 805+ tests with 85-95%+ coverage across packages
✅ Quality Gates - Pre-commit hooks, automated CI/CD, strict TypeScript
✅ AI-Powered Analysis - Intelligent codebase analysis with AST parsing
✅ TurboRepo Optimization - Advanced caching, hot reloading, incremental builds

📄 License

🙏 Acknowledgments

Built with the Model Context Protocol SDK v1.17.4 by Anthropic.

Core Technologies:

TypeScript - Type-safe development with strict compiler settings
TurboRepo - Advanced monorepo management with intelligent caching
Vitest - Fast, modern testing framework with comprehensive coverage
Zod - Runtime type validation and schema generation
SQLite - Lightweight database for server registry management

📊 Project Stats

Total Lines of Code: 25,000+ (production code)
Test Files: 805+ comprehensive tests across all packages
Templates: 5 production-ready templates (TypeScript, Python, Rust, Shell)
CLI Commands: 11 comprehensive commands with interactive wizards
MCP Tools: 7 powerful tools in the Meta-MCP server
Documentation: 12+ comprehensive guides and API references
Quality Gates: 5 automated checks (build, type-check, lint, format, test)

Context-Pods: The complete MCP development suite
From concept to production-ready MCP servers

Name		Name	Last commit message	Last commit date
Latest commit History 193 Commits
.claude/commands		.claude/commands
.github/workflows		.github/workflows
.husky		.husky
docs		docs
examples		examples
packages		packages
scripts		scripts
tests		tests
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.eslintrc.stricter.json		.eslintrc.stricter.json
.gitignore		.gitignore
.lintstagedrc.json		.lintstagedrc.json
.prettierrc.json		.prettierrc.json
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
IDEAS.md		IDEAS.md
README.md		README.md
RELEASE.md		RELEASE.md
package-lock.json		package-lock.json
package.json		package.json
pods		pods
tsconfig.json		tsconfig.json
turbo.json		turbo.json
vitest.config.ts		vitest.config.ts

conorluddy/ContextPods

Folders and files

Latest commit

History

Repository files navigation

Context-Pods

🚀 Quick Start

✨ Features

🎯 Multiple Language Support

🤖 Meta-MCP Server

🛠️ Advanced MCP Protocol Features

📦 Templates

Basic Templates

basic (TypeScript)

python-basic

rust-basic

shell-wrapper

Advanced Templates

typescript-advanced

🤖 AI-Powered Codebase Analysis

How It Works

Supported Languages

Usage Examples

Via Meta-MCP Server

What It Detects

Scoring Factors

Sample Output

🔧 CLI Commands

Complete Command Overview

Quick Access

Core Commands

🎯 generate - Create MCP servers from templates

🔧 wrap - Convert existing scripts to MCP servers

📋 list - Manage MCP servers

📚 templates - Explore available templates

⚙️ init - Initialize project configuration

🏥 doctor - System health checks and diagnostics

🧙‍♂️ wizard - Interactive guided setup

Development Commands

🚀 dev - Development mode with hot reloading

🔨 build - Build packages

🧪 test - Run tests

Management Commands

💾 cache - Cache management

🖥️ server - Meta-MCP Server management

⚙️ config - Configuration management

Advanced Features

📊 analyze - AI-powered codebase analysis

✅ validate - MCP compliance validation

Help and Documentation

Shell Integration

Scripting and Automation

🏗️ Architecture

Package Overview

🔌 Integration

Claude Desktop

VS Code (Cody, Continue)

🧪 Testing Framework

MCP Protocol Compliance Testing

Script Wrapper Testing

Test Categories

📚 Documentation

🧪 Test Coverage & Quality Assurance

Coverage by Package

Test Categories

Quality Gates & Standards

Development Setup

📈 Roadmap

📄 License

🙏 Acknowledgments

📊 Project Stats

About

Topics

Resources

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

`basic` (TypeScript)

`python-basic`

`rust-basic`

`shell-wrapper`

`typescript-advanced`

Packages