106 lines
2 KiB
Markdown
106 lines
2 KiB
Markdown
# 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
|
|
```
|