Skip to content

Commit 70f1a7e

Browse files
crivetimihaicrivetimihai
committed
Add CLAUDE.md
Signed-off-by: Mihai Criveti <[email protected]>
1 parent 9bc7edb commit 70f1a7e

File tree

1 file changed

+212
-0
lines changed

1 file changed

+212
-0
lines changed

‎CLAUDE.md

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
MCP Gateway (ContextForge) is a production-grade gateway, proxy, and registry for Model Context Protocol (MCP) servers. It federates MCP and REST services, providing unified discovery, auth, rate-limiting, observability, virtual servers, multi-transport protocols, and an optional Admin UI.
8+
9+
## Development Commands
10+
11+
### Core Development Workflow
12+
13+
```bash
14+
# Setup and Installation
15+
make venv # Create virtual environment
16+
make install-dev # Install with development dependencies
17+
make install-db # Install with database adapters (Redis, PostgreSQL)
18+
19+
# Running the Gateway
20+
make dev # Run with hot reload on port 8000 (uvicorn)
21+
make serve # Run production server (gunicorn)
22+
mcpgateway --host 0.0.0.0 --port 4444 # Run directly via CLI
23+
24+
# Testing
25+
make doctest # Run all doctest
26+
make test # Run all tests with coverage
27+
pytest tests/unit/ # Run specific test directory
28+
pytest -k "test_name" # Run specific test by name
29+
30+
# Code Quality
31+
make lint # Run all linters on mcpgateway/
32+
make lint-web # Run linters for web files (html, js, css)
33+
make check-manifest # Verify MANIFEST.in completeness
34+
35+
# Build & Distribution
36+
make dist # Build wheel and sdist packages
37+
```
38+
39+
### Authentication & Token Generation
40+
41+
```bash
42+
# Generate JWT bearer token
43+
python3 -m mcpgateway.utils.create_jwt_token \
44+
--username admin --exp 10080 --secret my-test-key
45+
46+
# Export for API calls
47+
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
48+
--username admin --exp 0 --secret my-test-key)
49+
```
50+
51+
### Working with MCP Servers
52+
53+
```bash
54+
# Run mcpgateway.translate to expose stdio servers via HTTP/SSE
55+
python3 -m mcpgateway.translate \
56+
--stdio "uvx mcp-server-git" --port 9000
57+
58+
# Run the stdio wrapper for MCP clients
59+
export MCP_AUTH_TOKEN=$MCPGATEWAY_BEARER_TOKEN
60+
export MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/UUID
61+
python3 -m mcpgateway.wrapper
62+
```
63+
64+
## Architecture Overview
65+
66+
### Core Components
67+
68+
The gateway is built on **FastAPI** with **Pydantic** for validation and **SQLAlchemy** for persistence. Key architectural decisions are documented in `docs/docs/architecture/adr/`.
69+
70+
### Directory Structure
71+
72+
- **`mcpgateway/`** - Main application code
73+
- `main.py` - FastAPI application entry point
74+
- `cli.py` - Command-line interface
75+
- `models.py` - SQLAlchemy ORM models
76+
- `schemas.py` - Pydantic schemas for validation
77+
- `config.py` - Settings management via environment variables
78+
- `admin.py` - Admin UI routes (HTMX + Alpine.js)
79+
80+
- **`mcpgateway/services/`** - Business logic layer
81+
- `gateway_service.py` - Federation and peer gateway management
82+
- `server_service.py` - Virtual server composition
83+
- `tool_service.py` - Tool registry and invocation
84+
- `resource_service.py` - Resource caching and updates
85+
- `prompt_service.py` - Prompt template management
86+
87+
- **`mcpgateway/transports/`** - Protocol implementations
88+
- `sse_transport.py` - Server-Sent Events
89+
- `websocket_transport.py` - WebSocket bidirectional
90+
- `stdio_transport.py` - Standard I/O for CLI tools
91+
- `streamablehttp_transport.py` - HTTP streaming
92+
93+
- **`mcpgateway/plugins/`** - Plugin framework
94+
- `framework/` - Plugin loader, manager, and registry
95+
- Plugin configurations in `plugins/config.yaml`
96+
97+
### Database & Caching
98+
99+
- **SQLite** default (`sqlite:///./mcp.db`)
100+
- **PostgreSQL** support via `psycopg2-binary`
101+
- **Redis** for distributed caching and federation
102+
- **Alembic** for database migrations (`mcpgateway/alembic/`)
103+
104+
### Service Federation
105+
106+
The gateway supports multi-instance federation:
107+
- Auto-discovery via mDNS/Zeroconf
108+
- Manual peer registration via API
109+
- Health checks and automatic failover
110+
- Shared tool/resource catalogs across peers
111+
112+
### Virtual Servers
113+
114+
Virtual servers bundle tools, prompts, and resources:
115+
- Compose multiple MCP servers into one logical unit
116+
- Control tool visibility per virtual server
117+
- Support multiple protocol endpoints per server
118+
119+
## Key Environment Variables
120+
121+
```bash
122+
# Core Settings
123+
HOST=0.0.0.0
124+
PORT=4444
125+
DATABASE_URL=sqlite:///./mcp.db # or postgresql://...
126+
REDIS_URL=redis://localhost:6379
127+
128+
# Authentication
129+
JWT_SECRET_KEY=your-secret-key
130+
BASIC_AUTH_USER=admin
131+
BASIC_AUTH_PASSWORD=changeme
132+
AUTH_REQUIRED=true
133+
134+
# UI & Admin
135+
MCPGATEWAY_UI_ENABLED=true
136+
MCPGATEWAY_ADMIN_API_ENABLED=true
137+
138+
# Federation
139+
MCPGATEWAY_ENABLE_MDNS_DISCOVERY=true
140+
MCPGATEWAY_ENABLE_FEDERATION=true
141+
142+
# Development
143+
LOG_LEVEL=INFO
144+
RELOAD=true # For development hot-reload
145+
```
146+
147+
## Testing Strategy
148+
149+
### Unit Tests
150+
- Located in `tests/unit/`
151+
- Cover all services, transports, and utilities
152+
- Use pytest fixtures for database and async testing
153+
154+
### Integration Tests
155+
- Located in `tests/integration/`
156+
- Test API endpoints and cross-service workflows
157+
- Mock external dependencies
158+
159+
### UI Tests
160+
- Located in `tests/playwright/`
161+
- Use Playwright for browser automation
162+
- Test admin UI interactions and real-time features
163+
164+
### Running Specific Tests
165+
```bash
166+
# Run tests for a specific module
167+
pytest tests/unit/mcpgateway/services/test_tool_service.py
168+
169+
# Run with verbose output
170+
pytest -v tests/
171+
172+
# Run with specific markers
173+
pytest -m "not slow"
174+
```
175+
176+
## Common Development Tasks
177+
178+
### Adding a New MCP Server
179+
1. Start the server (e.g., via `mcpgateway.translate` for stdio servers)
180+
2. Register it as a gateway peer via POST `/gateways`
181+
3. Create a virtual server bundling its tools via POST `/servers`
182+
4. Access via the virtual server's SSE/WebSocket endpoints
183+
184+
### Debugging Federation Issues
185+
1. Check peer health: `GET /gateways`
186+
2. Verify mDNS discovery: `MCPGATEWAY_ENABLE_MDNS_DISCOVERY=true`
187+
3. Check Redis connectivity if using distributed cache
188+
4. Review logs for connection errors
189+
190+
### Plugin Development
191+
1. Create plugin in `plugins/your_plugin/`
192+
2. Add manifest in `plugin-manifest.yaml`
193+
3. Register in `plugins/config.yaml`
194+
4. Implement required hooks (pre/post request/response)
195+
196+
## API Endpoints Overview
197+
198+
### Core MCP Operations
199+
- `POST /` - JSON-RPC endpoint for MCP protocol
200+
- `GET /servers/{id}/sse` - SSE transport for MCP
201+
- `WS /servers/{id}/ws` - WebSocket transport
202+
203+
### Admin APIs (when enabled)
204+
- `GET/POST /tools` - Tool management
205+
- `GET/POST /resources` - Resource management
206+
- `GET/POST /prompts` - Prompt templates
207+
- `GET/POST /servers` - Virtual servers
208+
- `GET/POST /gateways` - Peer gateways
209+
- `GET /admin` - Admin UI dashboard
210+
211+
# You have access to cli tools
212+
- You can use `gh` for github commands, e.g. gh issue view 586

0 commit comments

Comments
 (0)