mcp-hybrid-server

Hienfeld/mcp-hybrid-server

3.2

If you are the rightful owner of mcp-hybrid-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The MCP Hybrid Server for Hienfeld Insurance is a production-ready Model Context Protocol server designed for hybrid on-premises and cloud deployment in insurance environments.

Tools
9
Resources
0
Prompts
0

MCP Hybrid Server for Hienfeld Insurance

Status Tests Coverage

A production-ready Model Context Protocol (MCP) server designed for hybrid on-premises and cloud deployment in insurance environments. Fully implemented and tested with comprehensive Navision-focused tools and enterprise security features.

🏗️ System Architecture

graph TD
    A[Claude Desktop] --> D[MCP Server STDIO]
    B[MCP HTTP Client] --> D[MCP Server HTTP]
    C[WebSocket Client] --> D[MCP Server WebSocket]
    D --> E[JWT Authentication]
    D --> F[Navision Tools]
    D --> G[OData Client]
    D --> H[Hienfeld Helpers]
    D --> X[Xtendis Tools]
    D --> Y[Xtendis Client]
    F --> I[Search Customers]
    F --> J[Get Policies]
    F --> K[Broker Management]
    F --> L[Policy Analytics]
    F --> M[Expiring Policies]
    F --> N[High Value Policies]
    F --> O[Insurance Companies]
    X --> Z1[Upload Documents]
    X --> Z2[Search Documents]
    X --> Z3[Download Files]
    X --> Z4[PDF Conversion]
    X --> Z5[Document Management]
    G --> P[Hienfeld NAV System]
    Y --> W[Xtendis Document System]
    P --> Q[ActivePolissen]
    P --> R[Makelaars]
    P --> S[Maatschappijen]
    W --> W1[Document Archives]
    W --> W2[File Storage]
    W --> W3[Metadata Tags]
    Q --> T[Policy Data]
    R --> U[Broker Data]
    S --> V[Company Data]
    W1 --> W4[Policy Documents]
    W2 --> W5[Claims Files]
    W3 --> W6[Customer Notes]

Interface Protocols

InterfaceProtocolPortPurpose
MCP WebSocketWebSocket8000Claude Desktop integration (recommended)
MCP HTTPHTTP8000HTTP client integration
MCP STDIOSTDION/ALegacy Claude Desktop integration
Health CheckHTTP8000Load balancer health monitoring
MetricsHTTP8000Prometheus metrics collection
Navision ODataOData V47068Hienfeld Dynamics NAV integration
Xtendis REST APIHTTPS443Xtendis document management system

🏗️ Architecture Overview

This MCP server provides a secure bridge between AI models and the Hienfeld insurance ecosystem, including both the Dynamics NAV system and Xtendis document management platform. It supports on-premises data access through OData and REST APIs while leveraging cloud-based AI services.

Key Features

  • WebSocket Transport: Modern WebSocket-based MCP transport for Claude Desktop and custom clients
  • Docker-First Deployment: Complete Docker setup with monitoring, databases, and scalability
  • Hybrid Architecture: Run sensitive operations on-premises while leveraging cloud AI capabilities
  • Comprehensive Integration: 24 specialized tools (9 Navision + 15 Xtendis) for complete insurance workflows
  • Navision Tools: Pre-built tools for Hienfeld CRM policy management, customer search, and analytics
  • Document Management: Full Xtendis integration for policy documents, claims files, and correspondence
  • Enterprise Security: JWT authentication, role-based access control, and audit logging
  • Production Ready: Comprehensive testing, monitoring, health checks, and error handling
  • FastMCP Integration: Built on the latest FastMCP framework for optimal performance
  • Multi-Transport Support: WebSocket (recommended), HTTP, and STDIO modes

Components

  • MCP Server: Core FastMCP server with comprehensive insurance tools and resources
  • Authentication Layer: JWT-based security with role and permission management
  • OData Integration: Direct connection to Hienfeld Dynamics NAV system
  • REST API Integration: Secure connection to Xtendis document management system
  • Navision Tools: 9 specialized tools for insurance data access and analytics
  • Xtendis Tools: 15 specialized tools for document management and workflow
  • Monitoring: Health checks, metrics collection, and structured logging

