ankn
a5f8fb49ab
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.
166 lines
12 KiB
Markdown
166 lines
12 KiB
Markdown
# Requirements Document
|
|
|
|
## Introduction
|
|
|
|
This document specifies the requirements for refactoring the DB Planet MCP Server from a single monolithic tool (SearchDBPlanet) into a suite of focused, single-responsibility MCP tools. The current server exposes one tool that combines search and full content fetching. The refactored server will expose ~27 tools organized across 8 capability areas, enabling AI agents to select the right tool for each task with clear inputs and outputs.
|
|
|
|
## Glossary
|
|
|
|
- **MCP_Server**: The Model Context Protocol server that registers and exposes tools to AI agents via the StreamableHTTP transport
|
|
- **Tool**: A single MCP tool registered on the MCP_Server with a unique name, description, input schema, and handler function
|
|
- **HaiiloClient**: The API client class responsible for authenticating with the Haiilo platform via OAuth2 and making HTTP requests
|
|
- **Tool_Registry**: The module that registers all tools on the MCP_Server instance, organized by capability area
|
|
- **Capability_Area**: A logical grouping of related tools (e.g., Search, Workspaces, People)
|
|
- **Haiilo_API**: The REST API exposed by the Haiilo (DB Planet) platform
|
|
|
|
## Requirements
|
|
|
|
### Requirement 1: Shared API Client Infrastructure
|
|
|
|
**User Story:** As a developer, I want all tools to share a single authenticated HaiiloClient instance per session, so that OAuth2 tokens are reused and connection setup is not duplicated.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE MCP_Server SHALL create one HaiiloClient instance per session and share it across all registered tools
|
|
2. THE HaiiloClient SHALL cache the OAuth2 access token after the first successful authentication and reuse it for subsequent API calls within the same session
|
|
3. IF the HaiiloClient receives a 401 response from the Haiilo_API, THEN THE HaiiloClient SHALL re-authenticate and retry the request once
|
|
4. IF required credentials are missing, THEN THE Tool SHALL return an MCP error response with a descriptive message
|
|
|
|
### Requirement 2: Tool Registration Architecture
|
|
|
|
**User Story:** As a developer, I want tools organized into separate registration modules by capability area, so that the codebase is maintainable and each area can evolve independently.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE Tool_Registry SHALL organize tool registration functions into separate modules, one per Capability_Area
|
|
2. THE MCP_Server SHALL register all tools from all Capability_Area modules during server initialization
|
|
3. THE Tool_Registry SHALL assign each Tool a unique, descriptive name following the pattern `{Area}_{Action}` (e.g., `Search_FullText`, `Workspace_List`)
|
|
4. THE Tool_Registry SHALL provide each Tool with a description that explains the tool's purpose, expected inputs, and output format
|
|
5. THE Tool_Registry SHALL define each Tool's input schema using Zod validation with descriptive parameter annotations
|
|
|
|
### Requirement 3: Information Discovery and Search Tools
|
|
|
|
**User Story:** As an AI agent, I want separate search tools for full-text search, quick entity lookup, and grouped search, so that I can choose the right search strategy for each query.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN a full-text search query is provided, THE Search_FullText Tool SHALL call GET /api/search with the query term and return the list of search results with metadata (id, title, type, excerpt, modified date)
|
|
2. WHEN a full-text search query is provided, THE Search_FullText Tool SHALL accept optional pagination parameters (page number, page size)
|
|
3. WHEN a quick entity search query is provided, THE Search_QuickEntity Tool SHALL call GET /api/quick-entity-search with the query and return matching entities
|
|
4. WHEN a grouped search query is provided, THE Search_Grouped Tool SHALL call GET /api/search/grouped with the query and return results organized by content type
|
|
5. THE Search_FullText Tool SHALL return result metadata only, without fetching full content for each result
|
|
|
|
|
|
### Requirement 4: Workspace Management Tools
|
|
|
|
**User Story:** As an AI agent, I want tools to list, inspect, join, and create workspaces, so that I can help users manage their workspace memberships and discover workspace content.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN workspace listing is requested, THE Workspace_List Tool SHALL call GET /api/workspaces and return the list of available workspaces
|
|
2. WHEN a workspace ID is provided, THE Workspace_Get Tool SHALL call GET /api/workspaces/{id} and return the workspace details including name, description, and settings
|
|
3. WHEN a workspace ID is provided, THE Workspace_GetMembers Tool SHALL call GET /api/workspaces/{id}/members and return the list of workspace members
|
|
4. WHEN a workspace ID is provided, THE Workspace_Join Tool SHALL call PUT /api/workspaces/{id}/members/join to add the current user as a member of the workspace
|
|
5. WHEN workspace creation parameters are provided, THE Workspace_Create Tool SHALL call POST /api/workspaces with the provided name and description to create a new workspace
|
|
|
|
### Requirement 5: News and Content Tools
|
|
|
|
**User Story:** As an AI agent, I want a tool to retrieve the news feed, so that I can help users stay informed about recent company news and blog posts.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the news feed is requested, THE News_GetFeed Tool SHALL call GET /web/blog/newsfeed and return the list of recent news items
|
|
2. THE News_GetFeed Tool SHALL accept optional pagination parameters (page number, page size)
|
|
3. THE News_GetFeed Tool SHALL return each news item with its title, author, publication date, and excerpt
|
|
|
|
### Requirement 6: People Directory Tools
|
|
|
|
**User Story:** As an AI agent, I want tools to look up the current user's profile, list users, and search for people, so that I can help users find colleagues and retrieve profile information.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the current user's profile is requested, THE People_GetMe Tool SHALL call GET /api/users/me and return the authenticated user's profile information
|
|
2. WHEN a user listing is requested, THE People_List Tool SHALL call GET /api/users and return a paginated list of users
|
|
3. WHEN a people search query is provided, THE People_Search Tool SHALL call GET /api/users/chooser/search with the query and return matching user profiles
|
|
4. THE People_List Tool SHALL accept optional pagination parameters (page number, page size)
|
|
|
|
### Requirement 7: Event Discovery Tools
|
|
|
|
**User Story:** As an AI agent, I want tools to view event details, check memberships, update attendance status, and create events, so that I can help users manage their event participation.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN an event ID is provided, THE Event_Get Tool SHALL call GET /api/events/{id} and return the event details including title, description, date, and location
|
|
2. WHEN an event ID is provided, THE Event_GetMemberships Tool SHALL call GET /api/events/{id}/memberships and return the list of event attendees and their statuses
|
|
3. WHEN an event ID and attendance status are provided, THE Event_UpdateStatus Tool SHALL call PUT /api/events/{id}/memberships/status to update the current user's attendance status
|
|
4. WHEN event creation parameters are provided, THE Event_Create Tool SHALL call POST /api/events with the provided details to create a new event
|
|
|
|
### Requirement 8: Social Engagement Tools
|
|
|
|
**User Story:** As an AI agent, I want tools to read and post comments and manage likes, so that I can help users engage with content on the platform.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN a target entity ID is provided, THE Social_GetComments Tool SHALL call GET /api/comments with the target ID and return the list of comments
|
|
2. WHEN a comment body and target entity ID are provided, THE Social_PostComment Tool SHALL call POST /api/comments to create a new comment on the target entity
|
|
3. WHEN a like target ID is provided, THE Social_GetLikes Tool SHALL call GET /api/like-targets/{targetType}/{targetId} and return the like count and whether the current user has liked the target
|
|
4. WHEN a like target ID is provided, THE Social_ToggleLike Tool SHALL call POST /api/like-targets/{targetType}/{targetId}/likes/{userId} to toggle the current user's like on the target
|
|
|
|
|
|
### Requirement 9: Notification Tools
|
|
|
|
**User Story:** As an AI agent, I want tools to retrieve notifications, check notification status, and mark notifications as seen, so that I can help users stay on top of platform activity.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN notifications are requested, THE Notification_List Tool SHALL call GET /api/notifications and return the list of notifications with their read/unread status
|
|
2. THE Notification_List Tool SHALL accept optional pagination parameters (page number, page size)
|
|
3. WHEN notification status is requested, THE Notification_GetStatus Tool SHALL call GET /api/notifications/status and return the count of unseen notifications
|
|
4. WHEN a mark-seen request is made, THE Notification_MarkSeen Tool SHALL call PUT /api/notifications/mark-seen to mark all notifications as seen
|
|
|
|
### Requirement 10: Page Management Tools
|
|
|
|
**User Story:** As an AI agent, I want tools to list, view, inspect members of, and create pages, so that I can help users manage intranet page content.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN page listing is requested, THE Page_List Tool SHALL call GET /api/pages and return the list of available pages
|
|
2. WHEN a page ID or slug is provided, THE Page_Get Tool SHALL call GET /api/pages/{id} and return the page details including title, content widgets, and metadata
|
|
3. WHEN a page ID is provided, THE Page_GetMembers Tool SHALL call GET /api/pages/{id}/members and return the list of page members and their roles
|
|
4. WHEN page creation parameters are provided, THE Page_Create Tool SHALL call POST /api/pages with the provided title and content to create a new page
|
|
|
|
### Requirement 11: Content Fetching Tool
|
|
|
|
**User Story:** As an AI agent, I want a dedicated tool to fetch the full rendered content of a specific item by its ID and type, so that I can retrieve detailed content on demand after discovering items via search.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN a content ID and content type are provided, THE Content_GetFull Tool SHALL fetch the full rendered content for the specified item using the appropriate Haiilo widget API endpoint
|
|
2. THE Content_GetFull Tool SHALL support blog articles, wiki articles, pages, workspaces, apps, and timeline items as content types
|
|
3. THE Content_GetFull Tool SHALL extract text from widget HTML and return clean, readable text
|
|
4. IF the content type is not recognized, THEN THE Content_GetFull Tool SHALL return an error indicating the unsupported content type
|
|
5. IF the content cannot be fetched, THEN THE Content_GetFull Tool SHALL return an error with a descriptive message
|
|
|
|
### Requirement 12: Error Handling Consistency
|
|
|
|
**User Story:** As a developer, I want all tools to handle errors in a consistent manner, so that AI agents receive predictable error responses regardless of which tool is called.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. IF a tool receives a 401 Unauthorized response from the Haiilo_API, THEN THE Tool SHALL return an MCP error response indicating authentication failure
|
|
2. IF a tool receives a 403 Forbidden response from the Haiilo_API, THEN THE Tool SHALL return an MCP error response indicating insufficient permissions
|
|
3. IF a tool receives a 404 Not Found response from the Haiilo_API, THEN THE Tool SHALL return an MCP error response indicating the requested resource was not found
|
|
4. IF a tool encounters a network timeout, THEN THE Tool SHALL return an MCP error response indicating a timeout occurred
|
|
5. THE Tool SHALL include the HTTP status code and a human-readable message in all error responses
|
|
|
|
### Requirement 13: Backward Compatibility
|
|
|
|
**User Story:** As a developer, I want the refactored server to maintain the same transport and authentication mechanism, so that existing clients can connect without changes.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE MCP_Server SHALL continue to use the StreamableHTTP transport on the /servers/dbplanet/mcp endpoint
|
|
2. THE MCP_Server SHALL continue to accept credentials via the x-dbplanet-* HTTP headers
|
|
3. THE MCP_Server SHALL continue to listen on port 3000
|
|
4. THE MCP_Server SHALL continue to expose the /health endpoint returning a 200 status
|