Orchestrator/bahn/db-planet-mcp-server/.kiro/specs/dbplanet-mcp-tools/requirements.md

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