OSDU MCP Server

Acesse as capacidades da plataforma OSDU, incluindo pesquisa, gerenciamento de dados e operações de esquema.

Documentação

Servidor OSDU MCP

Um servidor Model Context Protocol (MCP) que fornece a assistentes de IA acesso às capacidades da plataforma OSDU.

Propósito

Este servidor permite que assistentes de IA interajam com os serviços da plataforma OSDU, incluindo busca, gerenciamento de dados e operações de esquema, por meio do protocolo MCP.

Desenvolvimento Orientado por IA

Este projeto segue um fluxo de trabalho de desenvolvimento orientado por IA:

🤖 Construído com IA - Desenvolvido usando Claude Code e GitHub Copilot
📋 Atribuição de Tarefas por IA - Issues rotuladas com copilot são atribuídas automaticamente
📚 Documentação Amigável para IA - Guias abrangentes para agentes de IA em CLAUDE.md e .github/copilot-instructions.md
🔄 Orquestração Multiagente - Diferentes agentes de IA lidam com diferentes tarefas com base em seus pontos fortes

Consulte nosso Estudo de Caso para obter insights sobre como construir código de qualidade com agentes de IA.

Documentação

Instalação

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

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

Configuração

Claude Code CLI

Para adicionar este servidor MCP usando o Claude Code CLI:

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"

Instalação Direta

Para usar este servidor MCP em seus projetos, adicione o seguinte ao seu arquivo .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"
      }
    }
  }
}

Instalação Rápida no VS Code

Desenvolvimento Local

Para desenvolvimento local, você também pode usar o método de instalação local:

Para usar o OSDU MCP Server, configure-o por meio do arquivo de configuração do seu 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"
      }
    }
  }
}

Configuração de Domínio

Crítico para o Formato ACL: Implantações OSDU usam diferentes formatos de domínio de dados para Listas de Controle de Acesso (ACL). Configure seu domínio de dados para evitar erros de formato ACL:

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

Exemplos de Domínio de Dados:

OSDU Padrão: contoso.com (padrão)
Microsoft OSDU: dataservices.energy
Microsoft Interno: msft-osdu-test.org

Métodos de Detecção de Domínio de Dados:

Variável de Ambiente (Recomendado): Defina OSDU_MCP_SERVER_DOMAIN
Use a Ferramenta Entitlements: Execute entitlements_mine() para ver o formato do seu grupo
Verifique com o Administrador: Pergunte ao seu administrador OSDU pelo domínio de dados correto

Importante: O domínio de dados é o domínio interno do sistema de dados OSDU usado em e-mails de grupo ACL, não o FQDN da URL do seu servidor.

Se não for definido, o servidor tentará extrair o domínio da URL do seu servidor. Para mais orientações, use o recurso MCP: ReadMcpResourceTool(server="osdu-mcp-server", uri="file://acl-format-examples.json").

Métodos de Autenticação

O servidor suporta autenticação multinuvem com detecção automática de provedor:

Prioridade de Autenticação

O servidor detecta automaticamente seu provedor de autenticação nesta ordem de prioridade:

Token Manual (maior prioridade) - OSDU_MCP_USER_TOKEN
Azure - AZURE_CLIENT_ID ou AZURE_TENANT_ID
AWS (explícito) - AWS_ACCESS_KEY_ID ou AWS_PROFILE
GCP (explícito) - GOOGLE_APPLICATION_CREDENTIALS
AWS (descoberta automática) - Funções IAM, SSO
GCP (descoberta automática) - gcloud, serviço de metadados

Autenticação Azure

Método 1: Azure CLI (Desenvolvimento)

Configuração: Execute az login antes de usar o servidor
Variáveis de Ambiente:
- AZURE_CLIENT_ID: O ID do seu aplicativo OSDU
- AZURE_TENANT_ID: O ID do seu locatário Azure
- Nenhum AZURE_CLIENT_SECRET necessário

Exemplo:

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 (Produção)

