docs(spec): add specification for hosted remote MCP server and multi-tenant credential scoping
This commit is contained in:
Lucas Winther
@@ -0,0 +1,200 @@
|
|||||||
|
# Specification: Hosted Remote MCP Server (HTTP/SSE Transport) & Multi-Tenant Scoping
|
||||||
|
|
||||||
|
## 1. Overview & Objectives
|
||||||
|
|
||||||
|
Currently, `openproject-mcp` runs as a local subprocess communicating via standard input/output (stdio) transports. Every user must have Docker or Bun installed locally and run their own MCP process.
|
||||||
|
|
||||||
|
This specification introduces a **Hosted Remote MCP Server** capability. Organizations can deploy a single hosted instance of `openproject-mcp` (e.g. at `https://mcp.example.com`). Individual users and their AI clients (Claude Desktop, Cursor, web agents) connect directly to the hosted server over the standard Model Context Protocol HTTP/SSE (Server-Sent Events) transport, supplying their own personal OpenProject API keys.
|
||||||
|
|
||||||
|
### Primary Objectives
|
||||||
|
1. **Hosted Multi-Tenant Remote Server**: Provide an HTTP/SSE server implementation based on native `Bun.serve` and `@modelcontextprotocol/sdk`.
|
||||||
|
2. **Dual-Transport Entrypoint**: Preserve existing local stdio operation by default; activate HTTP/SSE transport when `PORT` (e.g., `PORT=3000`) or `--port` is supplied.
|
||||||
|
3. **Flexible Credential Scoping**: Extract the user's OpenProject API key from incoming client requests via:
|
||||||
|
- `Authorization: Bearer <key>`
|
||||||
|
- `X-OpenProject-Api-Key: <key>`
|
||||||
|
- URL query parameter `?apiKey=<key>`
|
||||||
|
4. **Single-Instance Multi-User Isolation**: Target a shared OpenProject base URL (`OPENPROJECT_BASE_URL`) configured on the server, while strictly isolating each client's requests inside `RequestContext` (`AsyncLocalStorage`) using their respective personal API key.
|
||||||
|
5. **Unauthorized Rejection**: Return clean HTTP 401 Unauthorized responses if a client connects without an API key.
|
||||||
|
6. **Docker Compose Deployment**: Provide a `docker-compose.server.yml` file and `README.md` guide for hosting the server with health checks.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Architecture & Data Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
+------------------------------------+ +------------------------------------+
|
||||||
|
| User A (Cursor / Claude Desktop) | | User B (Claude Desktop / Agent) |
|
||||||
|
| Headers: X-OpenProject-Api-Key: keyA| | URL: /sse?apiKey=keyB |
|
||||||
|
+-----------------+------------------+ +-----------------+------------------+
|
||||||
|
| (GET /sse) | (GET /sse)
|
||||||
|
+-----------------------+-------------------+
|
||||||
|
|
|
||||||
|
v
|
||||||
|
+------------------------------+
|
||||||
|
| Hosted openproject-mcp Server |
|
||||||
|
| (Bun.serve on PORT=3000) |
|
||||||
|
+--------------+---------------+
|
||||||
|
|
|
||||||
|
+-----------------+-----------------+
|
||||||
|
| Session A | Session B
|
||||||
|
| Client A (key: keyA) | Client B (key: keyB)
|
||||||
|
| McpServer A (runWithContext) | McpServer B (runWithContext)
|
||||||
|
+-----------------+-----------------+
|
||||||
|
|
|
||||||
|
v
|
||||||
|
+------------------------------+
|
||||||
|
| OpenProject 17 REST API v3 |
|
||||||
|
| (Shared OPENPROJECT_BASE_URL)|
|
||||||
|
+------------------------------+
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.1 HTTP Endpoints
|
||||||
|
|
||||||
|
1. **`GET /health`**:
|
||||||
|
- Responds with HTTP 200:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "ok",
|
||||||
|
"mode": "remote-mcp",
|
||||||
|
"openproject": "https://openproject.example.com",
|
||||||
|
"readOnly": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- Used by load balancers, Kubernetes probes, and Docker health checks.
|
||||||
|
|
||||||
|
2. **`GET /sse`**:
|
||||||
|
- Establishes a persistent Server-Sent Events (SSE) connection with the client.
|
||||||
|
- Extracts the API key from:
|
||||||
|
1. `Authorization: Bearer <token>`
|
||||||
|
2. `X-OpenProject-Api-Key: <token>`
|
||||||
|
3. Query parameter `?apiKey=<token>`
|
||||||
|
- If missing: Rejects immediately with HTTP 401 and JSON error message:
|
||||||
|
```json
|
||||||
|
{ "error": "Missing OpenProject API key. Provide via Authorization header, X-OpenProject-Api-Key header, or ?apiKey= query parameter." }
|
||||||
|
```
|
||||||
|
- If present:
|
||||||
|
- Generates a cryptographically random `sessionId`.
|
||||||
|
- Creates an isolated `OpenProjectClient({ baseUrl, apiKey })`.
|
||||||
|
- Creates an `SSEServerTransport` bound to `/messages?sessionId=${sessionId}`.
|
||||||
|
- Creates an `McpServer` instance with all tools registered and wrapped with `runWithContext`.
|
||||||
|
- Stores the session in `activeSessions: Map<string, SessionData>`.
|
||||||
|
- Streams the initial `endpoint` SSE event to the client.
|
||||||
|
|
||||||
|
3. **`POST /messages`**:
|
||||||
|
- URL contains `?sessionId=<id>`.
|
||||||
|
- Looks up the session in `activeSessions`.
|
||||||
|
- If session not found: Returns HTTP 404 Not Found.
|
||||||
|
- Forwards the JSON-RPC request to the session transport's message handler, ensuring tool execution resolves the session's client via `runWithContext`.
|
||||||
|
|
||||||
|
4. **Session Eviction**:
|
||||||
|
- On SSE connection close or error, `transport.onclose` evicts the session from `activeSessions` to prevent memory leaks.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Configuration & CLI Flags
|
||||||
|
|
||||||
|
### Configuration Extension (`src/config/index.ts`)
|
||||||
|
```typescript
|
||||||
|
export interface AppConfig {
|
||||||
|
baseUrl: string;
|
||||||
|
apiKey?: string; // Optional when running in hosted HTTP mode
|
||||||
|
readOnly: boolean;
|
||||||
|
port?: number; // When present, launches HTTP/SSE server instead of stdio
|
||||||
|
host?: string; // Default: "0.0.0.0"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- When `port` is defined (`process.env.PORT` or `--port <num>`):
|
||||||
|
- `apiKey` is optional at server startup because individual connecting users supply their own keys.
|
||||||
|
- Server starts in HTTP mode.
|
||||||
|
- When `port` is undefined:
|
||||||
|
- Server runs in stdio mode (requires `OPENPROJECT_API_KEY` in environment).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Docker Compose Setup (`docker-compose.server.yml`)
|
||||||
|
|
||||||
|
A ready-to-run Docker Compose file for deploying the hosted MCP server:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: "3.8"
|
||||||
|
|
||||||
|
services:
|
||||||
|
openproject-mcp:
|
||||||
|
image: ghcr.io/stereotypicalcat/openproject-mcp:latest
|
||||||
|
container_name: openproject-mcp-hosted
|
||||||
|
restart: unless-stopped
|
||||||
|
ports:
|
||||||
|
- "3000:3000"
|
||||||
|
environment:
|
||||||
|
- OPENPROJECT_BASE_URL=https://openproject.example.com
|
||||||
|
- PORT=3000
|
||||||
|
- OPENPROJECT_READ_ONLY=false
|
||||||
|
healthcheck:
|
||||||
|
test: ["CMD-SHELL", "bun -e 'fetch(\"http://localhost:3000/health\").then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))'"]
|
||||||
|
interval: 30s
|
||||||
|
timeout: 5s
|
||||||
|
retries: 3
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Client Configuration Examples
|
||||||
|
|
||||||
|
### Cursor
|
||||||
|
Add to `.cursor/mcp.json` (or Cursor Settings > Features > MCP):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"openproject": {
|
||||||
|
"url": "https://mcp.example.com/sse",
|
||||||
|
"headers": {
|
||||||
|
"X-OpenProject-Api-Key": "your-personal-api-key"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Or via URL query parameter:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"openproject": {
|
||||||
|
"url": "https://mcp.example.com/sse?apiKey=your-personal-api-key"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Claude Desktop
|
||||||
|
In clients that connect to remote SSE servers via standard proxy or direct URL:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"openproject": {
|
||||||
|
"url": "https://mcp.example.com/sse?apiKey=your-personal-api-key"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Verification & Test Plan
|
||||||
|
|
||||||
|
1. **Unit & Protocol Tests (`tests/http-server.test.ts`)**:
|
||||||
|
- `GET /health` returns HTTP 200 with status info.
|
||||||
|
- `GET /sse` without credentials returns HTTP 401.
|
||||||
|
- `GET /sse` with `Authorization: Bearer <key>` succeeds and returns SSE stream.
|
||||||
|
- `GET /sse` with `X-OpenProject-Api-Key: <key>` succeeds.
|
||||||
|
- `GET /sse` with `?apiKey=<key>` succeeds.
|
||||||
|
- Concurrent clients with different API keys execute tools with their own respective credentials without bleed.
|
||||||
|
- Disconnecting client evicts session from memory.
|
||||||
|
2. **CLI & Entrypoint Tests**:
|
||||||
|
- `PORT=3000` boots the HTTP server.
|
||||||
|
- CLI flags `--port 3000` boots the HTTP server.
|
||||||
|
3. **Docker Compose Validation**:
|
||||||
|
- Validate `docker-compose.server.yml` configuration and verify container runs in HTTP mode.
|
||||||
|
4. **Documentation**:
|
||||||
|
- Record ADR-016 in `docs/DECISIONS.md`.
|
||||||
|
- Update `README.md` with Hosted Remote Server and Docker Compose deployment instructions.
|
||||||
Reference in New Issue
Block a user