Model Context Protocol (MCP) server for DB Planet (Haiilo) integration, enabling LLMs to search and retrieve full content from the Deutsche Bahn internal knowledge platform.

Overview

This MCP server provides seamless access to DB Planet content through a single search tool that:

Searches across all content types (blog articles, wiki articles, pages, workspaces, timeline items, files, events)
Automatically retrieves full content for each search result
Cleans and formats content for optimal LLM consumption
Handles OAuth2 authentication transparently

Features

Supported Content Types

Blog Articles: Full article content with rich text and headlines
Wiki Articles: Complete wiki pages with version support
Pages & Workspaces: Full page content with widget extraction
Timeline Items: Social posts and updates (snippet-based for performance)
Files: File metadata and descriptions
Events: Event details and information
Apps: Standalone app content pages

Content Extraction

Widget-based extraction: Parses RTE (rich text editor) and teaser widgets
HTML cleaning: Removes tags while preserving structure and readability
Entity decoding: Converts HTML entities to readable text
Headline extraction: Captures navigation headlines from teaser widgets

Installation

cd servers/server-dbplanet
npm install
npm run build

Running the Server

npm start

The server runs on port 3000 by default and exposes an MCP-over-HTTP endpoint.

Configuration

Required Credentials

The server requires DB Planet credentials passed via HTTP headers:

x-dbplanet-username: Your DB Planet username
x-dbplanet-password: Your DB Planet password
x-dbplanet-client-id: OAuth2 client ID
x-dbplanet-client-secret: OAuth2 client secret
x-dbplanet-base-url: DB Planet base URL (e.g., https://dbahn-staging.haiilo.cloud)

MCP Client Configuration

Add to your MCP client settings (e.g., Claude Desktop config):

{
  "mcpServers": {
    "dbplanet": {
      "url": "http://localhost:3000/servers/dbplanet/mcp",
      "transport": "http",
      "headers": {
        "x-dbplanet-username": "your-username",
        "x-dbplanet-password": "your-password",
        "x-dbplanet-client-id": "your-client-id",
        "x-dbplanet-client-secret": "your-client-secret",
        "x-dbplanet-base-url": "https://dbahn-staging.haiilo.cloud"
      }
    }
  }
}

API Endpoints

MCP Endpoint

Path: /servers/dbplanet/mcp
Methods: GET, POST, DELETE
Protocol: MCP Streamable HTTP (2025-03-26)

Health Check

Path: /health
Method: GET
Response: {"status": "ok"}

Tools

SearchDBPlanet

Search DB Planet and retrieve full content for all results. Returns complete articles/pages formatted for LLM analysis.

Parameters:

query (string, required): Search query term

Returns: Formatted text containing:

Total number of results
For each result:
- Title and source
- Content type
- Full extracted content (cleaned and formatted)

Example Usage:

{
  "query": "Wie erstelle ich einen S3 Bucket?"
}

Example Output:

Found 3 results for "Wie erstelle ich einen S3 Bucket?":

[1] AWS S3 Bucket erstellen
Source: Cloud Platform Team (blog-article)

Content:
Schritt für Schritt Anleitung zum Erstellen eines S3 Buckets...

================================================================================

[2] S3 Best Practices
Source: DevOps Wiki (wiki-article)

Content:
Best Practices für die Verwendung von Amazon S3...

How It Works

Authentication Flow

Server receives credentials via HTTP headers
Obtains OAuth2 access token using password grant flow
Caches token for subsequent requests
Uses Bearer token for all API calls

Search & Retrieval Flow

Search: Query DB Planet search API with user's search term
Content Type Detection: Identify content type for each result
Content Retrieval: Use type-specific endpoints to fetch full content:
- Blog articles: /api/blog-article/{id}/widgets/app-blog-{appId}-{id}
- Wiki articles: /api/wiki-article/{id}/widgets/app-wiki-{appId}-{id}-{version}
- Pages: /api/pages/{slug}/widgets/default
- Workspaces: /api/workspaces/{slug}/widgets/default
- Timeline items: /api/timeline-items (snippet only for performance)
- Apps: /api/app/{id}/widgets/app-content-{id}
Content Extraction: Parse widget data and extract text from RTE and teaser widgets
Cleaning: Remove HTML tags, decode entities, normalize whitespace
Formatting: Format as readable text optimized for LLM consumption

Performance Optimizations

Selective fetching: Timeline items use snippets to avoid timeout
Parallel processing: Content retrieval happens sequentially but efficiently
Error handling: Falls back to snippet if full content retrieval fails
Timeout: 60-second timeout for API requests

Development

Project Structure

servers/server-dbplanet/
├── src/
│   ├── server.ts          # Express server & MCP protocol handler
│   ├── haiiloClient.ts    # DB Planet API client & content retrieval
│   └── haiiloTools.ts     # MCP tool registration
├── package.json
└── tsconfig.json

Testing

A Python test script is available in the project root:

cd ../../
python test_auth_api.py

This script tests authentication and content retrieval for all content types.

Troubleshooting

Authentication Errors

Verify credentials are correct
Check that base URL matches your DB Planet instance
Ensure OAuth2 client has proper permissions

Timeout Errors

Reduce search result count by using more specific queries
Timeline items automatically use snippets to prevent timeouts
Check network connectivity to DB Planet instance

Missing Content

Some content types may require specific permissions
Widget-based content requires proper layout names
Wiki articles may need version number adjustment

License

Internal Deutsche Bahn project