README - mcp-server-as-http-python by yonaka15

MCP HTTP Server - Python Runtime

A Docker-optimized HTTP server for Python Model Context Protocol (MCP) servers, currently featuring typst-mcp with plans for universal Python MCP server support.

🐍 Python Focused: Optimized for Python MCP servers with automatic dependency management and virtual environment support.

🎯 MVP with typst-mcp: Currently configured for typst-mcp server, easily extensible to other Python MCP servers.

🚀 Future Roadmap: Designed for universal Python MCP server compatibility including filesystem, web-search, and custom servers.

🏗️ Architecture

mcp-server-as-http-python/
├── Dockerfile              # Python 3.12 optimized container
├── docker-compose.yml      # Docker Compose configuration  
├── docker-build.sh         # Build and deployment script
├── docker-entrypoint.sh    # Initialization script
├── mcp_servers.config.json # MCP server configuration
├── .env.example            # Environment template
└── README.md               # This file

Core Components:

Pre-built Binary: Uses mcp-server-as-http-core binary (Rust-based HTTP server)
Python Environment: Python 3.13 with pip and virtual environment
Dynamic Dependencies: Typst binary and Rust toolchain installed only when needed
Docker Optimization: Multi-stage build for minimal runtime image

🚀 Quick Start

Prerequisites

Docker and Docker Compose
Git (for repository cloning)

Option 1: Docker Compose (Recommended)

# Clone repository
git clone https://github.com/yonaka15/mcp-server-as-http-python.git
cd mcp-server-as-http-python

# Copy and configure environment
cp .env.example .env
# Edit .env with your settings

# Start with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

Option 2: Build Script

# Clone repository
git clone https://github.com/yonaka15/mcp-server-as-http-python.git
cd mcp-server-as-http-python

# Copy and configure environment  
cp .env.example .env
# Edit .env with your settings

# Build and run
./docker-build.sh

# Or use docker-compose via script
./docker-build.sh --use-compose

Option 3: Manual Docker

# Build image
docker build -t mcp-http-server-python .

# Run container
docker run -d \\
  --name mcp-http-server-python \\
  -p 3000:3000 \\
  --env-file .env \\
  mcp-http-server-python

⚙️ Configuration

Environment Variables

Variable	Default	Description
`MCP_CONFIG_FILE`	`mcp_servers.config.json`	Path to MCP servers configuration
`MCP_SERVER_NAME`	`typst-mcp`	Server name to use from config
`MCP_RUNTIME_TYPE`	`python`	Runtime type (fixed for this image)
`PORT`	`3000`	HTTP server port
`HTTP_API_KEY`	-	Bearer token for authentication
`DISABLE_AUTH`	`true`	Disable authentication (default for development)
`WORK_DIR`	`/tmp/mcp-servers`	Working directory for MCP servers

Automatic MCP Server Management

The mcp-server-as-http-core automatically handles:

Repository Cloning: Automatically clones the configured MCP server repository
Dependency Installation: Executes build_command to install required dependencies
Runtime Management: Launches and manages the MCP server process
Dynamic Setup: No manual installation needed - everything is configured via JSON

This approach provides maximum flexibility while maintaining simplicity.

Python MCP Server Configuration

The typst-mcp server provides powerful LaTeX to Typst conversion capabilities:

{
  "version": "1.0",
  "servers": {
    "typst-mcp": {
      "repository": "https://github.com/johannesbrandenburger/typst-mcp.git",
      "build_command": "pip install mcp[cli] numpy pillow",
      "command": "/app/venv/bin/python3",
      "args": ["server.py"],
      "env": {
        "PYTHONPATH": "/tmp/mcp-servers/typst-mcp",
        "VIRTUAL_ENV": "/app/venv",
        "PATH": "/app/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
      }
    }
  }
}

🛠️ API Usage

With Authentication

curl -X POST http://localhost:3000/api/v1 \\
  -H "Authorization: Bearer your-secret-api-key" \\
  -H "Content-Type: application/json" \\
  -d '{"command": "{\\"jsonrpc\\": \\"2.0\\", \\"id\\": 1, \\"method\\": \\"tools/list\\", \\"params\\": {}}"}'

