Tests Coverage

A secure, isolated environment for exploring Python development with Model Context Protocol (MCP) and Language Server Protocol (LSP).

This project creates an isolated container environment that combines MCP and LSP capabilities for Python development. By leveraging the complementary strengths of both protocols, we enable LLMs to access powerful code intelligence features while maintaining strict security boundaries.

The project includes comprehensive algorithm analysis capabilities, Claude Code integration, and educational materials for working with MCP and LSP in Python environments. Key features include:

• Advanced algorithm implementations with complexity analysis
• Custom Claude commands for GitHub issue resolution
• Structured milestones for project development
• Educational course materials for Claude Code training
• Standardized branch naming and coding conventions

graph TD
    A[Host System]
    B[API Keys]
    C[Alpine Container]
    D[Run-Python MCP]
    E[MultilspyLSP]
    F[Python LSP Server]
    G[Client Tools]
    H[Python Algorithms]
    
    A --> B
    A --> C
    B --> D
    B --> E
    C --> D
    C --> E
    C --> F
    C --> G
    C --> H
    
    D --> H
    E --> F
    F --> H
    
    G --> D
    G --> E

The project implements a principle of least access architecture:

• Container isolation from host system
• Non-root user execution within container
• Restricted port exposure (bound to localhost only)
• Secure secrets management via GitHub Secrets
• Resource limits on container (memory, CPU)
• Input validation and sanitization
• Clear security domain boundaries between components

See ./SECURITY.md for comprehensive security guidelines and best practices.

• Pydantic Run-Python: Executes Python code via MCP
• MultilspyLSP: Bridges LSP capabilities to MCP
• Python LSP Server: Provides code intelligence (completion, analysis, diagnostics)
• Client Interfaces: Multiple access methods with the same security model

1. Initial setup:

# Create required directories
make dirs

# Generate configuration files from org sources
make tangle

# Set up GitHub CLI authentication for secrets
gh auth login

1. Set up secrets management:

# Run the secrets setup script
./scripts/setup_secrets.sh

# Or manually update the GitHub secrets with your actual keys
gh secret edit GH_PAT
gh secret edit ANTHROPIC_API_KEY

1. Build and run the container:

# Build the Docker/Podman image
make build

# Run the container (automatically retrieves secrets)
make run

1. Test the environment:

# Verify MCP server connectivity
make test

# Try analyzing an algorithm (after creating one)
make analyze ALGO=fibonacci

Run make or gmake help for a full list of available commands.

Key commands for getting started:

• make build - Build the Docker/Podman image
• make run - Start container with mounted volumes
• make test - Verify MCP server connectivity
• make analyze ALGO=fibonacci - Analyze algorithm via MCP
• make claude-analyze ALGO=fibonacci - Use Claude to analyze code
• make tangle - Generate config files from org sources
• make detangle - Update org files from modified configs
• make install-mcp - Install MCP CLI with UV
• make pytest - Run all Python tests
• make lint - Run all linters (isort, black, mypy, flake8)

The project includes custom commands for Claude Code:

• /fix-github-issue - Analyze and fix issues from the GitHub repository
• /create-pr - Create pull requests with standardized formatting
• /analyze-algorithm - Perform detailed analysis of algorithm implementations

You can interact with the MCP Run Python server directly using Deno. The correct JSON-RPC format for calling Python code is:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "run_python_code",
    "arguments": {
      "python_code": "print(\"Hello, MCP!\")"
    }
  },
  "id": 1
}

Example usage:

echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "run_python_code", "arguments": {"python_code": "result = 40 + 2\nprint(f\"The answer is: {result}\")\nresult"}}, "id": 1}' | \
deno run -N -R=node_modules -W=node_modules --node-modules-dir=auto \
--allow-read=. jsr:@pydantic/mcp-run-python stdio | jq

To access the algorithms in this repository, use:

import sys
sys.path.append('.')
from algorithms.factorial import factorial_iterative

result = factorial_iterative(5)
print(f"Factorial of 5 is {result}")

Before committing changes, always run:

1. gmake help - Verify all targets are documented
2. gmake lint - Ensure code passes style checks
3. gmake test - Verify functionality works

The project uses literate programming with org-mode. Configuration files are generated from env-setup.org using the tangle process. If you modify generated files directly, use detangle to propagate changes back to the org source.

Utility scripts are available in the scripts/ directory. Scripts include setup tools, MCP management, and analysis utilities. Use `ls -la scripts/` to see all available scripts.

This project follows a literate programming approach with org-mode. Key development files:

• env-setup.org - Contains configuration for Emacs, VSCode, and Claude Code
• SETUP.org - Contains general setup instructions and documentation
• Makefile - Provides automation for common development tasks
• CLAUDE.md - Contains guidance for Claude Code when working in this repository

When making changes:

1. For configuration: Edit the org files and run make tangle
2. For implementation: Follow standard Git workflow with conventional commits
3. For testing: Add algorithms to algorithms/ directory and use make analyze

The project maintains standardized branch naming conventions:

• Always create branches from GitHub issues
• Follow the format: <type>/<issue-number>-<short-description>
• Types should match conventional commits (feat, fix, docs, etc.)

The project is organized around key milestones:

1. Security Enhancement - Hardening container isolation and access controls
2. Performance Optimization - Improving algorithm analysis speed and resource efficiency
3. Usability and Developer Experience - Enhancing tooling and documentation
4. Integration and Extensibility - Adding support for additional protocols and platforms
5. Documentation and Community - Creating educational materials and guides

1. Demonstrate secure integration between MCP and LSP
2. Provide a reference architecture for isolated AI code analysis
3. Enable exploration of Python algorithm implementations
4. Support multiple client interfaces while maintaining security
5. Create educational resources for Claude Code and MCP usage
6. Build a community-friendly platform for algorithm analysis

The project includes educational materials for learning Claude Code and MCP:

• docs/courses/claude-code-course.org - Comprehensive two-day course on Claude Code
• docs/courses/examples/ - Example code for Claude Code and MCP integration
• docs/courses/exercises/ - Hands-on exercises for learning Claude Code

The course covers:

• API setup and configuration
• AWS Bedrock integration
• Custom Claude commands
• Code review with Claude
• Multi-language support
• MCP server development and integration

• Anthropic: Introducing the Model Context Protocol - Official announcement of MCP as an open standard for connecting AI assistants to data sources.
• Model Context Protocol Documentation - Comprehensive documentation explaining MCP concepts, architecture, and implementation details.
• Model Context Protocol GitHub - Official GitHub organization with protocol specification, SDKs, and reference implementations.
• Anthropic MCP Documentation - Integration guides and best practices for using MCP with Claude.
• Claude Code Documentation - Official documentation for Claude Code CLI.
• Microsoft MultilspyLSP - The Python library for creating language server clients that powers our LSP integration.
• Python LSP Server - The Python implementation of the Language Server Protocol used in this project.
• Language Server Protocol - Background on the LSP standard that enables editor-agnostic language intelligence.
• MultilspyLSP MCP Server - Reference implementation of an MCP server that provides LSP capabilities.
• Hacker News: Model Context Protocol Discussion - Community discussion about MCP, including perspectives on security considerations and integration approaches.
• Simon Willison: MCP Run Python - Detailed exploration of the MCP run-python implementation and its practical applications.

MIT License