DTF MCP Server

Model Context Protocol (MCP) server for DTF Asset Management with GraphQL integration.

Quick Start

Option 1: Use Published NPM Package (Recommended)

1. No installation required - npx will automatically download and run the package

2. Configure Claude Desktop: Add this configuration to your Claude Desktop settings:

   On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "BuschGroupDigitalTwin": {
         "command": "npx",
         "args": ["@buschgroup/digital-twin-mcp"],
         "env": {
           "API_URL": "https://testing.buscheservices.io/graphql",
           "USERNAME": "your-keycloak-username",
           "PASSWORD": "your-keycloak-password"
         }
       }
     }
   }

3. Restart Claude Desktop to load the MCP server

4. Verify setup: You should see DTF asset management tools available in Claude

Option 2: Local Development Setup

1. Clone repository and setup environment:

   git clone https://gitlab.dreebit.com/coc/dtf/mcp-server.git
   cd mcp-server
   npm install
   npm run env:setup
   # Edit .env file with your authentication method (see below)

2. Configure Claude Desktop for local development:

   {
     "mcpServers": {
       "digital-twin-mcp": {
         "command": "npm",
         "args": ["run", "dev"],
         "cwd": "/path/to/your/digital-twin-mcp",
         "env": {
           "API_URL": "https://testing.buscheservices.io/graphql",
           "USERNAME": "your-keycloak-username",
           "PASSWORD": "your-keycloak-password"
         }
       }
     }
   }

3. Start development server:

   npm run dev

Authentication Configuration

The MCP server supports two authentication methods that can be configured either in Claude Desktop's environment variables or in a local .env file:

Method 1: Username/Password Authentication (Recommended)

Direct authentication with Keycloak using username and password:

In Claude Desktop config:

{
  "mcpServers": {
    "dtf-mcp-server": {
      "command": "npx",
      "args": ["@buschgroup/digital-twin-mcp"],
      "env": {
        "API_URL": "https://testing.buscheservices.io/graphql",
        "USERNAME": "your-keycloak-username",
        "PASSWORD": "your-keycloak-password",
        "KEYCLOAK_URL": "https://dev.sso.buschgroup.com",
        "KEYCLOAK_REALM": "dev",
        "KEYCLOAK_CLIENT_ID": "busch-otto-public"
      }
    }
  }
}

Or in local .env file:

# Required for username/password authentication
USERNAME=your-keycloak-username
PASSWORD=your-keycloak-password

# Optional - defaults provided
KEYCLOAK_URL=https://dev.sso.buschgroup.com
KEYCLOAK_REALM=dev
KEYCLOAK_CLIENT_ID=busch-otto-public

Method 2: Bearer Token Authentication (Fallback)

Manual bearer token management:

In Claude Desktop config:

{
  "mcpServers": {
    "dtf-mcp-server": {
      "command": "npx",
      "args": ["@buschgroup/digital-twin-mcp"],
      "env": {
        "API_URL": "https://testing.buscheservices.io/graphql",
        "GRAPHQL_BEARER_TOKEN": "your-bearer-token-here"
      }
    }
  }
}

Or in local .env file:

# Required for manual authentication
GRAPHQL_BEARER_TOKEN=your-bearer-token-here

Common Configuration Options

# GraphQL API endpoint (required)
API_URL=https://testing.buscheservices.io/graphql

# Server configuration (optional)
MCP_HTTP_MODE=false
PORT=3000
NODE_ENV=development
DEBUG=false

Available Tools

Asset Management Tools

• findAssetBySerialNumber: Find an asset by its exact serial number

  • Uses additional Systems of Record (e.g. SAP) when the asset is not yet registered
  • Returns structured JSON data for optimal Claude processing
  • Parameters: serialNumber (required), manufacturerId (optional)
  • Example: Find asset with serial number "ABC123"

• searchAssets: Search for assets using full-text search across various fields

  • Full-text search with relevance scoring across multiple fields
  • Supports advanced filtering by manufacturer, product category, client, etc.
  • Returns ranked results with relevance scores
  • Parameters: query (required), fields, manufacturerId, productCategoryId, serialNumber, productCode, assetUrn, clientId, marketSegmentId, productId, offset, limit
  • Example: Search for "Pfeiffer vacuum pumps" in DTF assets

• registerAsset: Register a new asset in the DTF system

  • Creates a new asset record with identification information
  • Supports optional location and origin information
  • Returns complete asset details after registration
  • Parameters: asset (with serialNumber, productCode), location (optional), origin (optional)
  • Example: Register new asset with serial "XYZ789" and product code "12345"

Usage in Claude Desktop

Once configured, you can use these tools naturally in conversation:

• "Find the asset with serial number D17471742"
• "Search for all Pfeiffer Vacuum assets"
• "Register a new asset with serial number ABC123 and product code 98765"
• "What assets are manufactured by Busch?"

The MCP server will automatically handle authentication and return structured JSON data that Claude can process and present in a user-friendly format.

Development

• npm run dev - Stdio mode (for Claude Desktop)
• npm run dev:http - HTTP/WebSocket mode
• npm run dev:debug - Debug mode with logging
• npm run test - Run unit tests
• npm run test:inspector - Test MCP tools manually
• npm run test:integration - Run all integration tests
• npm run test:integration:find - Test findAssetBySerialNumber
• npm run test:integration:search - Test searchAssets
• npm run test:integration:auth - Test authentication token management
• npm run test:integration:all - Test all tools together

Documentation

• CLAUDE.md - Detailed development instructions
• DEBUGGING.md - Complete debugging guide with VS Code setup