🚀 Quick Start

Prerequisites

  • Docker & Docker Compose (recommended)
  • Python 3.10+ (for local development)
  • Git
  • Access to Hienfeld Dynamics NAV system (for production use)

🐳 Docker Deployment (Recommended)

1. Quick Docker Start

git clone <repository-url>
cd mcp-hybrid-server

# Create environment file
cp .env.example .env
# Edit .env with your Hienfeld NAV credentials

# Start with Docker Compose
docker compose up -d

# Check server health
curl http://localhost:8000/health

2. Docker Configuration

The Docker setup includes:

  • MCP Server: Main WebSocket server on port 8000
  • PostgreSQL: Database for persistent data
  • Redis: Caching layer
  • Prometheus & Grafana: Monitoring (optional)
# Full stack with monitoring
docker compose --profile monitoring up -d

# Core services only
docker compose up -d mcp-server postgres redis

# Check logs
docker compose logs mcp-server

# View WebSocket endpoint
echo "WebSocket endpoint: ws://localhost:8000/mcp/ws"

3. Claude Desktop STDIO Setup (Recommended)

Working Configuration for Windows with WSL:

Location: %APPDATA%\Claude\claude_desktop_config.json (Windows) Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "hienfeld-insurance": {
      "command": "C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe",
      "args": [
        "run", "--rm", "-i",
        "--env", "MCP_STDIO_MODE=1",
        "--env", "ODATA_BASE_URL=http://HFDB2.hienfeld.local:7068/HF-NAV2018-B/ODataV4/Company('W.A.%20Hienfeld%20Assuradeuren%20BV')",
        "--env", "ODATA_USERNAME=gebruikers_naam",
        "--env", "ODATA_PASSWORD=wacht_woord",
        "--env", "ODATA_DOMAIN=HIENFELD",
        "--env", "XTENDIS_BASE_URL=https://hfar2.hienfeld.local/rest/api/v1",
        "--env", "XTENDIS_USERNAME=xtendis_api_gebruiker",
        "--env", "XTENDIS_PASSWORD=wacht_woord",
        "--env", "XTENDIS_TENANT_NAME=xtendis_tenant",
        "--env", "DEBUG=false",
        "--env", "LOG_LEVEL=ERROR",
        "--network", "host",
        "mcp-hybrid-server",
        "python", "-m", "src.server.main", "--stdio"
      ],
      "name": "Hienfeld Insurance MCP Server (Docker)"
    }
  }
}

🔧 Local Development Setup

1. Python Setup

git clone <repository-url>
cd mcp-hybrid-server

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

2. Environment Configuration

# Hienfeld Dynamics NAV OData Configuration
export ODATA_BASE_URL="http://HFDB2.hienfeld.local:7068/HF-NAV2018-B/ODataV4/Company('W.A.%20Hienfeld%20Assuradeuren%20BV')"
export ODATA_USERNAME="nav_username"
export ODATA_PASSWORD="nav_password"
export ODATA_DOMAIN="hienfeld"

# Xtendis Document Management Configuration
export XTENDIS_BASE_URL="https://hfar2.hienfeld.local/rest"
export XTENDIS_USERNAME="xtendis_username"
export XTENDIS_PASSWORD="xtendis_password"
export XTENDIS_TENANT_NAME="Hienfeld"

# Optional: Custom server settings
export SERVER_NAME="Hienfeld MCP Server"
export LOG_LEVEL="INFO"

3. Run the Server

WebSocket Mode (Recommended for Claude Desktop):

# WebSocket server with auto-reload
python3 -m src.server.main --reload --host 127.0.0.1 --port 8000
# WebSocket endpoint: ws://localhost:8000/mcp/ws

Legacy STDIO Mode:

# STDIO mode for older Claude Desktop setups
python3 -m src.server.main --stdio

4. Test the Installation

# Test server health
curl http://localhost:8000/health

