initial commit after one day coding agent session

QUICKSTART.md

@@ -0,0 +1,106 @@
+# 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
+```