#+TITLE: isolated-pymcp #+AUTHOR: Aidan Pace #+EMAIL: apace@defrecord.com #+DATE: 2025-04-20

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.

** 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
Limited port exposure
Controlled API access via environment variables
Clear security domain boundaries between components

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

Initial setup:

#+BEGIN_SRC shell

Create required directories

make dirs

Generate configuration files from org sources

make tangle

Create environment configuration (edit with your API keys)

cp .envrc.example .envrc #+END_SRC

Build and run the container:

#+BEGIN_SRC shell

Build the Docker/Podman image

make build

Run the container with mounted volumes

make run #+END_SRC

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~ for a full list of available commands.

Key commands:

~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

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.

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

When making changes:

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

** Project Goals

Demonstrate secure integration between MCP and LSP
Provide a reference architecture for isolated AI code analysis
Enable exploration of Python algorithm implementations
Support multiple client interfaces while maintaining security

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

Categories

Current Category: isolation

isolated-pymcp