# Test WebSocket connectivity (requires wscat: npm install -g wscat)
wscat -c ws://localhost:8000/mcp/ws

# Run comprehensive test suite
python3 -m pytest tests/unit/ -v

🔧 Available Navision Tools

Customer & Policy Management

  1. search_customers

    • Search for customers in Hienfeld Navision CRM using OData filters
    • Parameters: search_term (customer name or number), limit (default: 50)
    • Returns: List of matching customer records with policy counts
    • Example: Search for "Klinkhamer" or customer number "V0283059"

  2. get_customer_policies

    • Get policies for a specific customer using OData filters
    • Parameters: customer_number (Klantnummer), record_type (optional), limit (default: 100)
    • Returns: List of customer policies with full details
    • Example filters: record_type="Actief" for active policies only

  3. get_policy_details

    • Get detailed information for a specific policy
    • Parameters: policy_number (PolisNummer)
    • Returns: Complete policy record or null if not found

Broker & Company Management

  1. get_policies_by_broker

    • Get policies for a specific broker using OData filters
    • Parameters: broker_code (Makelaar), record_type (default: "Actief"), limit (default: 100)
    • Returns: List of broker policies

  2. get_all_brokers

    • Get all insurance brokers (Makelaars) from Hienfeld Navision
    • Parameters: active_only (default: true), limit (default: 100)
    • Returns: List of broker records

  3. get_all_insurance_companies

    • Get all insurance companies (Maatschappijen) from Hienfeld Navision
    • Parameters: reporting_only (default: false), limit (default: 100)
    • Returns: List of insurance company records

Analytics & Filtering

  1. get_expiring_policies

    • Get policies expiring within specified days using OData date filters
    • Parameters: days_ahead (default: 30), limit (default: 100)
    • Returns: List of expiring policies

  2. get_high_value_policies

    • Get high-value policies using OData numeric filters
    • Parameters: minimum_premium (default: 1000.0), limit (default: 100)
    • Returns: List of high-value policies

  3. get_policy_analytics

    • Get policy analytics and insights with multiple filters
    • Parameters: broker_code (optional), account_manager (optional), record_type (default: "Actief")
    • Returns: Analytics data with insights, totals, and breakdowns

📄 Available Xtendis Document Tools

Document Upload & Retrieval

  1. upload_document_with_file

    • Upload documents with metadata to Xtendis archives
    • Parameters: archive_id, file_content_base64, filename, document_tags
    • Returns: JSON with success status, document ID, and upload details
    • Example: Upload policy documents, claims files, correspondence

  2. download_document_file

    • Download document files from Xtendis
    • Parameters: archive_id, document_id, file_number (optional)
    • Returns: JSON with base64-encoded file content and metadata
    • Example: Retrieve original policy documents for review

  3. download_and_save_document_file ⭐ NEW

    • Download document files and save directly to local disk
    • Parameters: archive_id, document_id, save_directory (default: ~/Downloads/xtendis), file_number (optional)
    • Returns: JSON with local file path, filename, and file size
    • Example: Save policy documents directly to ~/Downloads for easy access

  4. preview_document_file ⭐ NEW

    • Preview document content without downloading full file
    • Parameters: archive_id, document_id, file_number (optional), max_preview_size (default: 10000)
    • Returns: JSON with preview content for text files, base64 for images, or file info for binary files
    • Example: Quick preview of text documents, display images, check file types

  5. get_document_as_pdf

    • Convert and download documents as PDF format
    • Parameters: archive_id, document_id
    • Returns: JSON with base64-encoded PDF content
    • Example: Get standardized PDF versions of any document type

  6. download_multiple_documents ⭐ NEW

    • Download multiple documents in batch to local directory
    • Parameters: archive_id, document_ids (list), save_directory (default: ~/Downloads/xtendis)
    • Returns: JSON with download results for each document
    • Example: Bulk download all policy documents for a customer

  7. get_document

    • Retrieve document metadata and tags
    • Parameters: archive_id, document_id, include_notes (optional)
    • Returns: JSON with complete document metadata and tag structure
    • Example: Get document properties, tags, creation dates, owners

