Migrate all repos into monorepo context folders
Bahn: aisupport, Analyse-O2C-C2S, awesome-bahn-mcp-servers, beam-mcp,
Confluence_Bot, db-planet-mcp-server, O2C-Harness, project-audit,
Projekt-KIQ-HP, teamlandkarte-mcp
Dhive: Jury-Voting
Privat: CV, NoteGraph (NOTE: NoteGraph needs complete redo after consolidation)
Shared: AI-Orchestrator, OrgMyLife, power_skills_and_more
Shared/references: symphony (read-only)
Bahn repos remain available as independent remotes - this monorepo
pulls them in via subtree, the originals are untouched.
This commit is contained in:
@@ -0,0 +1,217 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user