OSDU MCP Server

Accede a las capacidades de la plataforma OSDU, incluyendo búsqueda, gestión de datos y operaciones de esquema.

Documentación

Servidor OSDU MCP

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona a los asistentes de IA acceso a las capacidades de la plataforma OSDU.

Propósito

Este servidor permite que los asistentes de IA interactúen con los servicios de la plataforma OSDU, incluyendo búsqueda, gestión de datos y operaciones de esquemas a través del protocolo MCP.

Desarrollo Impulsado por IA

Este proyecto sigue un flujo de trabajo de desarrollo impulsado por IA:

🤖 Construido con IA - Desarrollado con Claude Code y GitHub Copilot
📋 Asignación de Tareas con IA - Los issues etiquetados con copilot se asignan automáticamente
📚 Documentación Amigable para IA - Guías completas para agentes de IA en CLAUDE.md y .github/copilot-instructions.md
🔄 Orquestación Multi-Agente - Diferentes agentes de IA manejan diferentes tareas según sus fortalezas

Consulte nuestro Caso de Estudio para obtener información sobre cómo construir código de calidad con agentes de IA.

Documentación

Instalación

# Clone the repository
git clone <repository-url>
cd osdu-mcp-server

# Install using uv (recommended)
uv sync
uv pip install -e '.[dev]'

Configuración

CLI de Claude Code

Para agregar este servidor MCP usando la CLI de Claude Code:

claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \
  -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \
  -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \
  -e "AZURE_CLIENT_ID=your-client-id" \
  -e "AZURE_TENANT_ID=your-tenant-id"

Instalación Directa

Para usar este servidor MCP en sus proyectos, agregue lo siguiente a su archivo .mcp.json:

{
  "mcpServers": {
    "osdu-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main",
        "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-id"
      }
    }
  }
}

Instalación Rápida en VS Code

Desarrollo Local

Para el desarrollo local, también puede usar el método de instalación local:

Para usar el Servidor OSDU MCP, configúrelo a través del archivo de configuración de su cliente 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"
      }
    }
  }
}

Configuración de Dominio

Crítico para el Formato ACL: Los despliegues de OSDU utilizan diferentes formatos de dominio de datos para las Listas de Control de Acceso (ACL). Configure su dominio de datos para evitar errores de formato ACL:

"env": {
  "OSDU_MCP_SERVER_DOMAIN": "contoso.com"
}

Ejemplos de Dominio de Datos:

OSDU estándar: contoso.com (predeterminado)
Microsoft OSDU: dataservices.energy
Microsoft Interno: msft-osdu-test.org

Métodos de Detección de Dominio de Datos:

Variable de Entorno (Recomendado): Establezca OSDU_MCP_SERVER_DOMAIN
Use la Herramienta de Entitlements: Ejecute entitlements_mine() para ver el formato de su grupo
Consulte con el Administrador: Pregunte a su administrador de OSDU por el dominio de datos correcto

Importante: El dominio de datos es el dominio interno del sistema de datos de OSDU utilizado en los correos de grupos ACL, no el FQDN de la URL de su servidor.

Si no se establece, el servidor intentará extraer el dominio de la URL de su servidor. Para más orientación, use el recurso MCP: ReadMcpResourceTool(server="osdu-mcp-server", uri="file://acl-format-examples.json").

Métodos de Autenticación

El servidor soporta autenticación multi-nube con detección automática de proveedor:

Prioridad de Autenticación

El servidor detecta automáticamente su proveedor de autenticación en este orden de prioridad:

Token Manual (prioridad más alta) - OSDU_MCP_USER_TOKEN
Azure - AZURE_CLIENT_ID o AZURE_TENANT_ID
AWS (explícito) - AWS_ACCESS_KEY_ID o AWS_PROFILE
GCP (explícito) - GOOGLE_APPLICATION_CREDENTIALS
AWS (auto-descubrimiento) - Roles IAM, SSO
GCP (auto-descubrimiento) - gcloud, servicio de metadatos

Autenticación de Azure

Método 1: CLI de Azure (Desarrollo)

Configuración: Ejecute az login antes de usar el servidor
Variables de Entorno:
- AZURE_CLIENT_ID: El ID de su aplicación OSDU
- AZURE_TENANT_ID: El ID de su tenant de Azure
- No se necesita AZURE_CLIENT_SECRET

Ejemplo:

az login
claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \
  -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \
  -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \
  -e "AZURE_CLIENT_ID=your-osdu-app-id" \
  -e "AZURE_TENANT_ID=your-tenant-id"

Método 2: Service Principal (Producción)

Configuración: Cree o use un service principal existente
Variables de Entorno:
- AZURE_CLIENT_ID: ID del service principal
- AZURE_CLIENT_SECRET: Secreto del service principal
- AZURE_TENANT_ID: El ID de su tenant de Azure
- OSDU_MCP_AUTH_SCOPE: (Opcional) Alcance OAuth personalizado para entornos de token v1.0 (consulte Autenticación de GCP para su significado en GCP)

