docs: record ADR-018 and update documentation for meetings, wikis, and activities tools
This commit is contained in:
Lucas Winther
@@ -10,6 +10,9 @@ It allows agents to browse, query, and reason about OpenProject workspaces using
|
||||
|
||||
- **Project Discovery**: List accessible projects, inspect hierarchies, and retrieve project details.
|
||||
- **Work Package Browsing**: Query work packages with status, type, assignee, priority, and custom filters; inspect work package details and parent/child relationships.
|
||||
- **Activities & Comment History**: Inspect full timeline events and discussions for work packages with comments-only filtering.
|
||||
- **Meetings & Agendas**: List meetings, inspect detailed agendas with section timings and outcomes, and perform deep keyword searches across meetings and agenda notes.
|
||||
- **Wikis & Documentation**: Discover and search wiki pages with smart discovery caching, view page metadata, inspect file attachments, and trace work package links.
|
||||
- **Saved Queries (Views)**: Discover and execute saved project and global queries.
|
||||
- **Taxonomies & Metadata**: Query work package types (Tasks, Bugs, Features), statuses, priorities, and users to enable structured agent reasoning.
|
||||
- **OpenAPI Schema Introspection**: Query dynamic endpoint specifications, parameter schemas, and data models directly from the connected OpenProject instance with in-memory caching.
|
||||
@@ -341,15 +344,26 @@ This launches a local web UI (typically at `http://localhost:5173`) where you ca
|
||||
|
||||
## Available MCP Tools
|
||||
|
||||
`openproject-mcp` currently exposes 11 tools:
|
||||
`openproject-mcp` currently exposes 18 tools:
|
||||
|
||||
### Projects
|
||||
- `openproject_list_projects`: List projects with pagination (`offset`, `pageSize`), sorting (`sortBy`), and filtering.
|
||||
- `openproject_get_project`: Retrieve project details and metadata by ID or identifier (e.g. `projectId: "mcp-test-project"` or `projectId: 4`).
|
||||
|
||||
### Work Packages
|
||||
### Work Packages & Activities
|
||||
- `openproject_list_work_packages`: Query work packages with high-level filters (`projectId`, `status`, `typeId`, `assigneeId`, `priorityId`, `subject`, `pageSize`, `offset`) or custom JSON filter expressions.
|
||||
- `openproject_get_work_package`: Retrieve detailed information for a specific work package by ID (`workPackageId: 38`), including description, type, status, priority, author, dates, parent, and children.
|
||||
- `openproject_list_work_package_activities`: Retrieve timeline history, field change logs, and discussions for a work package (`workPackageId: 38`), with optional `onlyComments` filtering.
|
||||
|
||||
### Meetings
|
||||
- `openproject_list_meetings`: List and filter meetings visible to the user by project (`projectId`) or time context (`time: "upcoming"` / `"past"`), with pagination (`offset`, `pageSize`).
|
||||
- `openproject_get_meeting`: Retrieve detailed meeting information by ID (`id: 2`), including structured agenda items, sections, notes, outcomes, and participants.
|
||||
- `openproject_search_meetings`: Deep search across meeting titles, locations, and agenda item notes by keyword (`query: "planning"`).
|
||||
|
||||
### Wikis
|
||||
- `openproject_get_wiki_page`: Retrieve wiki page metadata, project, and attachments by numeric ID (`id: 1`).
|
||||
- `openproject_search_wiki_pages`: Discover and search wiki pages matching keywords or project with smart caching discovery (`query: "architecture"`, `projectId: "demo-project"`).
|
||||
- `openproject_list_wiki_page_links`: List links connecting work packages to wiki pages (`workPackageId: 38`, `offset`, `pageSize`).
|
||||
|
||||
### Saved Queries & Views
|
||||
- `openproject_list_queries`: List saved queries/views accessible to the authenticated user, optionally scoped to a project.
|
||||
@@ -378,6 +392,11 @@ Once connected in Claude Desktop, Cursor, or your agent of choice, you can ask q
|
||||
- *"Show me all open bugs in the 'mcp-test-project' project."*
|
||||
- *"What work packages are assigned to me, and what are their priorities?"*
|
||||
- *"Get details for work package #38 including its child tasks."*
|
||||
- *"Show all comments and discussion history on work package #38."*
|
||||
- *"List upcoming meetings and show the agenda items for our weekly planning meeting."*
|
||||
- *"Search our meeting notes to see if anyone discussed the new architecture."*
|
||||
- *"Find wiki pages discussing 'architecture' or 'setup' and list their attachments."*
|
||||
- *"What wiki pages are linked to work package #38?"*
|
||||
- *"Show the saved queries available for project 4 and run 'MCP Active Tasks'."*
|
||||
- *"What work package types and statuses are available in our OpenProject instance?"*
|
||||
- *"Inspect the OpenAPI schema for creating work packages using openproject_get_openapi_spec."*
|
||||
@@ -490,8 +509,9 @@ PORT=3000 bun run src/index.ts
|
||||
|
||||
- **Phase 1 (Completed)**: Read-only browsing tools for projects, work packages, queries, taxonomies, and OpenAPI introspection.
|
||||
- **Phase 4 (Completed)**: Remote HTTP/SSE transport (`Bun.serve`) with multi-tenant per-session credential scoping and Docker Compose deployment.
|
||||
- **Phase 3 Extension (Completed)**: Read-only collaboration tools across Meetings, Wikis, and Work Package Activities (18 tools total).
|
||||
- **Phase 2 (Upcoming)**: Mutating operations (create/update work packages, add comments, log time).
|
||||
- **Phase 3**: Attachment reading and document resources.
|
||||
- **Phase 3 (Future)**: Binary attachment downloading and resource streaming.
|
||||
|
||||
---
|
||||
|
||||
|
||||
+31
-9
@@ -24,9 +24,12 @@ flowchart LR
|
||||
|
||||
subgraph DomainServices ["Domain Services (Stateless)"]
|
||||
ProjSvc["Projects Service"]
|
||||
WpSvc["Work Packages Service"]
|
||||
WpSvc["Work Packages Service\n(& Activities)"]
|
||||
QuerySvc["Queries Service"]
|
||||
MetaSvc["Metadata & Taxonomies"]
|
||||
OpenApiSvc["OpenAPI Introspection"]
|
||||
MeetSvc["Meetings Service"]
|
||||
WikiSvc["Wikis Service"]
|
||||
end
|
||||
|
||||
subgraph Remote ["OpenProject Instance"]
|
||||
@@ -61,9 +64,12 @@ The system is organized into four modular layers:
|
||||
### 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.
|
||||
- **Work Packages Service**: Listing work packages with filters, searching by text or ID, retrieving work package details, inspecting relations, and browsing work package timeline activities and comments.
|
||||
- **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.
|
||||
- **OpenAPI Introspection Service**: Dynamic API v3 schema introspection, endpoint parameter schemas, tag discovery, and model definitions with in-memory caching.
|
||||
- **Meetings Service**: Listing and filtering meetings (upcoming/past), retrieving meeting details with structured agenda items, sections, and outcomes, and deep keyword search across meeting titles, locations, and agenda item notes.
|
||||
- **Wikis Service**: Retrieving wiki pages with embedded attachments, smart discovery search across wiki pages using cached harvesting and consecutive 404 cutoff, and listing wiki page links to work packages.
|
||||
|
||||
### 2.3. OpenProject Client Layer
|
||||
- **HTTP Transport**: Handles HTTPS communication against the configured `OPENPROJECT_BASE_URL`.
|
||||
@@ -135,7 +141,7 @@ The server is architected from the ground up to support concurrent, multi-user o
|
||||
|
||||
---
|
||||
|
||||
## 4. Tool Specifications (Browse & Query Scope)
|
||||
## 4. Tool Specifications (Browse & Query Scope - 18 Tools)
|
||||
|
||||
| MCP Tool Name | Description | Key Parameters |
|
||||
| :--- | :--- | :--- |
|
||||
@@ -143,13 +149,20 @@ The server is architected from the ground up to support concurrent, multi-user o
|
||||
| `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_work_package_activities` | Retrieve timeline activities and comments for a work package | `workPackageId` (number), `onlyComments` (boolean) |
|
||||
| `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` |
|
||||
| `openproject_get_openapi_spec` | Retrieve OpenProject API v3 OpenAPI specification for schema introspection | `summary`, `path`, `tag`, `schema` |
|
||||
| `openproject_list_meetings` | List and filter meetings visible to the user | `projectId`, `time`, `offset`, `pageSize` |
|
||||
| `openproject_get_meeting` | Retrieve detailed meeting information including agenda items, sections, notes, and participants | `id` (number), `includeAgendaItems` (boolean) |
|
||||
| `openproject_search_meetings` | Search across meetings and agenda items by keywords | `query` (string), `projectId`, `offset`, `pageSize` |
|
||||
| `openproject_get_wiki_page` | Retrieve wiki page metadata, project, and attachments by numeric ID | `id` (number) |
|
||||
| `openproject_search_wiki_pages` | Discover and search wiki pages matching keywords or project | `query`, `projectId`, `limit`, `refreshCache` |
|
||||
| `openproject_list_wiki_page_links` | List links connecting work packages to wiki pages | `workPackageId`, `offset`, `pageSize` |
|
||||
|
||||
---
|
||||
|
||||
@@ -218,11 +231,14 @@ openproject-mcp/
|
||||
│ ├── config/
|
||||
│ │ └── index.ts # Configuration loader and Zod schema
|
||||
│ ├── services/
|
||||
│ │ ├── helper.ts # Client and project resolution helpers
|
||||
│ │ ├── projects.ts # Projects domain service
|
||||
│ │ ├── work-packages.ts # Work packages domain service
|
||||
│ │ ├── work-packages.ts # Work packages & activities domain service
|
||||
│ │ ├── queries.ts # Queries domain service
|
||||
│ │ ├── metadata.ts # Types, statuses, priorities, users
|
||||
│ │ └── openapi.ts # OpenAPI specification discovery & caching
|
||||
│ │ ├── openapi.ts # OpenAPI specification discovery & caching
|
||||
│ │ ├── meetings.ts # Meetings domain service & search
|
||||
│ │ └── wikis.ts # Wikis domain service & discovery cache
|
||||
│ └── tools/
|
||||
│ ├── common.ts # Common schemas and error formatters
|
||||
│ ├── index.ts # Tool registration and execution wrapper
|
||||
@@ -230,7 +246,9 @@ openproject-mcp/
|
||||
│ ├── openapi.ts # MCP tool definition for OpenAPI introspection
|
||||
│ ├── projects.ts # MCP tool definitions for projects
|
||||
│ ├── queries.ts # MCP tool definitions for saved queries
|
||||
│ └── work-packages.ts # MCP tool definitions for work packages
|
||||
│ ├── work-packages.ts # MCP tool definitions for work packages & activities
|
||||
│ ├── meetings.ts # MCP tool definitions for meetings
|
||||
│ └── wikis.ts # MCP tool definitions for wikis
|
||||
├── tests/
|
||||
│ ├── fixtures/ # HAL+JSON mock fixtures
|
||||
│ ├── client.test.ts # OpenProject client unit tests
|
||||
@@ -238,11 +256,14 @@ openproject-mcp/
|
||||
│ ├── docker.test.ts # Docker packaging and compose tests
|
||||
│ ├── http-server.test.ts # Hosted HTTP/SSE server and protocol tests
|
||||
│ ├── mcp-server.test.ts # MCP server stdio integration tests
|
||||
│ ├── meetings.test.ts # Meetings domain service tests
|
||||
│ ├── openapi.test.ts # OpenAPI service and tool tests
|
||||
│ ├── read-only.test.ts # Read-only execution mode guard tests
|
||||
│ ├── services.test.ts # Domain services integration tests
|
||||
│ ├── smoke.test.ts # Metadata and smoke tests
|
||||
│ └── tools.test.ts # Tool registration unit tests
|
||||
│ ├── tools.test.ts # Tool registration unit tests
|
||||
│ ├── wikis.test.ts # Wikis domain service tests
|
||||
│ └── work-package-activities.test.ts # Activities service unit tests
|
||||
├── AGENTS.md # Operating guidelines for AI agents
|
||||
├── package.json # Project dependencies and scripts
|
||||
├── bun.lock # Bun dependency lockfile
|
||||
@@ -255,5 +276,6 @@ openproject-mcp/
|
||||
|
||||
- **Phase 1 (Completed)**: Read/browse capability for projects, work packages, queries, taxonomies, and OpenAPI introspection.
|
||||
- **Phase 4 (Completed)**: Hosted remote MCP server (HTTP/SSE transport via `Bun.serve`) with multi-tenant per-session credential scoping and Docker Compose deployment.
|
||||
- **Phase 3 Extension (Completed)**: Read-only collaboration tools across Meetings (listing, detail inspection, deep keyword search across agenda notes), Wikis (page retrieval, smart discovery search, and links), and Work Package Activities (history and comments filtering). Total catalog: 18 tools.
|
||||
- **Phase 2 (Upcoming)**: Mutating operations (create/update work packages, add comments, log time).
|
||||
- **Phase 3**: Attachment inspection and download resources.
|
||||
- **Phase 3 (Future)**: Attachment binary download resources.
|
||||
|
||||
@@ -430,4 +430,54 @@ While modern AI platforms (such as Open WebUI v0.6.31+) natively support MCP Str
|
||||
- **Negative**:
|
||||
- Introduces `src/openapi-spec.ts` dependency on `zod-to-json-schema`.
|
||||
|
||||
---
|
||||
|
||||
## ADR-018: Add Meetings, Wikis, and Activities Tools with Smart Wiki Discovery and Deep Meeting Search
|
||||
|
||||
### Status
|
||||
Accepted
|
||||
|
||||
### Context
|
||||
OpenProject provides critical team collaboration capabilities beyond core projects and work packages:
|
||||
1. **Meetings**: Structured agendas, participant lists, outcomes, and meeting minutes at `/api/v3/meetings`. LLMs frequently need to review sprint retrospectives, planning outcomes, and architectural decisions discussed in meetings.
|
||||
2. **Wikis**: Project documentation, architectural guides, and wiki pages stored at `/api/v3/wiki_pages`. However, OpenProject REST API v3 lacks a direct global `/api/v3/wiki_pages` collection endpoint. The API only exposes individual page retrieval (`/api/v3/wiki_pages/{id}`) and associations from work packages (`/api/v3/wiki_page_links` and `/api/v3/work_packages/{id}/wiki_page_links`).
|
||||
3. **Work Package Activities & Comments**: Full audit history and discussions attached to work packages at `/api/v3/work_packages/{id}/activities`. LLMs summarizing work package state need to isolate user comments from field mutation logs (e.g. status changes).
|
||||
|
||||
Furthermore, all new capabilities must strictly adhere to the project's read-only execution guarantees (ADR-011), request-scoped concurrency model (ADR-012), token efficiency requirements (ADR-007), and OpenAPI specification generation (ADR-017).
|
||||
|
||||
### Decision
|
||||
1. **Tool Scope and Read-Only Compliance**:
|
||||
- Introduce 7 new read-only MCP tools:
|
||||
- Meetings: `openproject_list_meetings`, `openproject_get_meeting`, `openproject_search_meetings`
|
||||
- Wikis: `openproject_get_wiki_page`, `openproject_search_wiki_pages`, `openproject_list_wiki_page_links`
|
||||
- Activities: `openproject_list_work_package_activities`
|
||||
- Mark each tool `readOnly: true`, allowing them to be registered and executable in read-only mode, expanding the total catalog from 11 to 18 tools.
|
||||
2. **Token-Efficient HAL Normalization**:
|
||||
- Implement tailored normalizers for all new endpoints:
|
||||
- Meeting models normalize project, author, and participant references.
|
||||
- Meeting details concurrently fetch `/api/v3/meetings/{id}/agenda_items` to embed clean agenda items, durations, sections, notes, and outcomes without deep `_links` bloat.
|
||||
- Wiki pages embed attachments with download URLs, sizes, and MIME types.
|
||||
- Work package activities parse raw comment text, extract user references, and normalize property change details.
|
||||
3. **Smart Wiki Discovery Strategy (Sequential Probing with Consecutive 404 Cutoff & Caching)**:
|
||||
- To overcome the lack of an OpenProject collection endpoint for wiki pages:
|
||||
a. Query `/api/v3/wiki_page_links` to harvest referenced wiki pages.
|
||||
b. Probe sequential IDs starting from ID 1 (`/api/v3/wiki_pages/{id}`) with a consecutive 404 threshold stop (halt after 5 consecutive misses).
|
||||
c. Cache discovered pages in an in-memory map keyed by client `baseUrl`.
|
||||
d. Filter discovered pages by project (resolving numeric ID or slug) and search queries against page titles.
|
||||
e. Support a `refreshCache: true` parameter for forcing cache invalidation.
|
||||
4. **Deep Meeting Search**:
|
||||
- Provide `openproject_search_meetings` that searches meeting titles and locations, while concurrently inspecting agenda item titles, discussion notes, and outcome minutes to return snippet matches and identify match origin (`title`, `location`, or `agenda_item`).
|
||||
|
||||
### Consequences
|
||||
- **Positive**:
|
||||
- Full visibility for LLMs into team discussions, meetings, agendas, wiki documentation, and work package comment history.
|
||||
- Expands MCP catalog to 18 tools across both stdio and HTTP/SSE/OpenAPI transports.
|
||||
- Zero performance regression: smart wiki discovery avoids repetitive scanning via memory caching, while consecutive 404 cutoff bounds HTTP traffic.
|
||||
- Token-efficient representations conserve LLM context window.
|
||||
- Maintains strict read-only safety guarantees across all new tools.
|
||||
- **Negative**:
|
||||
- OpenProject API lack of a native wiki collection endpoint requires heuristic discovery probing.
|
||||
- Deep meeting search requires additional sub-requests for agenda items on candidate meetings, bounded by pagination limits.
|
||||
|
||||
|
||||
|
||||
|
||||
+17
-3
@@ -114,6 +114,17 @@
|
||||
- [x] Record [ADR-017](DECISIONS.md#adr-017-openapi-310-specification--rest-tool-execution-bridge-for-openapi-clients) in `docs/DECISIONS.md`.
|
||||
- [x] Document OpenAPI connection mode and server endpoints reference table in [README.md](../README.md).
|
||||
|
||||
- [x] **Task 9: Meetings, Wikis, and Activities Extension (18 Tools Total)**
|
||||
- [x] Implemented `listWorkPackageActivities` in `src/services/work-packages.ts` separating comments from field mutations with `onlyComments` filter.
|
||||
- [x] Implemented `listMeetings`, `getMeeting` (with embedded agenda items/outcomes), and `searchMeetings` (deep search across titles, locations, and agenda item notes) in `src/services/meetings.ts`.
|
||||
- [x] Implemented `getWikiPage` (with attachments), `listWikiPageLinks`, and `searchWikiPages` with smart discovery caching and consecutive 404 cutoff in `src/services/wikis.ts`.
|
||||
- [x] Registered `openproject_list_work_package_activities` in `src/tools/work-packages.ts`.
|
||||
- [x] Registered `openproject_list_meetings`, `openproject_get_meeting`, `openproject_search_meetings` in `src/tools/meetings.ts`.
|
||||
- [x] Registered `openproject_get_wiki_page`, `openproject_search_wiki_pages`, `openproject_list_wiki_page_links` in `src/tools/wikis.ts`.
|
||||
- [x] Wired all 18 tools into server registry (`src/tools/index.ts`, `src/services/index.ts`) and updated all test suite assertions to 18 tools.
|
||||
- [x] Added live OpenProject 17 container integration tests in `tests/services.test.ts` and `tests/mcp-server.test.ts`.
|
||||
- [x] Recorded [ADR-018](DECISIONS.md#adr-018-add-meetings-wikis-and-activities-tools-with-smart-wiki-discovery-and-deep-meeting-search) and updated [ARCHITECTURE.md](ARCHITECTURE.md), [TODO.md](TODO.md), and [README.md](../README.md).
|
||||
|
||||
---
|
||||
|
||||
## 3. Backlog & Future Phases
|
||||
@@ -121,11 +132,14 @@
|
||||
- [x] **Phase 4: Remote Transport (Completed)**
|
||||
- [x] Add SSE (Server-Sent Events) transport option for remote deployments.
|
||||
- [x] Multi-tenant credential scoping with per-session isolation.
|
||||
- [x] **Phase 3 Extension: Meetings, Wikis, and Activities (Completed - 18 Tools Total)**
|
||||
- [x] Meetings listing, detail inspection, and deep agenda search.
|
||||
- [x] Wiki pages retrieval, smart cached discovery search, and work package links.
|
||||
- [x] Work package activities and comments filtering.
|
||||
- [ ] **Phase 2: Mutating Operations**
|
||||
- [ ] Create work package tool (`openproject_create_work_package`).
|
||||
- [ ] Update work package tool (`openproject_update_work_package`).
|
||||
- [ ] Add comments / activities to work packages.
|
||||
- [ ] Time logging tool (`openproject_log_time`).
|
||||
- [ ] **Phase 3: Attachments & Documents**
|
||||
- [ ] Inspect and download attachment resources.
|
||||
- [ ] Wiki pages and project documents browsing.
|
||||
- [ ] **Phase 3 (Future): Binary Attachments & File Resources**
|
||||
- [ ] Inspect and download binary attachment file contents via MCP resources.
|
||||
|
||||
Reference in New Issue
Block a user