mcp-forge/README.md

# MCP-Forge

**Secure Python Execution Server with Model Context Protocol (MCP) Support**

MCP-Forge provides a secure, containerized Python execution environment that integrates with the Model Context Protocol. It enables AI assistants and other MCP clients to execute Python code safely with resource limits, security controls, and audit logging.

## Features

- **🔒 Secure Execution**: Podman-based container isolation with resource limits
- **🎯 MCP Protocol**: Native integration with Model Context Protocol for AI assistants
- **📊 Dual Backends**: 
  - Simple backend for stateless code execution
  - Jupyter backend for stateful sessions with kernel persistence
- **🛡️ Security Controls**: 
  - Package allowlist/blocklist validation
  - Resource limits (memory, CPU, timeout, storage)
  - Comprehensive audit logging
- **🔧 Environment Building**: Dynamic Python environment creation with `uv`
- **🌉 MCP Bridge**: Connect to external MCP tool servers (stdio, HTTP, SSE)
  - Support for stdio-based MCP servers (command-line tools)
  - HTTP transport for REST API-based MCP servers
  - SSE transport for Server-Sent Events MCP servers

## Quick Start

### Installation

```bash
git clone <repository>
cd mcp-forge
uv sync
```

### Configuration

1. Copy example configuration:
```bash
cp config.example.yaml config.yaml
```

2. Update Podman socket path in `config.yaml`:
```yaml
server:
  podman_socket: /run/user/1000/podman/podman.sock
```

3. Start Podman socket:
```bash
systemctl --user start podman.socket
```

### Running the Server

```bash
# stdio transport (for MCP clients)
uv run mcp-forge --config config.yaml

# HTTP transport (REST API)
uv run mcp-forge --config config.yaml --transport http --port 8011

# SSE transport (Server-Sent Events)
uv run mcp-forge --config config.yaml --transport sse --port 8080

# Alternative: using Python module
uv run python -m mcp_forge --config config.yaml --transport http --port 8011
```

### CLI Options

```
--config PATH        Path to configuration file (required)
--host HOST          Server host address (default: localhost)
--port PORT          Server port (default: 3000)
--transport TYPE     Transport protocol: stdio or sse (default: stdio)
--verbose, -v        Enable verbose logging
```

## MCP Client Integration

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "mcp-forge": {
      "command": "uv",
      "args": ["run", "mcp-forge", "--config", "/absolute/path/to/config.yaml"]
    }
  }
}
```

## Available MCP Tools

### `execute_python`
Execute Python code in isolated container:
```python
{
  "code": "print(2 + 2)",
  "timeout": 30,
  "memory": "512m"
}
```

### `build_environment`
Create custom Python environment with packages:
```python
{
  "python_version": "3.11",
  "packages": ["requests", "pandas"]
}
```

### `document_state`
Manage Jupyter session state:
```python
{
  "session_id": "user_session",
  "code": "x = 42",
  "clear": false
}
```

## Architecture

```
┌─────────────────┐
│   MCP Client    │
│ (Claude/Other)  │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│  MCP-Forge      │
│   Server        │
├─────────────────┤
│ • Tool Handlers │
│ • MCP Bridge    │
│ • Security      │
│ • Audit Logger  │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│    Podman       │
│   Containers    │
├─────────────────┤
│ • Python 3.11   │
│ • Python 3.12   │
│ • Jupyter       │
└─────────────────┘
```

## Security

- **Container Isolation**: Each execution runs in isolated Podman container
- **Resource Limits**: Memory, CPU, timeout, and storage quotas enforced
- **Package Validation**: Allowlist/blocklist for package installation
- **Audit Logging**: All operations logged with timestamps and metadata
- **Network Restrictions**: Containers run without network access by default

## Testing

```bash
# Run all tests
uv run pytest

# Run specific test suite
uv run pytest tests/server/ -v

# Integration tests (requires Podman)
uv run pytest tests/integration/ -v
```

**Test Status**: 388 tests passing, 27 integration tests pending Phase 5.4

## Configuration Reference

See [`config.example.yaml`](config.example.yaml) for complete configuration options.

Key sections:
- `server`: Host, port, Podman socket
- `security`: Audit log, resource enforcement
- `execution`: Timeouts, memory limits, backends
- `images`: Container image configuration
- `sessions`: Jupyter session management
- `environment_builder`: Package validation, caching

## Development

### Project Structure

```
mcp-forge/
├── src/mcp_forge/
│   ├── server/          # MCP server implementation
│   ├── config/          # Configuration schemas
│   ├── security/        # Security & audit
│   ├── podman/          # Container management
│   ├── execution/       # Execution backends
│   ├── builder/         # Environment building
│   └── mcp/             # MCP protocol integration
├── tests/               # Test suite
├── config/              # Default configurations
└── docs/                # Documentation
```

### Running Tests

```bash
# Unit tests
uv run pytest tests/ -v

# With coverage
uv run pytest --cov=mcp_forge --cov-report=html

# Specific module
uv run pytest tests/execution/ -v
```

## Troubleshooting

### Podman Socket Not Found
```bash
systemctl --user status podman.socket
systemctl --user start podman.socket
```

### Permission Denied
Check socket permissions:
```bash
ls -l /run/user/$(id -u)/podman/podman.sock
```

### Container Images
Pull and tag images:
```bash
podman pull python:3.11-slim
podman tag python:3.11-slim mcp-forge/python:3.11
```

## License

[Add license information]

## Contributing

[Add contribution guidelines]

## Documentation

- [Quick Start Guide](docs/QUICKSTART.md)
- [HTTP Transport Configuration](docs/HTTP_TRANSPORT.md)
- [Project Status](docs/STATUS.md)
- [Architecture Overview](docs/architecture1.md)
- [Development TODO](docs/todo.md)