Ejemplo:

claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \
  -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \
  -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \
  -e "AZURE_CLIENT_ID=your-service-principal-id" \
  -e "AZURE_CLIENT_SECRET=your-service-principal-secret" \
  -e "AZURE_TENANT_ID=your-tenant-id"

Autenticación de AWS

Método 1: AWS SSO (Desarrollo)

Configuración: Configure AWS SSO e inicie sesión
Variables de Entorno:
- AWS_PROFILE: El nombre de su perfil de AWS
- (El resto de la configuración de OSDU como de costumbre)

Ejemplo:

aws sso login --profile dev-profile
claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \
  -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \
  -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \
  -e "AWS_PROFILE=dev-profile"

Método 2: Claves de Acceso (Producción)

Configuración: Obtenga claves de acceso de AWS
Variables de Entorno:
- AWS_ACCESS_KEY_ID: Su clave de acceso de AWS
- AWS_SECRET_ACCESS_KEY: Su clave secreta de AWS
- AWS_REGION: Región de AWS (por ejemplo, us-east-1)

Ejemplo:

claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \
  -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \
  -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \
  -e "AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE" \
  -e "AWS_SECRET_ACCESS_KEY=your-secret-key" \
  -e "AWS_REGION=us-east-1"

Método 3: Roles IAM (EC2/ECS/Lambda)

Configuración: Asigne un rol IAM a su instancia de cómputo
Variables de Entorno: ¡Ninguna necesaria! Descubrimiento automático de credenciales
Nota: Funciona en EC2, ECS/Fargate, Lambda con roles IAM apropiados

Autenticación de GCP

Método 1: CLI de gcloud (Desarrollo)

Configuración: Ejecute gcloud auth application-default login
Variables de Entorno: ¡Ninguna necesaria! Descubrimiento automático de credenciales

Ejemplo:

gcloud auth application-default login
claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \
  -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \
  -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition"

Método 2: Clave de Cuenta de Servicio (Producción)

Configuración: Descargue la clave JSON de la cuenta de servicio
Variables de Entorno:
- GOOGLE_APPLICATION_CREDENTIALS: Ruta a la clave JSON de la cuenta de servicio

Ejemplo:

claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \
  -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \
  -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \
  -e "GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json"

Método 3: Workload Identity (GKE)

Configuración: Configure Workload Identity en GKE
Variables de Entorno: ¡Ninguna necesaria! Descubrimiento automático de credenciales
Nota: Funciona en GKE con Workload Identity configurado

Alcances

Todos los métodos de GCP solicitan cloud-platform más los alcances de identidad openid y userinfo.email por defecto. Los alcances de identidad no otorgan acceso adicional — hacen que la dirección de correo del llamante esté presente en el token, lo cual OSDU requiere para resolver entitlements. Sin ellos, cada solicitud de OSDU falla con 401 Access denied.

OSDU_MCP_AUTH_SCOPE: (Opcional) Lista de alcances separados por comas que reemplaza los predeterminados

Ejemplo:

claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \
  -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \
  -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \
  -e "OSDU_MCP_AUTH_SCOPE=https://www.googleapis.com/auth/cloud-platform,openid,https://www.googleapis.com/auth/userinfo.email"

Token OAuth Manual (Cualquier Proveedor)

Caso de Uso: Proveedores OAuth personalizados, pruebas o nubes no soportadas

Configuración: Obtenga un token Bearer OAuth de su proveedor
Variables de Entorno:
- OSDU_MCP_USER_TOKEN: Su token Bearer OAuth (formato JWT)
- Prioridad: Este método SIEMPRE tiene prioridad sobre todos los demás

Ejemplo:

# Obtain token from your OAuth provider
TOKEN=$(your-oauth-command)

claude mcp add osdu-mcp-server uvx "git+https://github.com/danielscholl-osdu/osdu-mcp-server@main" \
  -e "OSDU_MCP_SERVER_URL=https://your-osdu.com" \
  -e "OSDU_MCP_SERVER_DATA_PARTITION=your-partition" \
  -e "OSDU_MCP_USER_TOKEN=$TOKEN"

Requisitos del Token:

Formato JWT válido (header.payload.signature)
No expirado
El servidor advierte si el token expira dentro de 5 minutos

Notas de Seguridad:

Los tokens se validan por formato y expiración
Los tokens nunca se registran en logs
Los tokens deben renovarse manualmente cuando expiran

Configuración de Autorización

Cuándo necesita configuración adicional:

✅ Autenticación CLI de Azure: Siempre requiere configuración de autorización
✅ Service principal externo: Requiere configuración de autorización
❌ Service principal propio de la aplicación OSDU: No se necesita configuración adicional

Para CLI de Azure o Service Principal Externo:

