Orchestrator/bahn/db-planet-mcp-server/README.md

# 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

```bash
cd servers/server-dbplanet
npm install
npm run build
```

## Running the Server

```bash
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):

```json
{
  "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:**
```typescript
{
  "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:

```bash
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