Without Authentication (Default)

Development mode with DISABLE_AUTH=true:

curl -X POST http://localhost:3000/api/v1 \\
  -H "Content-Type: application/json" \\
  -d '{"command": "{\\"jsonrpc\\": \\"2.0\\", \\"id\\": 1, \\"method\\": \\"tools/list\\", \\"params\\": {}}"}'

Test typst-mcp LaTeX Conversion

curl -X POST http://localhost:3000/api/v1 \\
  -H "Content-Type: application/json" \\
  -d '{"command": "{\\"jsonrpc\\": \\"2.0\\", \\"id\\": 1, \\"method\\": \\"tools/call\\", \\"params\\": {\\"name\\": \\"latex_snippet_to_typst\\", \\"arguments\\": {\\"latex_snippet\\": \\"$f \\\\in K(t^H, \\\\beta)_\\\\delta$\\"}}}"}'

Health Check

curl -f http://localhost:3000/health

🎯 typst-mcp Features

The current MVP focuses on typst-mcp server capabilities:

Available Tools

list_docs_chapters(): Lists all chapters in the Typst documentation
get_docs_chapter(route): Retrieves specific chapter from Typst documentation
latex_snippet_to_typst(latex_snippet): Converts LaTeX code to Typst using Pandoc
check_if_snippet_is_valid_typst_syntax(typst_snippet): Validates Typst code
typst_snippet_to_image(typst_snippet): Renders Typst code to PNG image

Example Workflow

# 1. List available tools
curl -X POST http://localhost:3000/api/v1 \\
  -H "Content-Type: application/json" \\
  -d '{"command": "{\\"jsonrpc\\": \\"2.0\\", \\"id\\": 1, \\"method\\": \\"tools/list\\", \\"params\\": {}}"}'

# 2. Convert LaTeX to Typst
curl -X POST http://localhost:3000/api/v1 \\
  -H "Content-Type: application/json" \\
  -d '{"command": "{\\"jsonrpc\\": \\"2.0\\", \\"id\\": 2, \\"method\\": \\"tools/call\\", \\"params\\": {\\"name\\": \\"latex_snippet_to_typst\\", \\"arguments\\": {\\"latex_snippet\\": \\"\\\\begin{align} a &= b \\\\\\\\ c &= d \\\\end{align}\\"}}}"}'

# 3. Validate Typst syntax
curl -X POST http://localhost:3000/api/v1 \\
  -H "Content-Type: application/json" \\
  -d '{"command": "{\\"jsonrpc\\": \\"2.0\\", \\"id\\": 3, \\"method\\": \\"tools/call\\", \\"params\\": {\\"name\\": \\"check_if_snippet_is_valid_typst_syntax\\", \\"arguments\\": {\\"typst_snippet\\": \\"$f in K \\\\( t^H \\\\, beta \\\\)_delta$\\"}}}"}'

🔮 Future Roadmap

This project is designed for universal Python MCP server support:

Planned MCP Servers

{
  "filesystem": {
    "repository": "https://github.com/modelcontextprotocol/python-sdk.git",
    "build_command": "cd examples/server && pip install -e ../../",
    "command": "/app/venv/bin/python3",
    "args": ["examples/server/filesystem.py", "/tmp/mcp-servers"]
  },
  "web-search": {
    "repository": "https://github.com/modelcontextprotocol/servers.git", 
    "build_command": "cd src/brave_search && pip install -r requirements.txt",
    "command": "/app/venv/bin/python3",
    "args": ["src/brave_search/server.py"]
  },
  "memory": {
    "repository": "https://github.com/modelcontextprotocol/servers.git",
    "build_command": "cd src/memory && pip install -r requirements.txt", 
    "command": "/app/venv/bin/python3",
    "args": ["src/memory/server.py"]
  }
}

Extension Strategy

