docs: record ADR-018 and update documentation for meetings, wikis, and activities tools

docs/ARCHITECTURE.md

@@ -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.

docs/DECISIONS.md

@@ -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.
+
+
 

docs/TODO.md

@@ -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.