isolated-pymcp

#+TITLE: isolated-pymcp
#+AUTHOR: Aidan Pace
#+EMAIL: [email protected]
#+DATE: 2025-04-22

[[https://github.com/aygp-dr/isolated-pymcp/actions/workflows/python-tests.yml/badge.svg][Tests]] [[https://codecov.io/gh/aygp-dr/isolated-pymcp/branch/main/graph/badge.svg][Coverage]]

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

** Overview

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

** Architecture

#+BEGIN_SRC mermaid :file architecture.png
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
#+END_SRC

** Security Model

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.

** Core Components

- *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

** Integration Points

| Component    | Protocol | Function                             |
|--------------+----------+--------------------------------------|
| Run-Python   | MCP      | Code execution and output capture    |
| MultilspyLSP | MCP+LSP  | Code intelligence bridge             |
| Python LSP   | LSP      | Static analysis and completion       |
| Claude Code  | -        | AI-assisted analysis and exploration |

** Getting Started

1. Initial setup:

#+BEGIN_SRC shell
# Create required directories
make dirs

# Generate configuration files from org sources
make tangle

# Set up GitHub CLI authentication for secrets
gh auth login
#+END_SRC

2. Set up secrets management:

#+BEGIN_SRC shell
# 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
#+END_SRC

3. Build and run the container:

#+BEGIN_SRC shell
# Build the Docker/Podman image
make build

# Run the container (automatically retrieves secrets)
make run
#+END_SRC

3. Test the environment:

#+BEGIN_SRC shell
# Verify MCP server connectivity
make test

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

** Command Reference

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)

*** Custom Claude Commands

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

*** Using MCP Run Python Directly

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

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

Example usage:

#+BEGIN_SRC bash
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
#+END_SRC

To access the algorithms in this repository, use:

#+BEGIN_SRC python
import sys
sys.path.append('.')
from algorithms.factorial import factorial_iterative

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

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.

*** Scripts

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.

** Development Workflow

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~

*** Branch and Issue Management

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.)

*** Project Milestones

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

** Project Goals

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

** Educational Resources

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

** References

- [[https://www.anthropic.com/news/model-context-protocol][Anthropic: Introducing the Model Context Protocol]] - Official announcement of MCP as an open standard for connecting AI assistants to data sources.

- [[https://modelcontextprotocol.io/introduction][Model Context Protocol Documentation]] - Comprehensive documentation explaining MCP concepts, architecture, and implementation details.

- [[https://github.com/modelcontextprotocol][Model Context Protocol GitHub]] - Official GitHub organization with protocol specification, SDKs, and reference implementations.

- [[https://docs.anthropic.com/en/docs/agents-and-tools/mcp][Anthropic MCP Documentation]] - Integration guides and best practices for using MCP with Claude.

- [[https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview][Claude Code Documentation]] - Official documentation for Claude Code CLI.

- [[https://github.com/microsoft/multilspy][Microsoft MultilspyLSP]] - The Python library for creating language server clients that powers our LSP integration.

- [[https://github.com/python-lsp/python-lsp-server][Python LSP Server]] - The Python implementation of the Language Server Protocol used in this project.

- [[https://microsoft.github.io/language-server-protocol/][Language Server Protocol]] - Background on the LSP standard that enables editor-agnostic language intelligence.

- [[https://playbooks.com/mcp/asimihsan-multilspy-lsp][MultilspyLSP MCP Server]] - Reference implementation of an MCP server that provides LSP capabilities.

- [[https://news.ycombinator.com/item?id=43691230][Hacker News: Model Context Protocol Discussion]] - Community discussion about MCP, including perspectives on security considerations and integration approaches.

- [[https://simonwillison.net/2025/Apr/18/mcp-run-python/][Simon Willison: MCP Run Python]] - Detailed exploration of the MCP run-python implementation and its practical applications.

** License

MIT License