Multi-server Configuration: Switch between different MCP servers via environment variables
Automatic Dependency Management: Auto-detect and install Python dependencies per server
Runtime Detection: Support for different Python MCP server patterns
Plugin System: Easy addition of new Python MCP servers

🐳 Docker Features

Multi-Stage Build

Stage 1: Builds the Rust core binary with optimized settings
Stage 2: Python 3.12 Alpine runtime with essential tools

Python Optimizations

Virtual environment management (/app/venv)
Git repository cloning and building
Pandoc for LaTeX conversion
Typst binary for document generation
Non-root user execution

Security

Non-root user execution (mcpuser)
Minimal runtime dependencies
Health check endpoints

📊 Monitoring and Management

View Logs

# Docker Compose
docker-compose logs -f

# Docker
docker logs -f mcp-http-server-python

Container Management

# Docker Compose
docker-compose up -d      # Start
docker-compose down       # Stop
docker-compose restart    # Restart

# Docker
docker start mcp-http-server-python
docker stop mcp-http-server-python
docker restart mcp-http-server-python

Health Monitoring

# Check container health
docker inspect mcp-http-server-python | grep -A 10 Health

# Manual health check
curl -f http://localhost:3000/health

# Check running processes
docker exec mcp-http-server-python ps aux

🔧 Development and Debugging

Build Options

# Build without cache
./docker-build.sh --no-cache

# Build only (don't run)
./docker-build.sh --build-only

# Custom port
./docker-build.sh --port 3000

# Use docker-compose
./docker-build.sh --use-compose

Debugging

# Execute shell in container
docker exec -it mcp-http-server-python /bin/sh

# Check Python environment
docker exec mcp-http-server-python python3 --version
docker exec mcp-http-server-python pip --version

# Check virtual environment
docker exec mcp-http-server-python ls -la /app/venv/

# Check typst-mcp installation
docker exec mcp-http-server-python ls -la /tmp/mcp-servers/typst-mcp/

# Test typst binary
docker exec mcp-http-server-python typst --version

# Test pandoc
docker exec mcp-http-server-python pandoc --version

🔗 Related Projects

mcp-server-as-http-core: Core Rust HTTP server
typst-mcp: Typst document generation server
python-sdk: Official Python MCP SDK

🤝 Contributing

Fork the repository
Clone your fork: git clone <your-fork>
Create a feature branch
Make your changes (focus on Python MCP server support)
Test with ./docker-build.sh --build-only
Submit a pull request

Adding New MCP Servers

To add support for additional Python MCP servers:

Update mcp_servers.config.json with new server configuration
Add any required system dependencies to Dockerfile
Update environment variables in .env.example
Add documentation and examples to README.md

📄 License

This project is open source under the MIT License. See the LICENSE file for details.

⚠️ Important Notes

Docker Required: This implementation is Docker-only and requires Docker to run
Python Focus: Optimized specifically for Python MCP servers
typst-mcp MVP: Currently configured for typst-mcp, extensible to other servers
Future Universal: Designed for easy extension to any Python MCP server

🔄 Updates

To update to the latest core server:

# Rebuild with latest core
./docker-build.sh --no-cache

# Or with docker-compose
docker-compose build --no-cache

🆘 Support

Issues: Report bugs and request features in this repository
Core Issues: For HTTP server core functionality, use the core repository
typst-mcp: For typst-mcp specific issues, use the typst-mcp repository

🚀 Deployment Options

Development

# Quick development setup
cp .env.example .env
echo "DISABLE_AUTH=true" >> .env
echo "MCP_SERVER_NAME=typst-mcp" >> .env
docker-compose up -d

Production

# Production setup with authentication
cp .env.example .env
echo "DISABLE_AUTH=false" >> .env
echo "HTTP_API_KEY=your-secure-api-key-here" >> .env
echo "MCP_SERVER_NAME=typst-mcp" >> .env
docker-compose up -d

Built with ❤️ for the MCP (Model Context Protocol) community

🐳 Docker-optimized • 🐍 Python-focused • 📝 typst-mcp ready • 🚀 Universally extensible