docs: add design spec for meetings, wikis, and activities tools

2026-09-07 02:09:14 +02:00
parent 75531eca2d
commit e08eac3a2b
1 changed files with 229 additions and 0 deletions
@@ -0,0 +1,229 @@
+# Specification: Meetings, Wikis, and Work Package Activities MCP Tools
+
+## 1. Overview & Objectives
+
+This specification defines the extension of the `openproject-mcp` server with seven new read-only tools covering three domains:
+1. **Meetings**: Listing meetings, detailed inspection of agendas/notes, and deep keyword search across meeting titles and agenda content.
+2. **Wikis**: Retrieving wiki pages, smart caching discovery/search across wiki page titles, and listing wiki page links to work packages.
+3. **Work Package Activities & Comments**: Browsing history and timeline events with dedicated comments-only filtering.
+
+All 7 tools are strictly read-only (`readOnly: true`), preserving full functionality in read-only environments while expanding the MCP server catalog from 11 to 18 registered tools.
+
+---
+
+## 2. Architectural Design
+
+```
+   MCP Client (Claude / Antigravity / Cursor)
+                     │
+                     ▼
+          McpServer (src/server.ts)
+                     │
+                     ▼ wrapExecute (RequestContext)
+  ┌──────────────────┼──────────────────────────────┐
+  │                  │                              │
+  ▼                  ▼                              ▼
+Meetings Tools      Wikis Tools           Work Package Tools
+(src/tools/        (src/tools/            (src/tools/
+ meetings.ts)       wikis.ts)              work-packages.ts)
+  │                  │                              │
+  ▼                  ▼                              ▼
+Meetings Service    Wikis Service          Work Packages Service
+(src/services/     (src/services/         (src/services/
+ meetings.ts)       wikis.ts)              work-packages.ts)
+  │                  │                              │
+  │                  ├─► In-Memory Discovery Cache  │
+  │                  │                              │
+  └──────────────────┼──────────────────────────────┘
+                     │
+                     ▼ OpenProjectClient
+           OpenProject 17 API v3
+```
+
+### 2.1 Meetings Domain (`src/services/meetings.ts` & `src/tools/meetings.ts`)
+- **`listMeetings(params, client)`**:
+  - Accepts `projectId` (numeric ID or string identifier), `time` filter (e.g. `"upcoming"`, `"past"`), `offset`, and `pageSize`.
+  - Resolves string project identifiers to numeric IDs via `resolveProjectId`.
+  - Serializes OpenProject filter syntax: `[{"project_id":{"operator":"=","values":[...]}}]` and optional `time` filter.
+  - Calls `GET /api/v3/meetings`.
+  - Returns paginated `MeetingSummary` array:
+    ```typescript
+    export interface MeetingSummary {
+      id: number;
+      title: string;
+      state: string;
+      startTime: string;
+      endTime: string;
+      duration?: string;
+      project: { id: number; name: string };
+      location?: string;
+      author?: { id: number; name: string };
+    }
+    ```
+- **`getMeeting(id, options, client)`**:
+  - Calls `GET /api/v3/meetings/{id}`.
+  - If `options.includeAgendaItems` is true (default: true), concurrently calls `GET /api/v3/meetings/{id}/agenda_items` and unpacks each item.
+  - Returns `MeetingDetail`:
+    ```typescript
+    export interface AgendaItemOutcome {
+      id: number;
+      notes: string;
+    }
+
+    export interface AgendaItem {
+      id: number;
+      title: string;
+      durationInMinutes?: number;
+      notes?: string;
+      itemType: string;
+      position: number;
+      author?: { id: number; name: string };
+      presenter?: { id: number; name: string };
+      section?: { id: number; title: string };
+      outcomes: AgendaItemOutcome[];
+    }
+
+    export interface MeetingDetail extends MeetingSummary {
+      template: boolean;
+      notify: boolean;
+      participants: Array<{ id: number; name: string }>;
+      agendaItems?: AgendaItem[];
+      sections?: Array<{ id: number; title: string; position: number }>;
+    }
+    ```
+- **`searchMeetings(params, client)`**:
+  - Accepts `query` (required), optional `projectId`, `offset`, and `pageSize`.
+  - Fetches candidate meetings (scoped to `projectId` if provided).
+  - Performs case-insensitive matching against meeting `title` and `location`.
+  - Concurrently fetches agenda items for candidate meetings and inspects agenda item `title` and `notes`.
+  - Returns `MeetingSearchResult` list:
+    ```typescript
+    export interface MeetingSearchResult {
+      meeting: MeetingSummary;
+      matchType: "title" | "location" | "agenda_item";
+      matchedAgendaItems?: Array<{
+        id: number;
+        title: string;
+        snippet?: string;
+      }>;
+    }
+    ```
+
+### 2.2 Wikis Domain (`src/services/wikis.ts` & `src/tools/wikis.ts`)
+- **`getWikiPage(id, client)`**:
+  - Calls `GET /api/v3/wiki_pages/{id}`.
+  - Calls `GET /api/v3/wiki_pages/{id}/attachments` to embed attachments.
+  - Returns `WikiPageDetail`:
+    ```typescript
+    export interface WikiPageAttachment {
+      id: number;
+      fileName: string;
+      fileSize: number;
+      contentType: string;
+      downloadUrl: string;
+    }
+
+    export interface WikiPageDetail {
+      id: number;
+      title: string;
+      project: { id: number; identifier?: string; name?: string };
+      attachments: WikiPageAttachment[];
+    }
+    ```
+- **`listWikiPageLinks(params, client)`**:
+  - If `workPackageId` is provided, queries `/api/v3/work_packages/{workPackageId}/wiki_page_links`.
+  - Otherwise, queries `/api/v3/wiki_page_links`.
+  - Returns `WikiPageLink` array:
+    ```typescript
+    export interface WikiPageLink {
+      id: number;
+      pageTitle?: string;
+      pageUrl?: string;
+      provider?: string;
+      workPackage?: { id: number; title?: string };
+    }
+    ```
+- **`searchWikiPages(params, client)`**:
+  - Resolves optional `projectId` (numeric or identifier).
+  - Maintains an in-memory cache of discovered wiki pages keyed by `client.baseUrl` (`Map<number, WikiPageDetail>`).
+  - Discovery strategy:
+    1. Checks `wiki_page_links` to collect referenced wiki pages.
+    2. Batch-probes `/api/v3/wiki_pages/{id}` across sequential IDs (e.g. IDs 1..50 with consecutive 404 threshold stop).
+    3. Populates cache with discovered pages.
+  - Filters cached pages by `projectId` (if specified) and matches `query` against `page.title` (case-insensitive substring).
+  - Returns matching `WikiPageSummary` array.
+
+### 2.3 Work Package Activities & Comments (`src/services/work-packages.ts`)
+- **`listWorkPackageActivities(params, client)`**:
+  - Calls `GET /api/v3/work_packages/{workPackageId}/activities`.
+  - Parses each activity:
+    ```typescript
+    export interface ActivityDetail {
+      format: string;
+      raw: string;
+      html?: string;
+    }
+
+    export interface WorkPackageActivity {
+      id: number;
+      version: number;
+      createdAt: string;
+      user?: { id: number; name: string };
+      comment?: string;
+      details: ActivityDetail[];
+      isComment: boolean;
+    }
+    ```
+  - If `onlyComments: true`, filters out activities where `isComment` is false.
+  - Returns `PaginatedResult<WorkPackageActivity>`.
+
+---
+
+## 3. Tool Definitions & Zod Schemas
+
+| Tool Name | Parameters | Returns | Description |
+|-----------|------------|---------|-------------|
+| `openproject_list_meetings` | `projectId` (optional string/number), `time` (optional string), `offset` (optional number), `pageSize` (optional number) | `PaginatedResult<MeetingSummary>` | List and filter meetings visible to the user. |
+| `openproject_get_meeting` | `id` (required number), `includeAgendaItems` (optional boolean, default: true) | `MeetingDetail` | Retrieve detailed meeting information including agenda items, sections, and notes. |
+| `openproject_search_meetings` | `query` (required string), `projectId` (optional string/number), `offset` (optional number), `pageSize` (optional number) | `PaginatedResult<MeetingSearchResult>` | Deep search across meeting titles, locations, and agenda item notes. |
+| `openproject_get_wiki_page` | `id` (required number) | `WikiPageDetail` | Retrieve wiki page metadata, project, and attachments. |
+| `openproject_search_wiki_pages` | `query` (optional string), `projectId` (optional string/number), `limit` (optional number, default: 20) | `WikiPageSummary[]` | Discover and search wiki pages matching keywords or project. |
+| `openproject_list_wiki_page_links` | `workPackageId` (optional number), `offset` (optional number), `pageSize` (optional number) | `PaginatedResult<WikiPageLink>` | List links connecting work packages to wiki pages. |
+| `openproject_list_work_package_activities` | `workPackageId` (required number), `onlyComments` (optional boolean, default: false) | `PaginatedResult<WorkPackageActivity>` | Retrieve timeline activities and comments for a work package. |
+
+All 7 tools: `readOnly: true`.
+
+---
+
+## 4. Error Handling & Edge Cases
+
+1. **Missing Resource (404)**:
+   - `openproject_get_meeting` and `openproject_get_wiki_page` throw `OpenProjectNotFoundError` with descriptive message when resource does not exist.
+2. **Permission Denied (403)**:
+   - Preserves normalized `OpenProjectForbiddenError` when current API key lacks permission to view meetings or wiki pages in target project.
+3. **Empty Agenda Items**:
+   - Meetings without agenda items return an empty array for `agendaItems: []` without failing.
+4. **Consecutive 404s in Wiki Scanner**:
+   - The wiki scanner halts probing when encountering consecutive 404 responses (e.g. 5 consecutive misses), avoiding excessive HTTP requests.
+5. **Project Identifier Resolution**:
+   - `projectId` can be passed as integer (e.g. `1`) or string identifier (e.g. `"demo-project"`), resolved transparently using `resolveProjectId`.
+
+---
+
+## 5. Testing & Verification
+
+1. **Unit & Service Tests (`tests/services.test.ts`, `tests/meetings.test.ts`, `tests/wikis.test.ts`)**:
+   - Verify pagination, filters, and schema parsing against mocked HAL responses.
+   - Verify wiki scanner caching, project filtering, and title matching.
+   - Verify activities comments-only filtering.
+2. **MCP Server Integration (`tests/tools.test.ts`, `tests/mcp-server.test.ts`, `tests/read-only.test.ts`)**:
+   - Verify registry has 18 tools total.
+   - Verify tool schemas and execution via MCP Client in `RequestContext`.
+   - Verify that all 18 tools remain registered under `OPENPROJECT_READ_ONLY=true`.
+3. **Remote HTTP/SSE & OpenAPI Introspection (`tests/http-server.test.ts`)**:
+   - Verify `GET /openapi.json` publishes all 18 tool specifications.
+   - Verify `POST /api/tools/:toolName` executes the new tools.
+4. **Live OpenProject 17 Container Tests**:
+   - Live meeting retrieval against project 1 (`demo-project`, meetings 2-5).
+   - Live wiki page inspection against page 1 (`Wiki`).
+   - Live work package activity inspection against work package 38.