232 lines
14 KiB
Markdown
232 lines
14 KiB
Markdown
# Architecture Documentation: openproject-mcp
|
|
|
|
## 1. System Overview
|
|
|
|
`openproject-mcp` is a Model Context Protocol (MCP) server providing LLM applications (Claude Desktop, Cursor, Antigravity, etc.) with structured access to an OpenProject instance. The server interfaces with OpenProject's REST API v3 using personal API keys, exposing tools and resources for browsing and querying projects, work packages, custom queries, taxonomies, and users.
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
subgraph Clients ["MCP Clients (Multi-User)"]
|
|
UserA["User A Client\n(Key A)"]
|
|
UserB["User B Client\n(Key B)"]
|
|
end
|
|
|
|
subgraph Transports ["Transport Layer"]
|
|
Stdio["Stdio Transport\n(Personal Process Isolation)"]
|
|
SSE["SSE / HTTP Transport\n(Shared Central Daemon)"]
|
|
end
|
|
|
|
subgraph ContextLayer ["Session & Request Context Provider"]
|
|
ALS["AsyncLocalStorage /\nSession Context Resolver"]
|
|
CtxA["RequestContext A\n(Client A, Key A)"]
|
|
CtxB["RequestContext B\n(Client B, Key B)"]
|
|
end
|
|
|
|
subgraph DomainServices ["Domain Services (Stateless)"]
|
|
ProjSvc["Projects Service"]
|
|
WpSvc["Work Packages Service"]
|
|
QuerySvc["Queries Service"]
|
|
MetaSvc["Metadata & Taxonomies"]
|
|
end
|
|
|
|
subgraph Remote ["OpenProject Instance"]
|
|
ApiV3["OpenProject REST API v3\n(/api/v3 - RBAC Enforced)"]
|
|
end
|
|
|
|
UserA -->|stdio or HTTP headers| Stdio
|
|
UserB -->|HTTP headers| SSE
|
|
Stdio --> ALS
|
|
SSE --> ALS
|
|
ALS --> CtxA
|
|
ALS --> CtxB
|
|
CtxA --> DomainServices
|
|
CtxB --> DomainServices
|
|
DomainServices -->|Authenticated API Requests| ApiV3
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Core Architectural Layers
|
|
|
|
The system is organized into four modular layers:
|
|
|
|
### 2.1. MCP Server & Transport Layer
|
|
- **Runtime**: **Bun** (>= 1.2/1.3) providing native TypeScript execution without build steps, automatic `.env` loading, and fast startup for CLI/stdio subprocesses.
|
|
- **Responsibility**: Manages the MCP connection lifecycle, tool definitions, input validation, and JSON-RPC dispatching.
|
|
- **Protocol**: MCP specification implemented via `@modelcontextprotocol/sdk`.
|
|
- **Default Transport**: `StdioServerTransport` for local integration with desktop clients and CLI tools.
|
|
- **Schema Validation**: Each tool declares its arguments using Zod schemas, automatically generating standard JSON Schema definitions for the LLM.
|
|
|
|
### 2.2. Domain Services / Tool Providers
|
|
Domain services map MCP tool calls to concrete business logic and OpenProject API operations:
|
|
- **Projects Service**: Listing accessible projects, retrieving project details, and fetching project-level schemas.
|
|
- **Work Packages Service**: Listing work packages with filters, searching by text or ID, retrieving work package details, and inspecting relations.
|
|
- **Queries Service**: Listing saved queries (views) configured in OpenProject and executing them.
|
|
- **Metadata & Taxonomies Service**: Retrieving statuses, work package types, priorities, categories, versions, and users to enable LLMs to construct valid queries and interpret responses.
|
|
|
|
### 2.3. OpenProject Client Layer
|
|
- **HTTP Transport**: Handles HTTPS communication against the configured `OPENPROJECT_BASE_URL`.
|
|
- **Authentication Handler**: Enforces OpenProject API v3 authentication by injecting `Authorization: Basic base64(apikey:<api_key>)` headers.
|
|
- **HAL+JSON Parser**: OpenProject API v3 represents entities using HAL+JSON format (`_links`, `_embedded`). The parser unwraps links, extracts embedded entities, and converts them into clean, token-efficient JSON structures for LLM consumption.
|
|
- **Query Filter Builder**: Serializes user-friendly filtering parameters into OpenProject's JSON-based filter query syntax (e.g. `filters=[{"status_id":{"operator":"o","values":[]}}]`).
|
|
- **Error Normalizer**: Intercepts HTTP 4xx/5xx responses and maps them to descriptive MCP tool errors without exposing sensitive credential data.
|
|
|
|
### 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_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.
|
|
|
|
### 2.5. Read-Only Execution Mode
|
|
The server supports a dedicated read-only operating mode designed for auditing, reporting, and exploratory agent workflows:
|
|
- **Tool Filtering**: When read-only mode is active, only read/browse/query tools are registered in the MCP tool registry. Mutating tools (creating work packages, updating attributes, logging time) are completely excluded from the tool manifest exposed to the LLM.
|
|
- **Defense-in-Depth Guard**: In addition to tool manifest omission, the internal tool router validates whether an operation is a mutating action. Any write attempt is immediately rejected with a structured error (`SERVER_READ_ONLY: Server is operating in read-only mode. Write operations are disabled.`).
|
|
- **Safe Auditing**: Guarantees zero unintentional data modification or state changes in the OpenProject instance.
|
|
|
|
---
|
|
|
|
## 3. Multi-User Concurrency & Request-Scoped Architecture
|
|
|
|
The server is architected from the ground up to support concurrent, multi-user operations safely without cross-user credential leakage, state bleed, or privilege escalation.
|
|
|
|
### 3.1. Core Concurrency Rules
|
|
1. **Zero Global Mutable State**: No global singleton `OpenProjectClient` or static API key variable exists.
|
|
2. **Stateless Domain Services**: All domain services (`ProjectsService`, `WorkPackagesService`, etc.) are stateless and operate exclusively on the `RequestContext` resolved for the active execution.
|
|
3. **RequestContext Interface**:
|
|
```typescript
|
|
export interface RequestContext {
|
|
client: OpenProjectClient;
|
|
isReadOnly: boolean;
|
|
sessionId?: string;
|
|
userId?: string;
|
|
}
|
|
```
|
|
4. **Context Propagation via AsyncLocalStorage**:
|
|
In Bun/TypeScript, request context is propagated down asynchronous call trees using `AsyncLocalStorage<RequestContext>`. Tool handlers access `getRequestContext()` to obtain their session's isolated client and read-only flags cleanly.
|
|
|
|
### 3.2. Supported Deployment Models
|
|
|
|
#### Model A: Local Personal Desktop (Stdio Transport - Default)
|
|
- **Deployment**: The MCP client (Claude Desktop, Cursor, local CLI) spawns `openproject-mcp` as a dedicated child process communicating via standard input/output.
|
|
- **Isolation**: OS-level process and memory boundary.
|
|
- **Credentials**: Passed via process environment variables or local MCP client configuration.
|
|
- **Security**: Complete isolation. Zero network ports exposed.
|
|
|
|
#### Model B: Centralized Shared Server (SSE / HTTP Transport)
|
|
- **Deployment**: A single shared `openproject-mcp` daemon runs centrally for a team or cluster.
|
|
- **Isolation**: Connection and request-level isolation.
|
|
- **Credential Delivery via Headers**:
|
|
- Each connecting client supplies their OpenProject API token via standard HTTP headers during connection handshake and request dispatch:
|
|
- `Authorization: Basic base64(apikey:<USER_API_KEY>)`, or
|
|
- `X-OpenProject-API-Key: <USER_API_KEY>`
|
|
- Optional: `X-OpenProject-Read-Only: true`
|
|
- The transport layer extracts the credentials, instantiates an ephemeral scoped `OpenProjectClient`, and executes tool calls inside `requestContextStorage.run(context, ...)`.
|
|
- **RBAC Enforcement**: All calls execute against OpenProject REST API v3 using that specific user's token. OpenProject's internal Role-Based Access Control guarantees users only retrieve projects and work packages they have permission to access.
|
|
- **Lifecycle**: Ephemeral client instances and tokens reside only in active session memory and are garbage collected upon connection close.
|
|
|
|
---
|
|
|
|
## 4. Tool Specifications (Browse & Query Scope)
|
|
|
|
| MCP Tool Name | Description | Key Parameters |
|
|
| :--- | :--- | :--- |
|
|
| `openproject_list_projects` | List projects accessible to the authenticated user | `pageSize`, `offset`, `sortBy` |
|
|
| `openproject_get_project` | Get details of a single project by ID or identifier | `projectId` (number or string identifier) |
|
|
| `openproject_list_work_packages` | Browse work packages with filtering and pagination | `projectId`, `status`, `type`, `pageSize`, `offset`, `filters` |
|
|
| `openproject_get_work_package` | Get full details of a specific work package | `workPackageId` (number) |
|
|
| `openproject_list_queries` | List saved project or global queries (views) | `projectId`, `pageSize`, `offset` |
|
|
| `openproject_get_query` | Retrieve details and results of a saved query | `queryId` (number) |
|
|
| `openproject_list_types` | List all available work package types (Task, Bug, Milestone, etc.) | None |
|
|
| `openproject_list_statuses` | List all available work package statuses (New, In Progress, Closed, etc.) | None |
|
|
| `openproject_list_priorities` | List all priority levels | None |
|
|
| `openproject_list_users` | List users in the OpenProject instance | `pageSize`, `offset` |
|
|
| `openproject_get_openapi_spec` | Retrieve OpenProject API v3 OpenAPI specification for schema introspection | `path` |
|
|
|
|
---
|
|
|
|
## 5. OpenProject API v3 Specifics
|
|
|
|
### 5.1. Authentication Details
|
|
OpenProject API v3 utilizes HTTP Basic Authentication for API tokens:
|
|
```http
|
|
GET /api/v3/projects HTTP/1.1
|
|
Host: openproject.example.com
|
|
Authorization: Basic YXBpa2V5OnlvdXItb3BlbnByb2plY3QtYXBpLWtleQ==
|
|
Accept: application/hal+json
|
|
```
|
|
Where `YXBpa2V5OnlvdXItb3BlbnByb2plY3QtYXBpLWtleQ==` is the Base64 encoding of `apikey:<your-api-key>`.
|
|
|
|
### 5.2. HAL+JSON Handling
|
|
API responses contain `_links` linking to related resources (parent project, author, assignee, status, type). The client layer normalizes these into human-readable labels and numeric IDs so the LLM agent can reason over them easily.
|
|
|
|
### 5.3. Filter Syntax Translation
|
|
OpenProject filters are passed via a URL-encoded JSON string array. Example:
|
|
```json
|
|
[
|
|
{ "status_id": { "operator": "o", "values": [] } },
|
|
{ "project": { "operator": "=", "values": ["12"] } }
|
|
]
|
|
```
|
|
The client layer provides helper builders so tools can accept friendly parameters (e.g. `{ onlyOpen: true, projectId: 12 }`) and translate them automatically into the required format.
|
|
|
|
---
|
|
|
|
## 6. Security & Isolation
|
|
|
|
1. **Token Protection**: Credentials are read from environment variables or per-connection HTTP headers. Tokens are never echoed in logs or tool payloads.
|
|
2. **Permission Boundary**: The MCP server operates strictly within the permission scope of the provided API key. No elevated access is granted beyond what the user possesses in OpenProject.
|
|
3. **Input Sanitization**: All arguments from the LLM are validated via Zod schemas prior to making network requests, preventing request-smuggling or path traversal.
|
|
4. **Transport Isolation**: The default stdio transport communicates only through standard input/output with the host client process, with no exposed network ports.
|
|
5. **Read-Only Enforcement**: Configurable read-only mode (`OPENPROJECT_READ_ONLY=true`) guarantees zero write side-effects on the OpenProject instance when operating in exploratory or untrusted agent sessions.
|
|
6. **Multi-Tenant Memory Isolation**: Ephemeral `RequestContext` instances isolated via `AsyncLocalStorage` guarantee zero token bleed or cross-user contamination in concurrent shared server environments.
|
|
|
|
---
|
|
|
|
## 7. Project Directory Structure
|
|
|
|
```
|
|
openproject-mcp/
|
|
├── docs/
|
|
│ ├── ARCHITECTURE.md # System architecture and specifications
|
|
│ ├── DECISIONS.md # Architecture Decision Records (ADR)
|
|
│ └── TODO.md # Task tracking and roadmap
|
|
├── src/
|
|
│ ├── index.ts # CLI entry point and startup
|
|
│ ├── server.ts # MCP server instance & tool registration
|
|
│ ├── context.ts # RequestContext & AsyncLocalStorage
|
|
│ ├── client/
|
|
│ │ ├── api-client.ts # OpenProject REST API v3 HTTP client
|
|
│ │ ├── hal-parser.ts # HAL+JSON parsing and transformation
|
|
│ │ ├── filter-builder.ts # OpenProject JSON filter builder
|
|
│ │ └── types.ts # OpenProject API type definitions
|
|
│ ├── config/
|
|
│ │ └── index.ts # Configuration loader and Zod schema
|
|
│ ├── services/
|
|
│ │ ├── projects.ts # Projects domain service
|
|
│ │ ├── work-packages.ts # Work packages domain service
|
|
│ │ ├── queries.ts # Queries domain service
|
|
│ │ └── metadata.ts # Types, statuses, priorities, users
|
|
│ └── tools/
|
|
│ ├── project-tools.ts # MCP tool definitions for projects
|
|
│ ├── work-package-tools.ts# MCP tool definitions for work packages
|
|
│ └── metadata-tools.ts # MCP tool definitions for metadata
|
|
├── tests/
|
|
│ ├── fixtures/ # HAL+JSON mock fixtures
|
|
│ ├── client.test.ts # OpenProject client unit tests
|
|
│ └── tools.test.ts # MCP tool integration tests
|
|
├── AGENTS.md # Operating guidelines for AI agents
|
|
├── package.json # Project dependencies and scripts
|
|
├── bun.lock # Bun dependency lockfile
|
|
└── tsconfig.json # TypeScript compiler configuration (Bun bundler mode)
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Future Roadmap
|
|
|
|
- **Phase 1 (Current)**: Read/browse capability for projects, work packages, queries, and taxonomies with request-scoped context.
|
|
- **Phase 2**: Mutating operations (create/update work packages, add comments, log time).
|
|
- **Phase 3**: Attachment inspection and download resources.
|
|
- **Phase 4**: SSE / Stream transport for remote multi-user server deployments.
|