# DB Planet MCP Server — Tool Overview

29 tools across 9 components. Each tool maps to one or more Haiilo API endpoints.

---

## 1. Search (3 tools)

| Tool | API Endpoint | What it does |
|------|-------------|--------------|
| Search_FullText | `GET /api/search?term=` | Keyword search across all content. Returns metadata (id, type, excerpt). |
| Search_QuickEntity | `GET /api/quick-entity-search?term=` | Fast entity lookup by name (users, workspaces, pages, events). |
| Search_Grouped | `GET /api/search/grouped?term=` | Same as FullText but results grouped by content type. |

**Example user queries:**
- "Find articles about sustainability on DB Planet"
- "Search for GenAI content"
- "Is there a workspace called Innovation Hub?"
- "Find the Town Hall event"

**Limitations:**
- Keyword matching only, not semantic search. Short queries (1-2 words) work best.
- LLMs sometimes wrap queries in quotes — we strip them automatically.

---

## 2. Workspace Management (5 tools)

| Tool | API Endpoint | What it does |
|------|-------------|--------------|
| Workspace_List | `GET /api/workspaces` | List workspaces. `memberOnly=true` filters for user's own workspaces (client-side pagination + filter). |
| Workspace_Get | `GET /api/workspaces/{id}` | Get workspace details by UUID or slug. |
| Workspace_GetMembers | `GET /api/workspaces/{id}/members` | Get member list for a workspace. |
| Workspace_Join | `PUT /api/workspaces/{id}/users/join` | Join a workspace. |
| Workspace_Create | `POST /api/workspaces` | Create a new workspace. Auto-sets current user as admin. |

**Example user queries:**
- "What workspaces am I a member of?" → `Workspace_List(memberOnly=true)`
- "Show me the Innovation Hub workspace" → `Search_QuickEntity` → `Workspace_Get`
- "Who are the members of the BahnGPT workspace?" → `Workspace_GetMembers`
- "Join the Digital Transformation workspace" → `Search_QuickEntity` → `Workspace_Join`
- "Create a workspace called Q1 Planning" → `Workspace_Create`

**Limitations:**
- API has no server-side membership filter — `memberOnly` paginates all workspaces client-side.
- API defaults to 20 results per page.

---

## 3. News (1 tool)

| Tool | API Endpoint | What it does |
|------|-------------|--------------|
| News_GetFeed | `GET /web/blog/newsfeed` | Get news articles from subscribed pages. Filters: published/scheduled/drafts, date range. |

**Example user queries:**
- "What are the latest news on DB Planet?"
- "Show me articles from January 2026"
- "Are there any draft articles?"

**Limitations:**
- ⚠️ Returns 404 on staging — endpoint doesn't exist in staging environment.
- Only returns articles from pages the authenticated user is subscribed to.

---

## 4. People (4 tools)

| Tool | API Endpoint | What it does |
|------|-------------|--------------|
| People_GetMe | `GET /api/users/me` | Get current user's profile. |
| People_Get | `GET /api/users/{id}` | Get a user's profile by UUID. |
| People_List | `GET /api/users` | List all users with pagination. |
| People_Search | `GET /api/users/chooser/search?term=&types=user` | Search users by name only. |
| People_GetManaged | `GET /api/users/{id}/managed` | Get all users that a given user manages (direct reports). |

**Example user queries:**
- "Show me my DB Planet profile" → `People_GetMe`
- "Find Alexandra on DB Planet" → `People_Search`
- "How many users are on DB Planet?" → `People_List`
- "Who does Alexandra manage?" → `People_Search` + `People_GetManaged`

**Limitations:**
- People_Search only matches by name — cannot search by department, job title, or expertise.
- `properties.department` exists on profiles but is not queryable and often null on staging.
- No "find people in department X" capability via the API.

---

## 5. Events (4 tools)

| Tool | API Endpoint | What it does |
|------|-------------|--------------|
| Event_Get | `GET /api/events/{id}` | Get event details by UUID. |
| Event_GetMemberships | `GET /api/events/{id}/memberships` | Get attendee list. Only works if `showParticipants` is enabled. |
| Event_UpdateStatus | `PUT /api/events/{id}/status` | Update attendance: ATTENDING, NOT_ATTENDING, TENTATIVE. |
| Event_Create | `POST /api/events` | Create a new event. Auto-sets current user as host/admin. |