Configuração: Crie ou use um service principal existente
Variáveis de Ambiente:
- AZURE_CLIENT_ID: ID do service principal
- AZURE_CLIENT_SECRET: Segredo do service principal
- AZURE_TENANT_ID: O ID do seu locatário Azure
- OSDU_MCP_AUTH_SCOPE: (Opcional) Escopo OAuth personalizado para ambientes de token v1.0 (consulte Autenticação GCP para seu significado no GCP)

Exemplo:

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"

Autenticação AWS

Método 1: AWS SSO (Desenvolvimento)

Configuração: Configure o AWS SSO e faça login
Variáveis de Ambiente:
- AWS_PROFILE: O nome do seu perfil AWS
- (Outras configurações OSDU como de costume)

Exemplo:

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: Chaves de Acesso (Produção)

Configuração: Obtenha chaves de acesso AWS
Variáveis de Ambiente:
- AWS_ACCESS_KEY_ID: Sua chave de acesso AWS
- AWS_SECRET_ACCESS_KEY: Sua chave secreta AWS
- AWS_REGION: Região AWS (ex.: us-east-1)

Exemplo:

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: Funções IAM (EC2/ECS/Lambda)

Configuração: Atribua uma função IAM à sua instância de computação
Variáveis de Ambiente: Nenhuma necessária! Descoberta automática de credenciais
Nota: Funciona em EC2, ECS/Fargate, Lambda com funções IAM apropriadas

Autenticação GCP

Método 1: CLI gcloud (Desenvolvimento)

Configuração: Execute gcloud auth application-default login
Variáveis de Ambiente: Nenhuma necessária! Descoberta automática de credenciais

Exemplo:

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: Chave de Conta de Serviço (Produção)

Configuração: Baixe a chave JSON da conta de serviço
Variáveis de Ambiente:
- GOOGLE_APPLICATION_CREDENTIALS: Caminho para a chave JSON da conta de serviço

Exemplo:

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)

Configuração: Configure o Workload Identity no GKE
Variáveis de Ambiente: Nenhuma necessária! Descoberta automática de credenciais
Nota: Funciona no GKE com Workload Identity configurado

Escopos

Todos os métodos GCP solicitam cloud-platform mais os escopos de identidade openid e userinfo.email por padrão. Os escopos de identidade não concedem acesso adicional — eles fazem o endereço de e-mail do chamador estar presente no token, o que o OSDU exige para resolver entitlements. Sem eles, toda solicitação OSDU falha com 401 Access denied.

OSDU_MCP_AUTH_SCOPE: (Opcional) Lista de escopos separados por vírgula que substitui os padrões

Exemplo:

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 (Qualquer Provedor)

Caso de Uso: Provedores OAuth personalizados, testes ou nuvens não suportadas

Configuração: Obtenha o token Bearer OAuth do seu provedor
Variáveis de Ambiente:
- OSDU_MCP_USER_TOKEN: Seu token Bearer OAuth (formato JWT)
- Prioridade: Este método SEMPRE tem precedência sobre todos os outros

Exemplo:

# 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 do Token:

Formato JWT válido (header.payload.signature)
Não expirado
O servidor avisa se o token expirar em até 5 minutos

Notas de Segurança:

Os tokens são validados quanto ao formato e expiração
Os tokens nunca são registrados em logs
Os tokens devem ser renovados manualmente quando expirarem

Configuração de Autorização

Quando você precisa de configuração adicional:

✅ Autenticação Azure CLI: Sempre requer configuração de autorização
✅ Service principal externo: Requer configuração de autorização
❌ Service principal do próprio aplicativo OSDU: Nenhuma configuração adicional necessária

Para Azure CLI ou Service Principal Externo:

Navegue até seu aplicativo OSDU em Registros de aplicativo
Vá para Expor uma API → Aplicativos cliente autorizados
Clique em Adicionar um aplicativo cliente
Insira o ID do cliente:
- Azure CLI: 04b07795-8ddb-461a-bbee-02f9e1bf7b46
- Service Principal Externo: O ID do seu service principal
Selecione o escopo user_impersonation
Clique em Adicionar

