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

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.

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

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)

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.

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