Search & Discovery

  1. search_documents

    • Advanced document search with flexible criteria
    • Parameters: archive_id, search_criteria, limit
    • Returns: JSON with matching documents and metadata
    • Example: Find all documents for customer "V0283059" or specific policy numbers

  2. list_archives

    • Get all available document archives
    • Parameters: None
    • Returns: JSON with archive list and capabilities
    • Example: Discover available archives (Policies, Claims, Correspondence)

  3. get_archive_info

    • Get detailed archive information and tag definitions
    • Parameters: archive_identifier (ID or name)
    • Returns: JSON with archive structure, available tags, and data types
    • Example: Understand what tags are available for document classification

  4. get_archive_metadata_guide ⭐ NEW

    • Get practical metadata guide with real examples from existing documents
    • Parameters: archive_id, include_sample_values (default: true)
    • Returns: JSON with comprehensive metadata guide including practical examples
    • Example: Discover what metadata values are actually used in the Verzekeringen archive (ID 2)

  5. get_tag_value_suggestions ⭐ NEW

    • Get suggestions for tag values based on existing documents
    • Parameters: archive_id, tag_name, limit (default: 20)
    • Returns: JSON with suggested values and usage statistics
    • Example: See what "Klantnummer" values are used in archive 2 for consistent tagging

Document Management

  1. update_document_metadata

    • Update document tags and metadata
    • Parameters: archive_id, document_id, tag_changes
    • Returns: JSON with updated document information
    • Example: Update customer numbers, policy references, or processing status

  2. add_document_note

  • Add notes or comments to documents
  • Parameters: archive_id, document_id, note_text
  • Returns: JSON with note details and all document notes
  • Example: Add processing notes, customer interactions, or follow-up reminders
  1. delete_document
    • Remove documents from Xtendis (use with caution)
    • Parameters: archive_id, document_id
    • Returns: JSON with deletion confirmation
    • Example: Remove duplicate or incorrectly uploaded documents

Authentication

The server supports multiple authentication modes:

  • OAuth2 Client Credentials: For service-to-service authentication
  • OAuth2 Password Flow: For user authentication
  • JWT Bearer Tokens: All HTTP endpoints protected with JWT
  • STDIO mode: Legacy Claude Desktop mode, no authentication required
OAuth2 Endpoints (for testing/development)

Claude Desktop calls these endpoints automatically - these examples are for testing:

# Test client credentials token generation (Claude Desktop does this automatically)
curl -X POST http://localhost:8000/auth/token/client \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "claude-desktop",
    "client_secret": "claude-desktop-secret-dev-only"
  }'

# Test user token via password flow (for other applications)
curl -X POST http://localhost:8000/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=admin&password=admin123"
Pre-configured Development Credentials

OAuth2 Clients:

  • claude-desktop / claude-desktop-secret-dev-only
  • test-client / test-client-secret-dev-only

Development Users:

  • admin / admin123 (Admin role)
  • agent1 / agent123 (Agent role)

📊 Resources

Available Resources

  1. policy://customer/{customer_id}
    • Comprehensive customer policy information from Hienfeld Navision
    • Returns formatted text with all active policy details from Hienfeld CRM
    • Includes policy numbers, premiums, brokers, and customer information

Usage Example

# Access customer policy resource using Hienfeld customer number
resource_uri = "policy://customer/V0283059"
policy_info = await mcp_client.get_resource(resource_uri)

🎯 Prompts

Customer Service Prompt

Use the customer_service_prompt for standardized customer interactions:

prompt = await mcp_client.get_prompt(
    "customer_service_prompt",
    customer_id="V0283059",
    query_type="policy"
)

📁 File Handling Usage Examples

The new Xtendis file handling tools make it easy to work with documents in Claude Desktop:

Practical File Operations

Download and Save Files Locally:

Use download_and_save_document_file to download document 12345 from archive 1 to ~/Downloads

Result: File saved directly to your local Downloads folder with proper filename

Preview Document Content:

