docs: record ADR-015, update README with Docker usage, and update TODO.md

2026-09-06 20:48:55 +02:00
parent 2b93ebe0a1
commit a30d913470
3 changed files with 117 additions and 0 deletions
@@ -26,6 +26,91 @@ It allows agents to browse, query, and reason about OpenProject workspaces using

 ---

+## Running via Docker
+
+You can run `openproject-mcp` without installing Bun or cloning this repository by using the container image published to GitHub Container Registry (`ghcr.io`).
+
+### Docker Quickstart
+
+Run interactively with standard I/O streaming:
+
+```bash
+docker run -i --rm \
+  -e OPENPROJECT_BASE_URL="https://openproject.example.com" \
+  -e OPENPROJECT_API_KEY="your-api-key" \
+  ghcr.io/stereotypicalcat/openproject-mcp:latest
+```
+
+### Read-Only Mode
+
+To ensure the server strictly restricts capabilities to read-only queries and inspection:
+
+```bash
+docker run -i --rm \
+  -e OPENPROJECT_BASE_URL="https://openproject.example.com" \
+  -e OPENPROJECT_API_KEY="your-api-key" \
+  ghcr.io/stereotypicalcat/openproject-mcp:latest --read-only
+```
+
+*(Alternatively, pass `-e OPENPROJECT_READ_ONLY=true`.)*
+
+### MCP Client Configuration
+
+#### Claude Desktop
+
+Add the following to your `claude_desktop_config.json`:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "openproject": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "OPENPROJECT_BASE_URL=https://openproject.example.com",
+        "-e",
+        "OPENPROJECT_API_KEY=your-api-key",
+        "ghcr.io/stereotypicalcat/openproject-mcp:latest",
+        "--read-only"
+      ]
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add the following to `.cursor/mcp.json` (or Cursor Settings > Features > MCP):
+
+```json
+{
+  "mcpServers": {
+    "openproject": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "OPENPROJECT_BASE_URL=https://openproject.example.com",
+        "-e",
+        "OPENPROJECT_API_KEY=your-api-key",
+        "ghcr.io/stereotypicalcat/openproject-mcp:latest",
+        "--read-only"
+      ]
+    }
+  }
+}
+```
+
+---
+
 ## Quickstart: Local OpenProject Test Stack

 A complete OpenProject 17 environment with PostgreSQL 17 and Memcached is included via Docker Compose for local testing and agentic validation.
@@ -339,3 +339,27 @@ Support OpenAPI 3.0 specification retrieval as an MCP tool (`openproject_get_ope
  - Automatically adapts to installed OpenProject plugins and API extensions on target instances.
 - **Negative**:
  - Requires handling large JSON payloads efficiently when requesting full OpenAPI definitions.
+
+---
+
+## ADR-015: Docker Container Packaging and GitHub Actions CI/CD Pipeline
+
+### Status
+Accepted
+
+### Context
+Users and client LLM applications (such as Claude Desktop, Cursor, or containerized agents) require a lightweight, zero-dependency method to run `openproject-mcp` without manually installing Bun or local development dependencies. Furthermore, pull requests and releases require automated validation to guarantee that tests pass and container images are securely built and published to GitHub Container Registry (`ghcr.io`).
+
+### Decision
+1. **Runtime Base Image**: Adopt `oven/bun:1-slim` with a multi-stage Docker build. The builder stage installs production dependencies (`bun install --frozen-lockfile --production`), and the runner stage copies only production node_modules and application sources.
+2. **Security & Permissions**: Run container execution under the unprivileged `bun` user (UID 1000). Exclude sensitive environment files (`.env*`), git records, and local tokens via `.dockerignore`.
+3. **Multi-Architecture**: Build container images for both `linux/amd64` and `linux/arm64` via Docker Buildx and QEMU.
+4. **Interactive Stdio Execution**: Configure container `ENTRYPOINT ["bun", "run", "src/index.ts"]` with standard I/O streaming, allowing runtime options (such as `--read-only`) to be appended directly.
+5. **Continuous Integration**: Implement a two-stage GitHub Actions workflow (`.github/workflows/ci.yml`):
+   - `test`: Executes `bun run typecheck` and `bun test` on PRs and main pushes.
+   - `docker`: Builds multi-arch images with `type=gha` cache, publishing to `ghcr.io` on pushes to `main` and release tags (`v*.*.*`), while validating builds without push on pull requests.
+
+### Consequences
+- Provides seamless Docker execution for desktop and server MCP clients via `docker run -i --rm ghcr.io/<owner>/openproject-mcp:latest`.
+- Prevents container build regressions through automated PR verification.
+- Guarantees multi-architecture compatibility across Apple Silicon and x86_64 host machines.
@@ -88,6 +88,14 @@
  - [x] Add comprehensive test suite in `tests/openapi.test.ts` covering service methods, MCP client execution, error handling, and live OpenProject 17 container integration.
  - [x] Update suite regressions and assertions across all test suites (`tests/tools.test.ts`, `tests/read-only.test.ts`, `tests/mcp-server.test.ts`).

+- [x] **Task 6: Docker Container Packaging & CI/CD Pipeline**
+  - [x] Created multi-stage [Dockerfile](../Dockerfile) using `oven/bun:1-slim` builder and unprivileged `bun` user runner.
+  - [x] Created [.dockerignore](../.dockerignore) excluding secrets, local dependencies, test files, and docs from build context.
+  - [x] Implemented GitHub Actions CI workflow [.github/workflows/ci.yml](../.github/workflows/ci.yml) with automated type checking, testing, and multi-arch Docker image publishing (`linux/amd64`, `linux/arm64`) to `ghcr.io`.
+  - [x] Added automated test coverage in [tests/docker.test.ts](../tests/docker.test.ts) and [tests/ci-workflow.test.ts](../tests/ci-workflow.test.ts).
+  - [x] Recorded [ADR-015](DECISIONS.md#adr-015-docker-container-packaging-and-github-actions-cicd-pipeline).
+  - [x] Updated [README.md](../README.md) with Docker Quickstart, read-only mode instructions, and client integration settings (Claude Desktop & Cursor).
+
 ---

 ## 3. Backlog & Future Phases