Verifique a autenticação:

az account get-access-token --resource YOUR_AZURE_CLIENT_ID

Problemas Comuns:

"Aplicativo não encontrado": O aplicativo Azure CLI não existe em alguns locatários. Use service principal em vez disso.
"Recurso inválido": O cliente não foi autorizado. Siga a configuração de autorização acima.
"Falha na autenticação": Verifique se o ID do seu cliente corresponde ao seu aplicativo OSDU ou service principal.

Operações de Escrita

As operações de escrita (criar, atualizar) para qualquer serviço estão desabilitadas por padrão; você deve habilitá-las explicitamente:

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

Operações de Exclusão

As operações de exclusão e purga são controladas separadamente e desabilitadas por padrão:

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

Essa dupla proteção permite que você habilite a criação e atualização de dados enquanto mantém controle rigoroso sobre operações destrutivas.

Exemplo Completo de Configuração

Aqui está um exemplo completo de configuração .mcp.json com todas as variáveis de ambiente comuns:

{
  "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"
      }
    }
  }
}

Configuração de Logging

O servidor MCP usa logging JSON estruturado que segue ADR-016. Por padrão, o logging está desabilitado devido à verbosidade. Você pode habilitá-lo definindo:

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

Níveis de logging válidos: DEBUG, INFO, WARNING, ERROR, CRITICAL

Uso

Verificação de Saúde

osdu:health_check

Isso retorna o status de saúde da sua plataforma OSDU, verificando a autenticação e a disponibilidade de todos os serviços (storage, search, legal, schema, file, workflow, entitlements e dataset).

Capacidades Disponíveis

Prompts

list_mcp_assets: Visão geral abrangente de todas as capacidades do servidor com exemplos de uso e guia de início rápido
guide_search_patterns: Orientação sobre padrões de busca para operações OSDU com exemplos de sintaxe Elasticsearch

Ferramentas

Fundação

health_check: Verifica a conectividade da plataforma OSDU e a saúde dos serviços

Serviço de Partição

partition_list: Lista todas as partições OSDU acessíveis
partition_get: Recupera a configuração de uma partição específica
partition_create: Cria uma nova partição (protegida contra escrita)
partition_update: Atualiza propriedades da partição (protegida contra escrita)
partition_delete: Exclui uma partição (protegida contra escrita)

Serviço de Entitlements

entitlements_mine: Obtém grupos para o usuário autenticado atual

Serviço Legal

legaltag_list: Lista todas as tags legais
legaltag_get: Obtém uma tag legal específica
legaltag_get_properties: Obtém valores de propriedade permitidos
legaltag_search: Busca tags legais com filtros
legaltag_batch_retrieve: Obtém várias tags de uma vez
legaltag_create: Cria nova tag legal (protegida contra escrita)
legaltag_update: Atualiza tag legal (protegida contra escrita)
legaltag_delete: Exclui tag legal (protegida contra exclusão)

Serviço de Esquema

schema_list: Lista esquemas disponíveis com filtragem opcional
schema_get: Recupera esquema completo por ID
schema_search: Descoberta avançada de esquemas com filtragem rica e busca por texto
schema_create: Cria um novo esquema (protegido contra escrita)
schema_update: Atualiza um esquema existente (protegido contra escrita)

Serviço de Busca

search_query: Executa consultas de busca usando sintaxe Elasticsearch
search_by_id: Encontra registros específicos por ID
search_by_kind: Encontra todos os registros de um tipo específico

Serviço de Storage

storage_create_update_records: Cria ou atualiza registros (protegido contra escrita)
storage_get_record: Obtém a versão mais recente de um registro por ID
storage_get_record_version: Obtém uma versão específica de um registro
storage_list_record_versions: Lista todas as versões de um registro
storage_query_records_by_kind: Obtém IDs de registros de um tipo específico
storage_fetch_records: Recupera vários registros de uma vez
storage_delete_record: Exclui logicamente um registro (protegido contra exclusão)
storage_purge_record: Exclui permanentemente um registro (protegido contra exclusão)