**Example user queries:**
- "Show me details about the Town Hall event" → `Search_QuickEntity` → `Event_Get`
- "Who is attending the Innovation Workshop?" → `Event_GetMemberships`
- "Register me for the team building event" → `Event_UpdateStatus(status=ATTENDING)`
- "Decline the Friday meeting" → `Event_UpdateStatus(status=NOT_ATTENDING)`
- "Create a team event on May 15th at Frankfurt HQ" → `Event_Create`

**Limitations:**
- No "list all events" endpoint — must use Search_QuickEntity to find events by name.
- Event_GetMemberships returns 404 if the event has `showParticipants=false`.

---

## 6. Social (4 tools)

| Tool | API Endpoint | What it does |
|------|-------------|--------------|
| Social_GetComments | `GET /api/comments?targetId=&targetType=` | Get comments on an entity. |
| Social_PostComment | `POST /api/comments` | Post a comment. Auto-sets current user as author. |
| Social_GetLikes | `GET /api/like-targets/{type}/{id}/likes` | Get like count and list. |
| Social_ToggleLike | `POST /api/like-targets/{type}/{id}/likes/{userId}` | Like or unlike content. |

**Example user queries:**
- "Show me comments on the latest blog post" → `Search_FullText` → `Social_GetComments`
- "How many likes does the sustainability article have?" → `Social_GetLikes`
- "Like the welcome post" → `People_GetMe` + `Search_FullText` → `Social_ToggleLike`
- "Comment 'Great work!' on the team update" → `Search_FullText` → `Social_PostComment`

**Limitations:**
- Valid targetTypes: `blog-article`, `timeline-item`, `wiki-article` only. Events are NOT supported.
- Requires content UUID — must search first to find it.
- ToggleLike requires the user's UUID (from People_GetMe).

---

## 7. Notifications (3 tools)

| Tool | API Endpoint | What it does |
|------|-------------|--------------|
| Notification_List | `GET /api/notifications` | List notifications. Filter by category: ACTIVITY, DISCUSSION. |
| Notification_GetStatus | `GET /api/notifications/status` | Get unseen notification count. |
| Notification_MarkSeen | `PUT /api/notifications/action/mark-seen` | Mark notifications as seen. Optional category filter. |

**Example user queries:**
- "Do I have unread notifications?" → `Notification_GetStatus`
- "Show me my activity notifications" → `Notification_List(category=ACTIVITY)`
- "Show me discussion notifications" → `Notification_List(category=DISCUSSION)`
- "Mark all notifications as read" → `Notification_MarkSeen`

**Limitations:**
- Category parameter may be required (API returns error without it on some environments).

---

## 8. Pages (4 tools)

| Tool | API Endpoint | What it does |
|------|-------------|--------------|
| Page_List | `GET /api/pages` | List all pages. |
| Page_Get | `GET /api/pages/{id}` | Get page details by UUID or slug. |
| Page_GetMembers | `GET /api/pages/{id}/members` | Get page members/admins. |
| Page_Create | `POST /api/pages` | Create a new page. Auto-sets current user as admin. |

**Example user queries:**
- "What pages are available on DB Planet?" → `Page_List`
- "Show me the HR Department page" → `Search_QuickEntity` → `Page_Get`
- "Who manages the Innovation page?" → `Page_GetMembers`
- "Create a page for the sustainability initiative" → `Page_Create`

**Limitations:**
- ⚠️ Page_Create returns 404 on staging — endpoint doesn't exist in staging environment.

---

## 9. Content (1 tool)

| Tool | API Endpoint | What it does |
|------|-------------|--------------|
| Content_GetFull | Various widget endpoints | Fetch full rendered content by ID and type. Supports: blog-article, wiki-article, page, workspace, app, timeline-item. |

**Example user queries:**
- "Show me the full text of that article" → `Content_GetFull` (after search)
- "Read the wiki page about onboarding" → `Search_FullText` → `Content_GetFull`

**Limitations:**
- Requires `appId` for blog and wiki articles (available from Search_FullText results).
- Uses internal widget layout endpoints — may break if Haiilo changes layout naming.

---

## Summary

| Component | Tools | Status |
|-----------|-------|--------|
| Search | 3 | ✅ Working |
| Workspaces | 5 | ✅ Working |
| News | 1 | ⚠️ 404 on staging |
| People | 5 | ✅ Working (name search only) |
| Events | 4 | ✅ Working |
| Social | 4 | ✅ Working |
| Notifications | 3 | ✅ Working |
| Pages | 4 | ✅ Working (Create 404 on staging) |
| Content | 1 | ✅ Working |
| **Total** | **30** | |