From 9bfedf8a8b2e75934c689c7a350243798691f93f Mon Sep 17 00:00:00 2001 From: Lucas Winther Date: Sun, 6 Sep 2026 18:11:58 +0200 Subject: [PATCH] docs: add OpenAPI support requirement to spec, architecture, and plan --- docs/ARCHITECTURE.md | 1 + docs/plans/2026-09-06-mcp-tools-plan.md | 43 ++++++++++------------- docs/specs/2026-09-06-mcp-tools-design.md | 11 ++++++ 3 files changed, 31 insertions(+), 24 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index ead1530..e53157d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -141,6 +141,7 @@ The server is architected from the ground up to support concurrent, multi-user o | `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` | --- diff --git a/docs/plans/2026-09-06-mcp-tools-plan.md b/docs/plans/2026-09-06-mcp-tools-plan.md index 48bb6af..bb04f08 100644 --- a/docs/plans/2026-09-06-mcp-tools-plan.md +++ b/docs/plans/2026-09-06-mcp-tools-plan.md @@ -584,7 +584,7 @@ git commit -m "feat(tools): implement work package tools and registration" - `queryTools`: ToolDefinition[] - `registerQueryTools(server: McpServer): void` -- [ ] **Step 1: Write failing tests for query tools** +- [x] **Step 1: Write failing tests for query tools** In `tests/tools.test.ts`: ```typescript @@ -692,12 +692,12 @@ describe("Query Tools", () => { }); ``` -- [ ] **Step 2: Run test to verify it fails** +- [x] **Step 2: Run test to verify it fails** Run: `bun test tests/tools.test.ts` Expected: FAIL with module `../src/tools/queries` not found. -- [ ] **Step 3: Implement query tools** +- [x] **Step 3: Implement query tools** In `src/tools/queries.ts`: ```typescript @@ -765,12 +765,12 @@ export function registerQueryTools(server: McpServer): void { } ``` -- [ ] **Step 4: Run test to verify it passes** +- [x] **Step 4: Run test to verify it passes** Run: `bun test tests/tools.test.ts` Expected: PASS. -- [ ] **Step 5: Commit** +- [x] **Step 5: Commit** ```bash git add src/tools/queries.ts tests/tools.test.ts @@ -799,7 +799,7 @@ git commit -m "feat(tools): implement query tools and registration" - `metadataTools`: ToolDefinition[] - `registerMetadataTools(server: McpServer): void` -- [ ] **Step 1: Write failing tests for metadata tools** +- [x] **Step 1: Write failing tests for metadata tools** In `tests/tools.test.ts`: ```typescript @@ -919,12 +919,12 @@ describe("Metadata Tools", () => { }); ``` -- [ ] **Step 2: Run test to verify it fails** +- [x] **Step 2: Run test to verify it fails** Run: `bun test tests/tools.test.ts` Expected: FAIL with module `../src/tools/metadata` not found. -- [ ] **Step 3: Implement metadata tools** +- [x] **Step 3: Implement metadata tools** In `src/tools/metadata.ts`: ```typescript @@ -1028,12 +1028,12 @@ export function registerMetadataTools(server: McpServer): void { } ``` -- [ ] **Step 4: Run test to verify it passes** +- [x] **Step 4: Run test to verify it passes** Run: `bun test tests/tools.test.ts` Expected: PASS. -- [ ] **Step 5: Commit** +- [x] **Step 5: Commit** ```bash git add src/tools/metadata.ts tests/tools.test.ts @@ -1055,7 +1055,7 @@ git commit -m "feat(tools): implement metadata tools and registration" - `registerAllTools(server: McpServer, options?: { readOnly?: boolean }): void` - Re-exports of all individual tools, shapes, and handlers -- [ ] **Step 1: Write failing tests for tool registry** +- [x] **Step 1: Write failing tests for tool registry** In `tests/tools.test.ts`: ```typescript @@ -1094,12 +1094,12 @@ describe("Tool Registry", () => { }); ``` -- [ ] **Step 2: Run test to verify it fails** +- [x] **Step 2: Run test to verify it fails** Run: `bun test tests/tools.test.ts` Expected: FAIL with module `../src/tools/index` not found. -- [ ] **Step 3: Implement tool registry** +- [x] **Step 3: Implement tool registry** In `src/tools/index.ts`: ```typescript @@ -1140,12 +1140,12 @@ export function registerAllTools(server: McpServer, options?: RegisterToolsOptio } ``` -- [ ] **Step 4: Run test to verify it passes** +- [x] **Step 4: Run test to verify it passes** Run: `bun test tests/tools.test.ts` Expected: PASS. -- [ ] **Step 5: Commit** +- [x] **Step 5: Commit** ```bash git add src/tools/index.ts tests/tools.test.ts @@ -1159,12 +1159,7 @@ git commit -m "feat(tools): add tool registry and barrel export" **Files:** - Modify: `tests/tools.test.ts` - Modify: `docs/TODO.md` - -**Interfaces:** -- Consumes: Live OpenProject 17 container on `http://localhost:8080`, `OpenProjectClient`, `runWithContext`, `allTools` -- Produces: Live end-to-end integration tests verifying every tool against real OpenProject data. - -- [ ] **Step 1: Add live integration tests for all 10 tools** +- [x] **Step 1: Add live integration tests for all 10 tools** In `tests/tools.test.ts`: ```typescript @@ -1260,16 +1255,16 @@ describe("Live Container Integration (All 10 MCP Tools)", () => { }); ``` -- [ ] **Step 2: Run all tests against live container** +- [x] **Step 2: Run all tests against live container** Run: `bun test` Expected: All tests pass (client, smoke, services, tools). -- [ ] **Step 3: Update `docs/TODO.md`** +- [x] **Step 3: Update `docs/TODO.md`** Mark Task 3 as completed in `docs/TODO.md`. -- [ ] **Step 4: Commit** +- [x] **Step 4: Commit** ```bash git add tests/tools.test.ts docs/TODO.md diff --git a/docs/specs/2026-09-06-mcp-tools-design.md b/docs/specs/2026-09-06-mcp-tools-design.md index bff25ca..adfd67a 100644 --- a/docs/specs/2026-09-06-mcp-tools-design.md +++ b/docs/specs/2026-09-06-mcp-tools-design.md @@ -54,6 +54,12 @@ Per ADR-003 and ADR-004, tool handlers do NOT store global client references. In ### 2.3 Read-Only Safety All Phase 1 tools are read-only (`readOnly: true`). When `OPENPROJECT_READ_ONLY=true` or `--read-only` is active, read-only tools remain accessible while mutating tools (in Phase 2) are filtered out and rejected with `SERVER_READ_ONLY`. +### 2.4 OpenAPI Specification Support +OpenProject REST API v3 publishes a comprehensive, machine-readable OpenAPI 3.0 specification at `/api/v3/openapi.json`. +The MCP server architecture mandates first-class support for OpenAPI: +1. **Dynamic Schema Introspection**: Provide capability to fetch and query OpenProject's OpenAPI 3.0 specification so LLM agents can dynamically discover available endpoints, parameters, allowed filter operations, and custom field constraints. +2. **OpenAPI / JSON Schema Compatibility**: All MCP tool schemas and parameter definitions must strictly conform to OpenAPI 3.0 / JSON Schema specifications to ensure universal interoperability with MCP clients and LLM function-calling engines. + --- ## 3. Tool Specifications @@ -124,6 +130,11 @@ All tool names are prefixed with `openproject_` using `snake_case` in accordance - `pageSize` (optional integer, 1-100, default: 20): Number of users per page. - `offset` (optional integer, >= 1, default: 1): Page number to retrieve. +### 3.11 `openproject_get_openapi_spec` +- **Description**: Retrieve OpenProject API v3's OpenAPI 3.0 specification (`/api/v3/openapi.json`) for dynamic schema introspection, endpoint discovery, and entity definitions. +- **Parameters**: + - `path` (optional string): Specific endpoint path or tag to retrieve (e.g. `"/api/v3/work_packages"` or `"Work Packages"`) to conserve LLM context tokens, or omitted to retrieve full metadata. + --- ## 4. MCP Response & Error Handling