OSDU MCP 服务器

一个模型上下文协议（MCP）服务器，提供AI助手访问OSDU平台功能的能力。

目的

此服务器使AI助手能够通过MCP协议与OSDU平台服务进行交互，包括搜索、数据管理和模式操作。

安装

# 克隆仓库
git clone <repository-url>
cd osdu-mcp-server

# 使用uv安装（推荐）
uv sync
uv pip install -e '.[dev]'

配置

要使用OSDU MCP服务器，请通过您的MCP客户端配置文件进行配置：

{
  "mcpServers": {
    "osdu-mcp-server": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "osdu-mcp-server"],
      "env": {
        "OSDU_MCP_SERVER_URL": "https://your-osdu.com",
        "OSDU_MCP_SERVER_DATA_PARTITION": "your-partition",
        "AZURE_CLIENT_ID": "your-client-id",
        "AZURE_TENANT_ID": "your-tenant"
      }
    }
  }
}

认证方法

默认情况下，认证通过Azure CLI处理。在运行服务器之前，您必须使用az login登录：

要启用服务主体认证，请添加可选的AZURE_CLIENT_SECRET环境变量：

写操作

任何服务的写操作（创建、更新）默认是禁用的，您必须明确启用它们：

"env": {
  "OSDU_MCP_ENABLE_WRITE_MODE": "true"
}

删除操作

删除和清除操作分别控制，默认是禁用的：

"env": {
  "OSDU_MCP_ENABLE_DELETE_MODE": "true"
}

这种双重保护允许您启用数据创建和更新，同时严格控制破坏性操作。

日志配置

MCP服务器使用遵循ADR-016的结构化JSON日志。默认情况下，由于冗长，日志是禁用的。您可以设置以下内容来启用它：

"env": {
  "OSDU_MCP_LOGGING_ENABLED": "true",
  "OSDU_MCP_LOGGING_LEVEL": "INFO"  // 可选，默认为INFO
}

有效日志级别：DEBUG, INFO, WARNING, ERROR, CRITICAL

使用

健康检查

osdu:health_check

这会返回您的OSDU平台健康状态，检查认证以及所有服务（存储、搜索、法律、模式、文件、工作流、权限和数据集）的可用性。

可用工具

基础设施

• health_check: 检查OSDU平台连接性和服务健康状况

分区服务

• partition_list: 列出所有可访问的OSDU分区
• partition_get: 获取特定分区的配置
• partition_create: 创建新的分区（写保护）
• partition_update: 更新分区属性（写保护）
• partition_delete: 删除分区（写保护）

权限服务

• entitlements_mine: 获取当前认证用户的组

法律服务

• legaltag_list: 列出所有法律标签
• legaltag_get: 获取特定法律标签
• legaltag_get_properties: 获取允许的属性值
• legaltag_search: 使用过滤器搜索法律标签
• legaltag_batch_retrieve: 一次获取多个标签
• legaltag_create: 创建新的法律标签（写保护）
• legaltag_update: 更新法律标签（写保护）
• legaltag_delete: 删除法律标签（删除保护）

模式服务

• schema_list: 列出可用模式，可选过滤
• schema_get: 根据ID检索完整的模式
• schema_search: 使用丰富的过滤器和文本搜索进行高级模式发现
• schema_create: 创建新的模式（写保护）
• schema_update: 更新现有模式（写保护）

高级模式搜索

schema_search工具提供了强大的能力来发现模式：

# 查找描述中包含“压力”的所有模式
schema_search(text="压力", search_in=["description"])

# 获取任何权威下版本为1.1.*的所有模式
schema_search(version_pattern="1.1.*")

# 搜索具有特定属性组合的模式
schema_search(
    filter={
        "authority": ["osdu", "lab"],
        "status": ["PUBLISHED"],
        "scope": "SHARED"
    }
)

# 在结果中包含完整的模式内容
schema_search(include_content=True)

存储服务

• storage_create_update_records: 创建或更新记录（写保护）
• storage_get_record: 根据ID获取记录的最新版本
• storage_get_record_version: 获取记录的具体版本
• storage_list_record_versions: 列出记录的所有版本
• storage_query_records_by_kind: 获取特定类型的记录ID
• storage_fetch_records: 一次性检索多个记录
• storage_delete_record: 逻辑删除记录（删除保护）
• storage_purge_record: 永久删除记录（删除保护）

存储操作和保护

存储服务实现了两种级别的保护，用于不同类型的操作：

• 写操作（创建、更新）：由OSDU_MC_ENABLE_WRITE_MODE=true控制
• 删除操作（删除、清除）：由OSDU_MC_ENABLE_DELETE_MODE=true控制

这提供了对数据生命周期操作的细粒度控制，允许环境允许数据创建，同时防止删除。

高级路线图

• 第二阶段（已完成）：分区、法律和权限服务
• 第三阶段（已完成）：模式服务和高级搜索功能
• 第四阶段（已完成）：存储服务和数据验证
• 第五阶段（未来）：高级特性和集成

文档

• 项目简介
• 项目需求
• 架构概述
• 架构设计决策
• 基础规范

项目开发

这是一个AI开发的项目，使用AI编码工具加速开发，同时努力保持高标准的质量。阅读案例研究以深入了解哪些方法被证明是有效的。 </中文翻译>