Use preview_document_file to preview document 12345 from archive 1

Result: Shows text content for text files, displays images, or provides file info for binary files

Batch Download Multiple Documents:

Use download_multiple_documents to download documents [12345, 12346, 12347] from archive 1

Result: Downloads all documents to local directory with success/failure report

Smart File Type Handling

  • Text Files (.txt, .csv, .json, .xml, .html, .md, .log): Shows content preview
  • Images (.jpg, .png, .gif, .bmp, .webp): Provides base64 for display
  • PDFs: Suggests using get_document_as_pdf for conversion
  • Binary Files: Recommends download_and_save_document_file for local storage

Custom Save Locations

Use download_and_save_document_file with save_directory="/path/to/project/documents"
to save document 12345 from archive 1 to a specific project folder

🏷️ Metadata Discovery Examples

The new metadata tools help you discover and use the correct tag values for document organization:

Discover Available Metadata for Verzekeringen Archive

Get comprehensive metadata guide:

Use get_archive_metadata_guide with archive_id=2 to discover all available metadata fields
and see real examples from existing documents in the Verzekeringen archive

Result: Shows all available fields like "Klantnummer", "PolisNummer", "DocumentType" with actual values used

Find specific tag suggestions:

Use get_tag_value_suggestions with archive_id=2 and tag_name="Klantnummer"
to see what customer numbers are actually used in the system

Result: Returns actual values like ["V0283059", "V0284123", "V0285678"] for consistent tagging

Practical Metadata Usage

Before uploading a policy document:

  1. get_archive_metadata_guide(archive_id=2) - See what fields are available
  2. get_tag_value_suggestions(archive_id=2, tag_name="DocumentType") - See document types used
  3. Use the suggested values in your upload_document_with_file call

Example workflow for consistent tagging:

# Step 1: Discover metadata structure
Use get_archive_metadata_guide with archive_id=2

# Step 2: Get suggestions for specific fields
Use get_tag_value_suggestions with archive_id=2 and tag_name="DocumentType"

# Step 3: Upload with consistent metadata
Use upload_document_with_file with document_tags: {
  "Klantnummer": ["V0283059"],
  "DocumentType": ["Polis"],
  "PolisNummer": ["POL-2023-001"]
}

# Get JWT token
TOKEN=$(curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"agent","password":"password"}' | jq -r '.access_token')

# Use Navision tools via HTTP
curl -X POST http://localhost:8000/tools/search_customers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search_term": "Klinkhamer",
    "limit": 10
  }'

🧪 Testing

Test Status: ✅ All Tests Passing

Current Test Results:

  • Unit Tests: Comprehensive coverage of all modules
  • Integration Tests: Full MCP functionality validated
  • Navision Tools: All 9 tools tested with mocking
  • Xtendis Tools: All 15 document management tools tested
  • Authentication: JWT token handling working
  • Configuration: Environment settings tested
  • Error Handling: Robust error scenarios covered

Running Tests

# Run unit tests (recommended)
python3 -m pytest tests/unit/ -v

# Run with coverage report
python3 -m pytest tests/unit/ -v --cov=src --cov-report=html

# Run integration tests (requires mocking)
python3 -m pytest tests/integration/ -v

# Run all tests
python3 -m pytest tests/ -v

# Test MCP server functionality
python3 test_mcp.py

Test Coverage Summary

Module                                 Tests
--------------------------------------------------------------------
src/tools/navision_tools.py          ✅ 25+ comprehensive tests
src/tools/xtendis_tools.py            ✅ 8+ document management tests
src/auth/jwt_handler.py               ✅ 20+ authentication tests
src/server/config.py                  ✅ 15+ configuration tests
src/server/main.py                    ✅ 20+ server integration tests
src/utils/odata_client.py             ✅ 15+ OData client tests
src/utils/xtendis_client.py           ✅ 10+ Xtendis client tests
src/utils/hienfeld_helpers.py         ✅ 15+ helper function tests
src/resources/navision_resources.py   ✅ 10+ resource tests
--------------------------------------------------------------------
TOTAL                                 ✅ 140+ tests covering all modules

