From 914883957e9484c1a9e5f343cf7d63b095e1c9d1 Mon Sep 17 00:00:00 2001 From: Lucas Winther Date: Mon, 7 Sep 2026 01:20:29 +0200 Subject: [PATCH] docs: ensure consistent PORT and HOST_PORT documentation across codebase and docs --- .env.example | 9 ++++++++- README.md | 1 + docs/ARCHITECTURE.md | 6 ++++-- docs/DECISIONS.md | 2 +- src/config/index.ts | 3 ++- 5 files changed, 16 insertions(+), 5 deletions(-) diff --git a/.env.example b/.env.example index e4954d1..b39ed1a 100644 --- a/.env.example +++ b/.env.example @@ -17,9 +17,16 @@ OPENPROJECT_HOST__NAME=localhost:8080 OPENPROJECT_HTTPS=false SECRET_KEY_BASE=openproject-secret-key-base-for-local-testing-at-least-64-characters-long -# MCP Server Client Configuration +# MCP Server Client Configuration (Stdio Mode) # Once the container is running and seeded via scripts/seed.sh, # OPENPROJECT_API_KEY will be automatically written to .env.test OPENPROJECT_BASE_URL=http://localhost:8080 OPENPROJECT_API_KEY= OPENPROJECT_READ_ONLY=false + +# Hosted Remote MCP Server Configuration (HTTP/SSE Mode) +# When PORT (or HOST_PORT) is set, openproject-mcp runs as an HTTP/SSE server. +# In HTTP mode, connecting clients supply their own API keys, so OPENPROJECT_API_KEY is optional. +# PORT=3000 +# HOST=0.0.0.0 +# HOST_PORT=3000 diff --git a/README.md b/README.md index 87ce4b5..673f053 100644 --- a/README.md +++ b/README.md @@ -418,6 +418,7 @@ The MCP server accepts configuration through environment variables, CLI argument | `OPENPROJECT_API_KEY` | Personal API token (required in stdio mode; supplied per-client in HTTP mode) | - | | `OPENPROJECT_READ_ONLY` | Run server in read-only mode (`true` / `false` or `--read-only`) | `false` | | `PORT` | HTTP server port when running hosted MCP server, or web port for local dev stack | `3000` (MCP) / `8080` (test stack) | +| `HOST_PORT` | Optional environment fallback for `PORT`, and host-side port in `docker-compose.server.yml` | `3000` | | `HOST` | Bind host for hosted HTTP server | `0.0.0.0` | | `TAG` | OpenProject container image tag (local test stack) | `17-slim` | | `POSTGRES_VERSION` | PostgreSQL container image tag (local test stack) | `17` | diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index ae733b0..7a8f1ad 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -75,9 +75,11 @@ Domain services map MCP tool calls to concrete business logic and OpenProject AP ### 2.4. Configuration & Environment Layer - Parses and validates configuration at startup: - `OPENPROJECT_BASE_URL`: Base URL of the OpenProject instance (e.g., `https://openproject.example.com`). - - `OPENPROJECT_API_KEY`: User API key generated in OpenProject under "My Account > Access tokens". + - `OPENPROJECT_API_KEY`: User API key generated in OpenProject under "My Account > Access tokens" (required in stdio mode; optional in HTTP/SSE mode). - `OPENPROJECT_READ_ONLY`: Boolean flag (`true` / `false`, default: `false`). Can also be set via `--read-only` CLI argument. -- Fails fast with actionable setup advice if required credentials are missing or invalid. + - `PORT`: HTTP server listening port (e.g. `3000` or `--port `). When set, activates HTTP/SSE remote transport. Supports `HOST_PORT` as an environment variable fallback. + - `HOST`: Server bind address (or `--host `, default: `0.0.0.0`). +- Fails fast with actionable setup advice if required credentials are missing or invalid in stdio mode. ### 2.5. Read-Only Execution Mode The server supports a dedicated read-only operating mode designed for auditing, reporting, and exploratory agent workflows: diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 68b033d..68a68d8 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -376,7 +376,7 @@ Accepted Key requirements for hosted operation: 1. **Multi-Tenant Credential Scoping**: A single server process connects to a shared OpenProject base URL (`OPENPROJECT_BASE_URL`), but every connecting user/agent must use their own personal OpenProject API token. User credentials must never bleed across sessions or be retained in global mutable memory. -2. **Dual-Transport Entrypoint**: The server CLI must support both local stdio execution and hosted HTTP/SSE execution via configuration (`PORT` / `--port`). +2. **Dual-Transport Entrypoint**: The server CLI must support both local stdio execution and hosted HTTP/SSE execution via configuration (`PORT`, `HOST_PORT` fallback, or `--port`). 3. **Flexible Authentication**: Clients must be able to authenticate via standard headers (`Authorization: Bearer `, `X-OpenProject-Api-Key: `) or query parameters (`?apiKey=`) for SSE-compatible desktop and web clients. 4. **Health & Lifecycle Management**: Provide standardized `/health` endpoints and clean session eviction on client disconnect to prevent memory leaks. diff --git a/src/config/index.ts b/src/config/index.ts index f4a2eee..6d2e477 100644 --- a/src/config/index.ts +++ b/src/config/index.ts @@ -21,7 +21,8 @@ export const configSchema = z if (data.port === undefined && (!data.apiKey || data.apiKey.trim().length === 0)) { ctx.addIssue({ code: z.ZodIssueCode.custom, - message: "OPENPROJECT_API_KEY is required in stdio mode (when port is not set)", + message: + "OPENPROJECT_API_KEY is required in stdio mode (set PORT, HOST_PORT, or --port to run as an HTTP server)", path: ["apiKey"], }); }