# MCP-Forge Quick Start Guide

## Installation

```bash
# Install from source
git clone <repository>
cd mcp-forge
uv sync
```

## Configuration

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

2. Edit `config.yaml` to set your Podman socket path:
```yaml
server:
  podman_socket: /run/user/1000/podman/podman.sock  # Update this
```

3. Ensure Podman is running:
```bash
systemctl --user start podman.socket
```

## Running the Server

### stdio Transport (default)
```bash
mcp-forge --config config.yaml
```

### SSE Transport (HTTP)
```bash
mcp-forge --config config.yaml --transport sse --host 0.0.0.0 --port 8080
```

## Command-Line 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 Configuration

To use with an MCP client (e.g., Claude Desktop), add to your client config:

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

## Testing

Run the test suite:
```bash
uv run pytest
```

Run specific tests:
```bash
uv run pytest tests/server/test_server_integration.py -v
```

## Architecture

- **Simple Backend**: Stateless Python execution in fresh containers
- **Jupyter Backend**: Stateful sessions with kernel persistence
- **Security**: Resource limits, package validation, audit logging
- **MCP Integration**: Bridge to external MCP tool servers

## Troubleshooting

### Podman Socket Not Found
Ensure Podman socket is running:
```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
Build or pull required images:
```bash
podman pull python:3.11-slim
podman tag python:3.11-slim mcp-forge/python:3.11
```