docs: add OpenAPI support requirement to spec, architecture, and plan

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` |
 
 ---
 

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`
-
+- [x] **Step 1: Add live integration tests for all 10 tools**
-**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**
 
 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

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