Odata MCP Server

OData API Discovery MCP服务器

一种模型上下文协议（MCP）服务器，可帮助AI代理基于本地缓存的元数据发现和调用适当的OData API。

特性

• 智能API发现：从缓存的元数据中自动发现可用的OData API
• 参数推断：分析用户需求并建议适当的API端点和参数
• 元数据解析：支持OData v2和v4元数据格式
• 实体关系导航：根据导航属性建议相关实体
• 参数验证：根据实体元数据架构验证参数
• API调用生成：生成具有正确URL、方法和有效载荷的完整HTTP请求

安装

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

配置

目录结构

your-project/
├── odata-mcp-server.ts
├── metadata/
│   ├── northwind.xml
│   ├── hr-service.edmx
│   └── inventory.xml
└── package.json

环境变量

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

MCP客户端配置

添加到您的MCP客户端配置中（例如，Claude Desktop）：

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

使用示例

1.发现可用的API

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

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

2.分析用户需求

// 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.获取实体详细信息

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

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

4.生成API调用

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

// Response: Complete HTTP request configuration

5.验证参数

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

// Response: Validation results with errors and warnings

6.查找相关实体

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

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

支持的OData功能

元数据元素

• 实体类型和实体集
• 属性（带类型验证）
• 按键和导航属性
• 功能和动作导入
• 参考约束

运营

• CRUD操作：创建、读取、更新、删除
• 函数：带有参数的OData函数
• 行动：具有副作用的OData操作
• 过滤：$filter查询参数支持
• 导航：以下实体关系

数据类型

• 基本类型（String、Int32、DateTime等）
• 复杂类型
• 集合类型
• 无效验证
• 长度和精度约束

错误处理

服务器为以下内容提供全面的错误处理：

• 元数据文件缺失或无效
• 未知的服务或实体
• 类型验证错误
• 缺少必要参数
• 请求格式错误

扩展服务器

添加自定义分析器

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

添加身份验证

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

自定义元数据源

async loadFromDatabase(): Promise {
  // 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);
  }
}

最佳实践

元数据管理

1. 版本控制：将元数据文件保存在版本控制中
2. 命名约定：使用一致的服务命名
3. 文档：在元数据中包含描述
4. 验证：部署前验证元数据文件

性能优化

1. 缓存：元数据缓存在内存中，以便快速访问
2. 延迟加载：仅在需要时加载元数据
3. 压缩：压缩大型元数据文件
4. 索引：索引经常访问的实体

安全考虑

1. 输入验证：所有参数都根据模式进行验证
2. 访问控制：实施服务级别访问控制
3. 速率限制：为API调用添加速率限制
4. 日志记录：记录所有API发现活动

故障排除

常见问题

元数据未加载

# Check file permissions
ls -la ./metadata/

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

未找到实体

• 验证实体名称是否与元数据完全匹配
• 检查命名空间前缀
• 确保服务名称正确

类型验证错误

• 检查元数据中的属性类型
• 验证可为null的约束
• 验证日期/时间格式

调试模式

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

集成示例

使用克劳德桌面

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

使用自定义AI代理

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)

贡献

要为OData MCP服务器做出贡献，请执行以下操作：

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 更新文档
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

相关项目

根据我的研究，您应该了解以下现有的解决方案：

• 通用OData↔ MCP电桥：自动发现OData实体并将其转换为MCP工具
• OData的CData MCP服务器：将OData作为MCP工具集公开的商业解决方案

此实现提供了一种更具可定制性和功能性的替代方案，具有高级参数验证、智能API发现和全面的元数据分析功能。