Orchestrator/bahn/db-planet-mcp-server

DB Planet MCP Server

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

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

Search & Retrieval Flow

1. Search: Query DB Planet search API with user's search term
2. Content Type Detection: Identify content type for each result
3. 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}
4. Content Extraction: Parse widget data and extract text from RTE and teaser widgets
5. Cleaning: Remove HTML tags, decode entities, normalize whitespace
6. 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