Migrate all repos into monorepo context folders

Bahn: aisupport, Analyse-O2C-C2S, awesome-bahn-mcp-servers, beam-mcp, Confluence_Bot, db-planet-mcp-server, O2C-Harness, project-audit, Projekt-KIQ-HP, teamlandkarte-mcp Dhive: Jury-Voting Privat: CV, NoteGraph (NOTE: NoteGraph needs complete redo after consolidation) Shared: AI-Orchestrator, OrgMyLife, power_skills_and_more Shared/references: symphony (read-only) Bahn repos remain available as independent remotes - this monorepo pulls them in via subtree, the originals are untouched.
2026-06-30 20:39:52 +02:00
parent 2f2b295531
commit a5f8fb49ab
1717 changed files with 447332 additions and 0 deletions
@@ -0,0 +1,187 @@
+# Implementation Plan: DB Planet MCP Tools Refactoring
+
+## Overview
+
+Refactor the DB Planet MCP Server from a single monolithic `SearchDBPlanet` tool into ~28 focused, single-responsibility MCP tools organized across 9 registration modules. The implementation proceeds bottom-up: shared infrastructure first (error handler, enhanced client), then tool registration modules by capability area, then wiring everything together in the barrel and server entry point.
+
+## Tasks
+
+- [x] 1. Set up test infrastructure and shared utilities
+  - [x] 1.1 Add vitest and fast-check dev dependencies
+    - Run `npm install --save-dev vitest fast-check`
+    - Add `"test": "vitest --run"` script to package.json
+    - Add vitest config if needed (ESM + TypeScript)
+    - _Requirements: N/A (infrastructure)_
+
+  - [x] 1.2 Create the shared error handler at `src/errorHandler.ts`
+    - Implement `handleApiError(error: unknown): CallToolResult`
+    - Map 401 → authentication failed, 403 → insufficient permissions, 404 → not found, timeout → timed out, other → status + message
+    - All responses: `{ isError: true, content: [{ type: 'text', text: '[{status}] {message}' }] }`
+    - _Requirements: 12.1, 12.2, 12.3, 12.4, 12.5_
+
+  - [ ]* 1.3 Write property test for error handler (Property 3)
+    - **Property 3: Error handler maps HTTP status to correct MCP error**
+    - Generate arbitrary HTTP status codes and verify the output shape and message mapping
+    - **Validates: Requirements 12.1, 12.2, 12.3, 12.4, 12.5**
+
+- [x] 2. Enhance HaiiloClient with generic request method and 401 retry
+  - [x] 2.1 Add generic `request<T>` method to `src/haiiloClient.ts`
+    - Accepts `{ method, path, params?, data? }` config
+    - Calls `getAccessToken()`, makes request with Bearer token, returns `response.data`
+    - _Requirements: 1.1, 1.2_
+
+  - [x] 2.2 Add Axios response interceptor for 401 retry
+    - On 401: clear `accessToken`, re-authenticate, retry once using `_retried` flag
+    - If retry also 401, propagate error
+    - _Requirements: 1.3_
+
+  - [ ]* 2.3 Write property test for token caching (Property 5)
+    - **Property 5: Token caching — single authentication per session**
+    - Mock OAuth endpoint, make N requests, verify exactly 1 token request
+    - **Validates: Requirements 1.1, 1.2**
+
+  - [ ]* 2.4 Write property test for 401 retry logic (Property 10)
+    - **Property 10: 401 retry — re-authenticate and retry once**
+    - Mock API returning 401 then success, verify retry behavior and token refresh
+    - **Validates: Requirements 1.3**
+
+  - [ ]* 2.5 Write property test for missing credentials (Property 6)
+    - **Property 6: Missing credentials produce error**
+    - Generate arbitrary subsets of missing credentials, verify MCP error response
+    - **Validates: Requirements 1.4**
+
+- [x] 3. Checkpoint — Ensure shared infrastructure tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 4. Implement search tool registration module
+  - [x] 4.1 Create `src/tools/searchTools.ts` with `registerSearchTools(server, client)`
+    - Register `Search_FullText`: GET /api/search with query, page, pageSize params; return metadata only (id, title, type, excerpt, modified date)
+    - Register `Search_QuickEntity`: GET /api/quick-entity-search with query param
+    - Register `Search_Grouped`: GET /api/search/grouped with query param
+    - All tools use Zod schemas with `.describe()` annotations and delegate errors to `handleApiError`
+    - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5_
+
+  - [ ]* 4.2 Write property test for pagination forwarding (Property 2)
+    - **Property 2: Pagination parameter forwarding**
+    - Generate optional page/pageSize values, verify they are forwarded as query params when present and omitted when absent
+    - **Validates: Requirements 3.2, 5.2, 6.4, 9.2**
+
+  - [ ]* 4.3 Write property test for Search_FullText metadata only (Property 7)
+    - **Property 7: Search_FullText returns metadata only**
+    - Mock search response, verify result contains metadata fields and no full content
+    - **Validates: Requirements 3.5**
+
+- [x] 5. Implement workspace tool registration module
+  - [x] 5.1 Create `src/tools/workspaceTools.ts` with `registerWorkspaceTools(server, client)`
+    - Register `Workspace_List`: GET /api/workspaces
+    - Register `Workspace_Get`: GET /api/workspaces/{id}
+    - Register `Workspace_GetMembers`: GET /api/workspaces/{id}/members
+    - Register `Workspace_Join`: PUT /api/workspaces/{id}/members/join
+    - Register `Workspace_Create`: POST /api/workspaces with name, description
+    - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5_
+
+- [x] 6. Implement news, people, and event tool registration modules
+  - [x] 6.1 Create `src/tools/newsTools.ts` with `registerNewsTools(server, client)`
+    - Register `News_GetFeed`: GET /web/blog/newsfeed with optional page, pageSize
+    - _Requirements: 5.1, 5.2, 5.3_
+
+  - [x] 6.2 Create `src/tools/peopleTools.ts` with `registerPeopleTools(server, client)`
+    - Register `People_GetMe`: GET /api/users/me
+    - Register `People_List`: GET /api/users with optional page, pageSize
+    - Register `People_Search`: GET /api/users/chooser/search with query
+    - _Requirements: 6.1, 6.2, 6.3, 6.4_
+
+  - [x] 6.3 Create `src/tools/eventTools.ts` with `registerEventTools(server, client)`
+    - Register `Event_Get`: GET /api/events/{id}
+    - Register `Event_GetMemberships`: GET /api/events/{id}/memberships
+    - Register `Event_UpdateStatus`: PUT /api/events/{id}/memberships/status with id, status
+    - Register `Event_Create`: POST /api/events with title, description, startDate, endDate, location
+    - _Requirements: 7.1, 7.2, 7.3, 7.4_
+
+- [x] 7. Implement social, notification, and page tool registration modules
+  - [x] 7.1 Create `src/tools/socialTools.ts` with `registerSocialTools(server, client)`
+    - Register `Social_GetComments`: GET /api/comments with targetId
+    - Register `Social_PostComment`: POST /api/comments with targetId, body
+    - Register `Social_GetLikes`: GET /api/like-targets/{targetType}/{targetId}
+    - Register `Social_ToggleLike`: POST /api/like-targets/{targetType}/{targetId}/likes/{userId}
+    - _Requirements: 8.1, 8.2, 8.3, 8.4_
+
+  - [x] 7.2 Create `src/tools/notificationTools.ts` with `registerNotificationTools(server, client)`
+    - Register `Notification_List`: GET /api/notifications with optional page, pageSize
+    - Register `Notification_GetStatus`: GET /api/notifications/status
+    - Register `Notification_MarkSeen`: PUT /api/notifications/mark-seen
+    - _Requirements: 9.1, 9.2, 9.3, 9.4_
+
+  - [x] 7.3 Create `src/tools/pageTools.ts` with `registerPageTools(server, client)`
+    - Register `Page_List`: GET /api/pages
+    - Register `Page_Get`: GET /api/pages/{id}
+    - Register `Page_GetMembers`: GET /api/pages/{id}/members
+    - Register `Page_Create`: POST /api/pages with title, content
+    - _Requirements: 10.1, 10.2, 10.3, 10.4_
+
+- [x] 8. Implement content fetching tool registration module
+  - [x] 8.1 Create `src/tools/contentTools.ts` with `registerContentTools(server, client)`
+    - Register `Content_GetFull`: uses existing `getContentByType`, `fetchWidgetContent`, `extractTextFromWidgets`, `cleanHtml` logic from HaiiloClient
+    - Accept contentId, contentType, optional appId, optional slug
+    - Support blog-article, wiki-article, page, workspace, app, timeline-item
+    - Return clean text extracted from widget HTML
+    - Return error for unsupported content types
+    - _Requirements: 11.1, 11.2, 11.3, 11.4, 11.5_
+
+  - [ ]* 8.2 Write property test for HTML widget text extraction (Property 8)
+    - **Property 8: HTML widget text extraction removes all tags**
+    - Generate arbitrary HTML strings, verify output contains no `<...>` sequences and entities are decoded
+    - **Validates: Requirements 11.3**
+
+  - [ ]* 8.3 Write property test for unsupported content type (Property 9)
+    - **Property 9: Unsupported content type returns error**
+    - Generate arbitrary strings not in the supported set, verify MCP error response
+    - **Validates: Requirements 11.4**
+
+- [ ] 9. Checkpoint — Ensure all tool module tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 10. Wire everything together and update server entry point
+  - [x] 10.1 Create `src/tools/index.ts` barrel with `registerAllTools(server, client)`
+    - Import and call all 9 registration functions in order
+    - _Requirements: 2.1, 2.2_
+
+  - [x] 10.2 Update `src/getToolServer.ts` to use new architecture
+    - Create one `HaiiloClient` instance per session (not per tool call)
+    - Call `registerAllTools(server, client)` instead of `registerHaiiloTools`
+    - Remove old import of `registerHaiiloTools`
+    - _Requirements: 1.1, 2.2_
+
+  - [x] 10.3 Remove old `src/tools/haiiloTools.ts`
+    - Delete the monolithic tool registration file
+    - _Requirements: 2.1_
+
+  - [ ]* 10.4 Write property test for tool metadata completeness (Property 4)
+    - **Property 4: Tool metadata completeness**
+    - Instantiate McpServer, register all tools, verify each tool has `{Area}_{Action}` name pattern, non-empty description, and Zod schema
+    - **Validates: Requirements 2.3, 2.4, 2.5**
+
+  - [ ]* 10.5 Write property test for tool-to-endpoint routing (Property 1)
+    - **Property 1: Tool-to-endpoint routing correctness**
+    - For each registered tool with arbitrary valid input, mock `client.request`, invoke tool, verify correct HTTP method and path
+    - **Validates: Requirements 3.1, 3.3, 3.4, 4.1–4.5, 5.1, 6.1–6.3, 7.1–7.4, 8.1–8.4, 9.1, 9.3, 9.4, 10.1–10.4, 11.1**
+
+- [ ] 11. Verify backward compatibility
+  - [ ] 11.1 Verify `server.ts` is unchanged
+    - Confirm StreamableHTTP transport on `/servers/dbplanet/mcp`, credentials via `x-dbplanet-*` headers, port 3000, `/health` endpoint
+    - _Requirements: 13.1, 13.2, 13.3, 13.4_
+
+  - [ ]* 11.2 Write unit tests for backward compatibility
+    - Test that server listens on port 3000, /health returns 200, all 28 tools are registered
+    - _Requirements: 13.1, 13.2, 13.3, 13.4, 2.2_
+
+- [ ] 12. Final checkpoint — Ensure all tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+## Notes
+
+- Tasks marked with `*` are optional and can be skipped for faster MVP
+- Each task references specific requirements for traceability
+- Property tests validate universal correctness properties from the design document
+- The existing `server.ts` should remain unchanged — only `getToolServer.ts` and `src/tools/` are modified
+- The `HaiiloClient` content-fetching methods (`getContentByType`, `fetchWidgetContent`, `extractTextFromWidgets`, `cleanHtml`) need to be made accessible (public or package-internal) for use by `contentTools.ts`