📝 Development

Local Development Setup

Recommended: Docker Development

# Use Docker for development (recommended)
docker compose up -d --build

# Watch logs during development
docker compose logs -f mcp-server

# Rebuild and restart after code changes
docker compose up -d --build mcp-server

Alternative: Python Development

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run development server with WebSocket support
python3 -m src.server.main --reload --host 127.0.0.1 --port 8000

# Legacy STDIO mode for testing
python3 -m src.server.main --stdio

Development Workflow

# Run tests during development
python3 -m pytest tests/unit/ -v

# Check code formatting
black --check src/ tests/
isort --check-only src/ tests/

# Type checking
mypy src/

# Lint code
flake8 src/ tests/

# Format code
black src/ tests/
isort src/ tests/

Key Development Notes

  • Fixed Depends Error: The original 'Depends' object has no attribute 'get' error has been resolved
  • STDIO Mode: Works seamlessly with Claude Desktop
  • HTTP Mode: Supports traditional HTTP clients with JWT authentication
  • Real Data Integration: All tools connect to actual Hienfeld Dynamics NAV system
  • Comprehensive Testing: Full test suite with mocking for all scenarios

📚 Hienfeld Dynamics NAV Integration

The server includes specialized tools for accessing Hienfeld's Microsoft Dynamics NAV system via OData feeds.

Configuration

Set these environment variables for OData access:

ODATA_BASE_URL="http://HFDB2.hienfeld.local:7068/HF-NAV2018-B/ODataV4/Company('W.A.%20Hienfeld%20Assuradeuren%20BV')"
ODATA_USERNAME="username"
ODATA_PASSWORD="password"
ODATA_DOMAIN="hienfeld"

Key OData Endpoints

  • ActivePolissen: Active insurance policies
  • Makelaars: Insurance brokers
  • Maatschappijen: Insurance companies

Data Structures

Policies (ActivePolissen):

  • Ordernummer, PolisNummer - Order and policy numbers
  • Klantnummer, Klant_naam - Customer ID and name
  • Makelaar, Makelaar_naam - Broker code and name
  • Record_Type - "Actief", "Post-IN", etc.
  • Bedrag_excl_ass_belasting - Premium amount
  • Date fields: Ingangsdatum, Premievervaldatum, etc.

Example Policy Data:

{
  "Ordernummer": "A331939",
  "PolisNummer": "0036003-23282",
  "Klantnummer": "V0283059",
  "Klant_naam": "Klinkhamer",
  "Makelaar": "MAK11570",
  "Makelaar_naam": "OpGroen Verzekeringen t.b.v. KNJV",
  "Account_manager": "FL",
  "Record_Type": "Actief",
  "Sjabloonomschrijving": "AVP JAGERS KNJV",
  "Ingangsdatum": "2024-04-01",
  "Premievervaldatum": "2025-04-01",
  "Bedrag_excl_ass_belasting": 33.06,
  "Klant_adres": "Hoofdstraat",
  "Klant_postcode": "7873 TB",
  "Klant_plaats": "ODOORN"
}

Useful OData Filters

For Policies:

  • "Record_Type eq 'Actief'" - Active policies
  • "Klantnummer eq 'V0283059'" - Specific customer
  • "Account_manager eq 'FL'" - Specific account manager
  • "Bedrag_excl_ass_belasting gt 1000" - High-value policies

📄 Xtendis Document Management Integration

The server includes comprehensive integration with the Xtendis document management system for handling insurance documents, policies, claims, and correspondence.

Configuration

Set these environment variables for Xtendis access:

XTENDIS_BASE_URL="https://hfar2.hienfeld.local/rest"
XTENDIS_USERNAME="username"
XTENDIS_PASSWORD="password"
XTENDIS_TENANT_NAME="Hienfeld"
XTENDIS_TIMEOUT=30

