# my-mcp
my-mcp is a Model Context Protocol (MCP) server built with FastMCP featuring dynamic tool loading.
## Features
- **Dynamic Tool Loading**: Tools are automatically discovered and loaded from `src/tools/`
- **One Tool Per File**: Each tool is a single file with a function matching the filename
- **FastMCP Integration**: Leverages FastMCP for robust MCP protocol handling
- **Configuration Management**: Tool-specific configuration via `mcp.yaml`
- **Fail-Fast**: Server won't start if any tool fails to load
- **Auto-Generated Tests**: Automatic test generation for tool validation
## Project Structure
```
src/
├── tools/ # Tool implementations (one file per tool)
│ ├── echo.py # Example echo tool
│ └── __init__.py # Auto-generated tool registry
├── core/ # Dynamic loading framework
│ ├── server.py # Dynamic MCP server
│ └── utils.py # Shared utilities
└── main.py # Entry point
mcp.yaml # Configuration file
tests/ # Generated tests
```
## Quick Start
### Option 1: Local Development (with Python/uv)
1. **Install Dependencies**:
```bash
uv sync
```
2. **Run the Server**:
```bash
# Stdio mode (default MCP transport)
uv run python src/main.py
# HTTP mode with WebSocket MCP endpoint
uv run python src/main.py --http
# HTTP mode with custom host/port
uv run python src/main.py --http --host 0.0.0.0 --port 8080
```
3. **Using uv Scripts**:
```bash
# Development mode (HTTP on port 3000)
uv run dev
# HTTP mode
uv run dev-http
# Stdio mode
uv run start
```
4. **Add New Tools**:
```bash
# Create a new tool (no tool types needed!)
arctl mcp add-tool weather
# The tool file will be created at src/tools/weather.py
# Edit it to implement your tool logic
```
### Option 2: Docker-Only Development (no local Python/uv required)
1. **Build Docker Image**:
```bash
arctl mcp build --verbose
```
2. **Run in Container**:
```bash
docker run -i my-mcp:latest
```
3. **Add New Tools**:
```bash
# Create a new tool
arctl mcp add-tool weather
# Edit the tool file, then rebuild
arctl mcp build
```
## HTTP Transport Mode
The server supports running in HTTP mode for development and integration purposes.
### Starting in HTTP Mode
```bash
# Command line flag
python src/main.py --http
# Environment variable
MCP_TRANSPORT_MODE=http python src/main.py
# Custom host and port
python src/main.py --http --host localhost --port 8080
```
## Creating Tools
### Basic Tool Structure
Each tool is a Python file in `src/tools/` containing a function decorated with `@mcp.tool()`:
```python
# src/tools/weather.py
from core.server import mcp
from core.utils import get_tool_config, get_env_var
@mcp.tool()
def weather(location: str) -> str:
"""Get weather information for a location."""
# Get tool configuration
config = get_tool_config("weather")
api_key = get_env_var(config.get("api_key_env", "WEATHER_API_KEY"))
base_url = config.get("base_url", "https://api.openweathermap.org/data/2.5")
# TODO: Implement weather API call
return f"Weather for {location}: Sunny, 72°F"
```
### Tool Examples
The generated tool template includes commented examples for common patterns:
```python
# HTTP API calls
# async with httpx.AsyncClient() as client:
# response = await client.get(f"{base_url}/weather?q={location}&appid={api_key}")
# return response.json()
# Database operations
# async with asyncpg.connect(connection_string) as conn:
# result = await conn.fetchrow("SELECT * FROM weather WHERE location = $1", location)
# return dict(result)
# File processing
# with open(file_path, 'r') as f:
# content = f.read()
# return {"content": content, "size": len(content)}
```
## Configuration
Configure tools in `mcp.yaml`:
```yaml
tools:
weather:
api_key_env: "WEATHER_API_KEY"
base_url: "https://api.openweathermap.org/data/2.5"
timeout: 30
database:
connection_string_env: "DATABASE_URL"
max_connections: 10
```
## Testing
Run the generated tests to verify your tools load correctly:
```bash
uv run pytest tests/
```
## Development
### Adding Dependencies
Update `pyproject.toml` and run:
```bash
uv sync
```
### Code Quality
```bash
uv run black .
uv run ruff check .
uv run mypy .
```
## Deployment
### Docker
```bash
# Build image (handles lockfile automatically)
arctl mcp build
# Run container
docker run -i my-mcp:latest
```
