lucasw89/openproject-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Lucas Winther
2026-09-06 18:11:58 +02:00
parent ebb47eb659
commit 9bfedf8a8b
3 changed files with 31 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE.md
+1
View File
@@ -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
+19 -24
View File
@@ -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
docs/specs/2026-09-06-mcp-tools-design.md
+11
View File
@@ -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