Key Xtendis Features

  • Automatic Session Management: JWT authentication and token refresh handled internally
  • Document Archives: Full support for multiple document archives (Policies, Claims, Correspondence)
  • File Operations: Upload, download, and PDF conversion capabilities
  • Metadata Management: Rich tag system for document classification and search
  • Advanced Search: Flexible search criteria with OData-style filtering
  • Document Workflow: Note system, status tracking, and document lifecycle management

Typical Document Archives

  • Policies Archive: Insurance policy documents and contracts
  • Claims Archive: Claims documentation and correspondence
  • Correspondence Archive: Customer communications and letters
  • Legal Archive: Legal documents and regulatory filings

Document Tags

  • CustomerNumber: Hienfeld customer identifier (e.g., "V0283059")
  • PolicyNumber: Policy reference number
  • DocumentType: Policy, Claim, Correspondence, Legal, etc.
  • CreationDate: Document creation timestamp
  • Status: Document processing status (New, Processed, Archived)
  • Department: Responsible department (Claims, Underwriting, Legal)
  • Priority: Document priority level (Low, Medium, High, Urgent)

Example Document Operations

Upload a policy document:

result = await upload_document_with_file(
    archive_id=1,
    file_content_base64="base64_encoded_content",
    filename="policy_V0283059.pdf",
    document_tags={
        "CustomerNumber": ["V0283059"],
        "PolicyNumber": ["POL-2023-001"],
        "DocumentType": ["Policy"],
        "Status": ["New"]
    }
)

Search for customer documents:

search_criteria = {
    "DocumentOperations": [
        {
            "TagName": "CustomerNumber",
            "CompareOperator": "Equals",
            "Values": ["V0283059"],
            "TagType": "Custom"
        }
    ]
}
result = await search_documents(archive_id=1, search_criteria=search_criteria)

Get document as PDF:

pdf_result = await get_document_as_pdf(archive_id=1, document_id=12345)

Integration with Navision

The Xtendis integration complements the existing Navision OData integration:

  • Navision: Provides policy data, customer information, and business logic
  • Xtendis: Provides document storage, retrieval, and management
  • Combined: Offers complete insurance workflow coverage

All Xtendis tools return structured JSON responses with success/error status for reliable error handling and integration.

🔒 Security Features

OAuth2 Authentication System

The server implements a comprehensive OAuth2 authentication system using FastAPI's standard security patterns:

Supported OAuth2 Flows
  • Client Credentials Flow: For service-to-service authentication (recommended for Claude Desktop)
  • Password Flow: For user authentication with username/password
  • JWT Bearer Tokens: All HTTP endpoints protected with JWT
Authentication Features
  • JWT with JTI: Tokens include JWT ID for revocation support
  • Token Blacklisting: Ability to revoke tokens before expiration
  • Role-Based Access Control: Users have roles (admin, agent, service) with specific permissions
  • Strong Encryption: Configurable JWT secrets with HS256 algorithm
  • Token Expiration: Configurable token lifetime (default: 24 hours)
Development vs Production
  • Development: Pre-configured clients and users for easy testing
  • Production: Environment-based JWT secrets and proper client management
  • STDIO Mode: Legacy mode with no authentication (Claude Desktop compatibility)

Audit & Compliance

  • Request/response logging
  • User action auditing
  • Security event monitoring
  • Structured logging with user identification

🔧 Troubleshooting

Common Issues & Solutions

  1. Claude Desktop JSON-RPC Communication Errors

    ✅ FIXED: "Unexpected token" errors in Claude Desktop logs

Problem: Log output polluting stdout breaks JSON-RPC communication
Solution: Use LOG_LEVEL='ERROR' and DEBUG='false' in configuration

Example error: Unexpected token 'I', "Initializi"... is not valid JSON

  2. NTLM Authentication Error

    ✅ FIXED: HttpNtlmAuth.__init__() got an unexpected keyword argument 'domain'

Problem: Incorrect NTLM authentication parameter usage
Solution: Domain is included in username format: "HIENFELD\\username"
Fixed in: src/utils/odata_client.py line 35-39

  3. Module Not Found Errors in WSL

    # Problem: ModuleNotFoundError: No module named 'src'
