odata-mcp-server

ichungyoung/odata-mcp-server

3.2

If you are the rightful owner of odata-mcp-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 henry@mcphub.com.

The OData API Discovery MCP Server is a specialized server designed to assist AI agents in discovering and invoking OData APIs using locally cached metadata.

OData API Discovery MCP Server

A Model Context Protocol (MCP) server that assists AI agents in discovering and invoking appropriate OData APIs based on locally cached metadata.

Features

  • Intelligent API Discovery: Automatically discovers available OData APIs from cached metadata
  • Parameter Inference: Analyzes user requirements and suggests appropriate API endpoints and parameters
  • Metadata Parsing: Supports both OData v2 and v4 metadata formats
  • Entity Relationship Navigation: Suggests related entities based on navigation properties
  • Parameter Validation: Validates parameters against entity metadata schemas
  • API Call Generation: Generates complete HTTP requests with proper URLs, methods, and payloads

Installation

npm install @modelcontextprotocol/sdk axios fast-xml-parser

Configuration

Directory Structure

your-project/
ā”œā”€ā”€ odata-mcp-server.ts
ā”œā”€ā”€ metadata/
ā”‚   ā”œā”€ā”€ northwind.xml
ā”‚   ā”œā”€ā”€ hr-service.edmx
ā”‚   ā””ā”€ā”€ inventory.xml
ā””ā”€ā”€ package.json

Environment Variables

# Optional: Custom metadata directory (defaults to ./metadata)
export ODATA_METADATA_DIR="/path/to/your/metadata"

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "odata-discovery": {
      "command": "node",
      "args": ["./odata-mcp-server.js"],
      "env": {
        "ODATA_METADATA_DIR": "./metadata"
      }
    }
  }
}

Usage Examples

1. Discover Available APIs

// Tool call: discover_apis
{
  "query": "customer",
  "service": "northwind"
}

// Response: Lists all customer-related entity sets and operations

2. Analyze User Requirements

// Tool call: analyze_api_requirements
{
  "userRequest": "I need to find all orders for a specific customer and update their status"
}

// Response: Suggests Customer and Order entities with read and update operations

3. Get Entity Details

// Tool call: get_entity_details
{
  "service": "northwind",
  "entityName": "Customer"
}

// Response: Complete entity schema with properties, keys, and navigation properties

4. Generate API Call

// Tool call: generate_api_call
{
  "service": "northwind",
  "operation": "read",
  "entitySet": "Customers",
  "parameters": { "id": "ALFKI" },
  "filters": ["Country eq 'Germany'"]
}

// Response: Complete HTTP request configuration

5. Validate Parameters

// Tool call: validate_parameters
{
  "service": "northwind",
  "entityName": "Customer",
  "parameters": {
    "CustomerID": "NEWCO",
    "CompanyName": "New Company",
    "ContactName": null
  }
}

// Response: Validation results with errors and warnings

6. Find Related Entities

// Tool call: suggest_related_entities
{
  "service": "northwind",
  "entityName": "Customer",
  "relationshipType": "one-to-many"
}

// Response: Lists related entities like Orders, with relationship details

Supported OData Features

Metadata Elements

  • Entity Types and Entity Sets
  • Properties (with type validation)
  • Keys and Navigation Properties
  • Function and Action Imports
  • Referential Constraints

Operations

  • CRUD Operations: Create, Read, Update, Delete
  • Functions: OData functions with parameters
  • Actions: OData actions with side effects
  • Filtering: $filter query parameter support
  • Navigation: Following entity relationships

Data Types

  • Primitive types (String, Int32, DateTime, etc.)
  • Complex types
  • Collection types
  • Nullable validation
  • Length and precision constraints

Error Handling

The server provides comprehensive error handling for:

  • Missing or invalid metadata files
  • Unknown services or entities
  • Type validation errors
  • Missing required parameters
  • Malformed requests

Extending the Server

Adding Custom Analyzers

class CustomAnalyzer {
  analyzeIntent(userRequest: string): AnalysisResult {
    // Custom NLP logic
    return {
      intent: 'custom',
      entities: [],
      confidence: 0.8
    };
  }
}

Adding Authentication

private addAuthHeaders(headers: any, service: string): any {
  return {
    ...headers,
    'Authorization': `Bearer ${this.getServiceToken(service)}`
  };
}

Custom Metadata Sources

async loadFromDatabase(): Promise<void> {
  // Load metadata from database instead of files
  const services = await db.getODataServices();
  for (const service of services) {
    const metadata = await this.parseMetadata(service.metadata);
    this.metadataCache.set(service.name, metadata);
  }
}

Best Practices

Metadata Management

  1. Version Control: Keep metadata files in version control
  2. Naming Convention: Use consistent service naming
  3. Documentation: Include descriptions in metadata
  4. Validation: Validate metadata files before deployment

Performance Optimization

  1. Caching: Metadata is cached in memory for fast access
  2. Lazy Loading: Load metadata only when needed
  3. Compression: Compress large metadata files
  4. Indexing: Index frequently accessed entities

Security Considerations

  1. Input Validation: All parameters are validated against schemas
  2. Access Control: Implement service-level access controls
  3. Rate Limiting: Add rate limiting for API calls
  4. Logging: Log all API discovery activities

Troubleshooting

Common Issues

Metadata Not Loading

# Check file permissions
ls -la ./metadata/

# Validate XML structure
xmllint --noout ./metadata/service.xml

Entity Not Found

  • Verify entity name matches metadata exactly
  • Check namespace prefixes
  • Ensure service name is correct

Type Validation Errors

  • Check property types in metadata
  • Verify nullable constraints
  • Validate date/time formats

Debug Mode

# Enable verbose logging
DEBUG=odata-mcp:* node odata-mcp-server.js

Integration Examples

With Claude Desktop

{
  "mcpServers": {
    "odata": {
      "command": "node",
      "args": ["/path/to/odata-mcp-server.js"],
      "env": {
        "ODATA_METADATA_DIR": "/path/to/metadata"
      }
    }
  }
}

With Custom AI Agent

import asyncio
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters

async def use_odata_discovery():
    server = StdioServerParameters(
        command="node",
        args=["./odata-mcp-server.js"]
    )
    
    async with ClientSession(server) as session:
        # Discover APIs
        result = await session.call_tool(
            "discover_apis",
            {"query": "customer"}
        )
        print(result)

Contributing

To contribute to the OData MCP Server:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Update documentation
  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Related Projects

Based on my research, there are existing solutions you should be aware of:

  • Universal OData ā†” MCP Bridge: Auto-discovers OData entities and translates them to MCP tools
  • CData MCP Server for OData: Commercial solution that exposes OData as MCP toolsets

This implementation provides a more customizable and feature-rich alternative with advanced parameter validation, intelligent API discovery, and comprehensive metadata analysis capabilities.