Navegue a su aplicación OSDU en App registrations
Vaya a Expose an API → Authorized client applications
Haga clic en Add a client application
Ingrese el ID de cliente:
- CLI de Azure: 04b07795-8ddb-461a-bbee-02f9e1bf7b46
- Service Principal Externo: El ID de su service principal
Seleccione el alcance user_impersonation
Haga clic en Add

Verifique la autenticación:

az account get-access-token --resource YOUR_AZURE_CLIENT_ID

Problemas Comunes:

"Application not found": La aplicación de CLI de Azure no existe en algunos tenants. Use un service principal en su lugar.
"Invalid resource": El cliente no ha sido autorizado. Siga la configuración de autorización anterior.
"Authentication failed": Verifique que su ID de cliente coincida con su aplicación OSDU o service principal.

Operaciones de Escritura

Las operaciones de escritura (crear, actualizar) para cualquier servicio están deshabilitadas por defecto; debe habilitarlas explícitamente:

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

Operaciones de Eliminación

Las operaciones de eliminación y purga se controlan por separado y están deshabilitadas por defecto:

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

Esta doble protección le permite habilitar la creación y actualización de datos mientras mantiene un control estricto sobre las operaciones destructivas.

Ejemplo de Configuración Completa

Aquí hay un ejemplo completo de configuración de .mcp.json con todas las variables de entorno comunes:

{
  "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": "opendes",
        "OSDU_MCP_SERVER_DOMAIN": "contoso.com",
        "OSDU_MCP_ENABLE_WRITE_MODE": "true",
        "OSDU_MCP_ENABLE_DELETE_MODE": "true",
        "AZURE_CLIENT_ID": "your-client-id",
        "AZURE_TENANT_ID": "your-tenant-id",
        "AZURE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Configuración de Registro (Logging)

El servidor MCP utiliza registro JSON estructurado que sigue ADR-016. Por defecto, el registro está deshabilitado debido a su verbosidad. Puede habilitarlo estableciendo:

"env": {
  "OSDU_MCP_LOGGING_ENABLED": "true",
  "OSDU_MCP_LOGGING_LEVEL": "INFO" 
}

Niveles de registro válidos: DEBUG, INFO, WARNING, ERROR, CRITICAL

Uso

Verificación de Salud

osdu:health_check

Esto devuelve el estado de salud de su plataforma OSDU, verificando la autenticación y la disponibilidad de todos los servicios (storage, search, legal, schema, file, workflow, entitlements y dataset).

Capacidades Disponibles

Prompts

list_mcp_assets: Descripción general completa de todas las capacidades del servidor con ejemplos de uso y guía de inicio rápido
guide_search_patterns: Guía de patrones de búsqueda para operaciones de OSDU con ejemplos de sintaxis de Elasticsearch

Herramientas

Fundación

health_check: Verificar la conectividad de la plataforma OSDU y la salud de los servicios

Servicio de Particiones

partition_list: Listar todas las particiones de OSDU accesibles
partition_get: Recuperar la configuración de una partición específica
partition_create: Crear una nueva partición (protegida contra escritura)
partition_update: Actualizar propiedades de una partición (protegida contra escritura)
partition_delete: Eliminar una partición (protegida contra escritura)

Servicio de Entitlements

entitlements_mine: Obtener grupos para el usuario autenticado actual

Servicio Legal

legaltag_list: Listar todas las etiquetas legales
legaltag_get: Obtener una etiqueta legal específica
legaltag_get_properties: Obtener valores de propiedades permitidos
legaltag_search: Buscar etiquetas legales con filtros
legaltag_batch_retrieve: Obtener múltiples etiquetas a la vez
legaltag_create: Crear una nueva etiqueta legal (protegida contra escritura)
legaltag_update: Actualizar una etiqueta legal (protegida contra escritura)
legaltag_delete: Eliminar una etiqueta legal (protegida contra eliminación)

Servicio de Esquemas

schema_list: Listar esquemas disponibles con filtrado opcional
schema_get: Recuperar el esquema completo por ID
schema_search: Descubrimiento avanzado de esquemas con filtrado enriquecido y búsqueda de texto
schema_create: Crear un nuevo esquema (protegido contra escritura)
schema_update: Actualizar un esquema existente (protegido contra escritura)

Servicio de Búsqueda

search_query: Ejecutar consultas de búsqueda usando sintaxis de Elasticsearch
search_by_id: Encontrar registros específicos por ID
search_by_kind: Encontrar todos los registros de un tipo específico

Servicio de Storage

storage_create_update_records: Crear o actualizar registros (protegido contra escritura)
storage_get_record: Obtener la última versión de un registro por ID
storage_get_record_version: Obtener una versión específica de un registro
storage_list_record_versions: Listar todas las versiones de un registro
storage_query_records_by_kind: Obtener IDs de registros de un tipo específico
storage_fetch_records: Recuperar múltiples registros a la vez
storage_delete_record: Eliminar lógicamente un registro (protegido contra eliminación)
storage_purge_record: Eliminar permanentemente un registro (protegido contra eliminación)