# Solution: Ensure correct working directory
cd /mnt/c/Users/thomas/Development/mcp-hybrid-server
python3 -m src.server.main --stdio

# Problem: ModuleNotFoundError: No module named 'structlog'
# Solution: Install Python dependencies
pip install -r requirements.txt

  4. Docker Connection Issues on Windows

    ✅ AVOIDED: Docker Desktop not running errors

Problem: Docker engine connectivity issues
Solution: Use WSL-based STDIO approach instead of Docker
Recommended: Native STDIO setup is more reliable for Claude Desktop

  5. OData Connection Issues

    # Check OData configuration
echo $ODATA_BASE_URL
echo $ODATA_USERNAME

# Test OData connection with NTLM
curl -u "HIENFELD\\$ODATA_USERNAME:$ODATA_PASSWORD" "$ODATA_BASE_URL/ActivePolissen?\$top=1"

  6. Claude Desktop Configuration Path Issues

    # Windows configuration location
%APPDATA%\Claude\claude_desktop_config.json

# Common path issues:
# ❌ Wrong: "C:\Users\thomas\Development\mcp-hybrid-server"
# ✅ Correct: "/mnt/c/Users/thomas/Development/mcp-hybrid-server" (in WSL)

  7. STDIO Mode Setup Verification

    # Test STDIO mode directly
cd /path/to/mcp-hybrid-server
export DEBUG=false LOG_LEVEL=ERROR
python3 -m src.server.main --stdio

# Should see clean JSON-RPC output only, no log messages

📄 Configuration Reference

Environment Variables

The server includes sensible defaults for development. Environment variables are optional unless you need to customize specific settings.

Core Settings (with defaults):

# Server Configuration
SERVER_NAME="Insurance MCP Server"  # Default
HOST="0.0.0.0"                     # Default
PORT=8000                           # Default
DEBUG=false                         # Default
LOG_LEVEL="INFO"                    # Default

# Security (using development defaults)
SECRET_KEY="dev-secret-key-change-in-production"
JWT_SECRET_KEY="dev-jwt-secret-change-in-production"

# Hienfeld OData Integration
ODATA_BASE_URL="http://HFDB2.hienfeld.local:7068/HF-NAV2018-B/ODataV4/Company('W.A.%20Hienfeld%20Assuradeuren%20BV')"
ODATA_USERNAME="your_username"
ODATA_PASSWORD="your_password"
ODATA_DOMAIN="hienfeld"

# Deployment Mode
DEPLOYMENT_MODE="hybrid"           # Default: hybrid, cloud, on-prem

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make changes with tests
  4. Run quality checks: black src/ tests/ && flake8 src/ tests/ && mypy src/
  5. Run test suite: python3 -m pytest tests/ -v
  6. Submit a pull request

📄 License

Copyright (c) 2024 Hienfeld Insurance. All rights reserved.

🆘 Support

  • Documentation: See this README and CLAUDE.md
  • Issues: Create GitHub issues for bugs
  • Testing: Run python3 test_mcp.py for integration testing

✅ Production Readiness Checklist

  • Core MCP Server: FastMCP-based implementation complete
  • Navision Tools: 9 tools implemented and tested
  • Authentication: JWT-based auth with RBAC
  • Configuration: Environment-based settings with defaults
  • Testing: Comprehensive unit and integration tests
  • Documentation: Complete README and examples
  • Claude Desktop Support: Fixed Depends error, works seamlessly
  • Error Handling: Robust error handling and validation
  • Monitoring: Health check and structured logging
  • OData Integration: Direct Hienfeld Dynamics NAV connection

Status: 🚀 Ready for Production Deployment

Quick Start for Hienfeld Users (WebSocket + Docker):

  1. Clone: git clone <repo> && cd mcp-hybrid-server
  2. Configure: cp .env.example .env and update NAV credentials
  3. Deploy: docker compose up -d
  4. Test: curl http://localhost:8000/health
  5. Claude Desktop: Use WebSocket config: ws://localhost:8000/mcp/ws
  6. Monitor: View logs with docker compose logs -f mcp-server