SAP OData MCP Server

Um servidor MCP para integração com serviços SAP OData, configurado por meio de variáveis de ambiente.

GitHub
12
Experimente este MCPPatrocinado

Documentação

SAP OData MCP Server

Um servidor Model Context Protocol (MCP) para integrar sistemas SAP com assistentes de IA como Claude usando APIs REST OData. Este servidor fornece ferramentas para conectar-se a serviços OData SAP, consultar conjuntos de entidades, executar operações CRUD e chamar funções OData.

Recursos

  • Conectividade SAP OData: Conecte-se a sistemas SAP via APIs REST OData
  • Tratamento Inteligente de Conexão: Gerencia corretamente estruturas de URL OData SAP e respostas 404
  • Descoberta de Serviços: Descubra automaticamente serviços OData disponíveis via catálogo ou teste de serviços comuns
  • Consultas de Conjuntos de Entidades: Consulte qualquer conjunto de entidades OData com filtragem, ordenação e paginação
  • Operações CRUD: Operações de Criar, Ler, Atualizar e Excluir em entidades OData
  • Importações de Funções: Execute importações de funções OData e funções personalizadas
  • Tratamento de Token CSRF: Gerenciamento automático de token CSRF para operações seguras
  • Arquitetura Modular: Código TypeScript limpo e sustentável com separação de responsabilidades

Pré-requisitos

  • Node.js 18+
  • Sistema SAP com serviços OData habilitados
  • Acesso de rede aos endpoints OData SAP
  • Credenciais de usuário SAP com autorizações apropriadas

⚠️ Vantagem: Não é necessária instalação do SDK RFC SAP! Usa APIs HTTP/REST padrão.

Instalação

Configuração Rápida

  1. Crie o projeto:
mkdir sap-odata-mcp-server
cd sap-odata-mcp-server
mkdir src

  1. Copie os arquivos de origem dos artefatos para o diretório src/:

    • src/index.ts - Ponto de entrada
    • src/server.ts - Configuração do servidor MCP
    • src/handlers.ts - Manipuladores de requisições
    • src/odata-client.ts - Cliente SAP OData
    • src/tool-definitions.ts - Definições de ferramentas
    • src/types.ts - Tipos TypeScript

  2. Copie os arquivos de configuração:

    • package.json - Dependências e scripts
    • tsconfig.json - Configuração TypeScript
    • .env.example - Modelo de variáveis de ambiente

  3. Instale as dependências:

npm install
  1. Configure o ambiente:
cp .env.example .env
# Edit .env with your SAP details
  1. Compile o projeto:
npm run build

Configuração

Variáveis de Ambiente

Crie um arquivo .env com os detalhes do seu sistema SAP:

# Required SAP OData Configuration
SAP_ODATA_BASE_URL=https://your-sap-host:8000/sap/opu/odata/sap/
SAP_USERNAME=your-sap-username
SAP_PASSWORD=your-sap-password

# Optional Configuration
SAP_CLIENT=100
SAP_TIMEOUT=30000
SAP_VALIDATE_SSL=false  # for development with self-signed certificates
SAP_ENABLE_CSRF=true

Integração com Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sap-odata": {
      "command": "node",
      "args": ["/full/path/to/your/sap-odata-mcp-server/dist/index.js"],
      "env": {
        "SAP_ODATA_BASE_URL": "https://your-sap-host:8000/sap/opu/odata/sap/",
        "SAP_USERNAME": "your-username",
        "SAP_PASSWORD": "your-password",
        "SAP_CLIENT": "100",
        "SAP_VALIDATE_SSL": "false"
      }
    }
  }
}

Ferramentas Disponíveis

1. sap_connect

Conecte-se ao serviço OData SAP.

Parâmetros:

  • baseUrl (obrigatório): URL base do serviço OData SAP
  • username (obrigatório): Nome de usuário SAP
  • password (obrigatório): Senha SAP
  • client (opcional): Número do cliente SAP
  • timeout (opcional): Tempo limite de requisição em milissegundos (padrão: 30000)
  • validateSSL (opcional): Validar certificados SSL (padrão: true)
  • enableCSRF (opcional): Habilitar tratamento de token CSRF (padrão: true)

2. sap_get_services

Obtenha a lista de serviços OData disponíveis com descoberta inteligente.

3. sap_get_service_metadata

Obtenha metadados para um serviço OData específico.

Parâmetros:

  • serviceName (obrigatório): Nome do serviço OData

4. sap_query_entity_set

Consulte um conjunto de entidades OData com filtragem, ordenação e paginação.

Parâmetros:

  • serviceName (obrigatório): Nome do serviço OData
  • entitySet (obrigatório): Nome do conjunto de entidades
  • select (opcional): Matriz de campos para selecionar
  • filter (opcional): Expressão de filtro OData
  • orderby (opcional): Expressão de ordenação OData
  • top (opcional): Número de registros para retornar
  • skip (opcional): Número de registros para pular
  • expand (opcional): Propriedades de navegação para expandir

5. sap_get_entity

Obtenha uma entidade específica pelos seus valores de chave.

Parâmetros:

  • serviceName (obrigatório): Nome do serviço OData
  • entitySet (obrigatório): Nome do conjunto de entidades
  • keyValues (obrigatório): Objeto com pares chave-valor para chaves de entidade

6. sap_create_entity

Crie uma nova entidade em um conjunto de entidades.

7. sap_update_entity

Atualize uma entidade existente.

8. sap_delete_entity

Exclua uma entidade.

9. sap_call_function

Chame uma importação de função OData.

10. sap_connection_status

Verifique o status atual da conexão SAP OData.

11. sap_disconnect

Desconecte-se do serviço OData SAP.

Exemplos de Uso

Começando com Claude

Uma vez configurado, você pode interagir com SAP usando linguagem natural no Claude:

Conectar ao SAP:

Connect to SAP OData service at https://sap-host:8000/sap/opu/odata/sap/ using username DEVELOPER and password mypassword

Descobrir Serviços Disponíveis:

Get list of available OData services

Obter Informações do Serviço:

Get metadata for service GWSAMPLE_BASIC

Consultar Dados:

Query BusinessPartnerSet from GWSAMPLE_BASIC, select BusinessPartnerID and CompanyName, top 10

Filtragem Avançada:

Query SalesOrderSet from ZSD_SALES_SRV, filter by CreationDate ge datetime'2024-01-01T00:00:00', order by CreationDate desc, top 20

Obter Registros Específicos:

Get entity from MaterialSet in ZMM_MATERIAL_SRV with key Material = '000000000000000001'

Criar Novos Registros:

Create entity in CustomerSet with data: {"CustomerNumber": "1000", "CustomerName": "Test Customer", "Country": "US"}

Exemplos de Consultas OData

Filtragem:

$filter=MaterialType eq 'FERT' and CreationDate ge datetime'2024-01-01T00:00:00'

Selecionando Campos:

$select=Material,MaterialDescription,MaterialType,BaseUnit

Ordenação:

$orderby=CreationDate desc,Material asc

Paginação:

$top=50&$skip=100

Expandindo Propriedades de Navegação:

$expand=MaterialPlantData,MaterialSalesData

Requisitos do Sistema SAP

Componentes SAP Necessários

  • SAP NetWeaver 7.0 ou superior
  • Componente SAP Gateway ativado
  • Serviços OData habilitados e configurados

Autorizações SAP Necessárias

O usuário SAP precisa destes objetos de autorização:

  • S_SERVICE: Autorização de serviço para endpoints OData
  • S_ICF: Autorização do Internet Communication Framework
  • S_TCODE: Autorização de transação para BAPIs (se usar importações de funções)

Ativando Serviços OData

  1. Transação SICF: Ative serviços ICF em /sap/opu/odata
  2. Transação /IWFND/MAINT_SERVICE: Gerencie e ative serviços OData
  3. Transação /IWFND/GW_CLIENT: Teste chamadas de serviço OData

Arquitetura

Design Modular

src/
├── index.ts              # Entry point - starts the server
├── server.ts             # MCP server setup and request routing
├── handlers.ts           # Business logic for each tool
├── odata-client.ts       # SAP OData HTTP client
├── tool-definitions.ts   # MCP tool schemas
└── types.ts              # TypeScript type definitions

Recursos Principais

  • Teste Inteligente de Conexão: Gerencia a estrutura de URL do SAP onde URLs base retornam 404
  • Descoberta de Serviços: Múltiplos métodos para encontrar serviços OData disponíveis
  • Tratamento de Erros: Tratamento abrangente de erros com mensagens úteis
  • Segurança de Tipos: Suporte completo a TypeScript com interfaces adequadas
  • Proteção CSRF: Gerenciamento automático de token CSRF para operações de escrita

Solução de Problemas

Problemas Comuns

Conexão Recusada (Erro de Rede)

  • Verifique se o sistema SAP está em execução e acessível
  • Verifique hostname/porta em SAP_ODATA_BASE_URL
  • Verifique se as configurações de firewall permitem tráfego HTTP/HTTPS

401 Não Autorizado

  • Verifique SAP_USERNAME e SAP_PASSWORD
  • Verifique se a conta do usuário não está bloqueada
  • Garanta que o usuário tenha autorização S_SERVICE

403 Proibido

  • Verifique se o usuário tem as autorizações SAP necessárias
  • Verifique a autorização S_ICF para caminhos OData
  • Contate o administrador SAP para revisão de permissões

404 Não Encontrado

  • Isso é normal para URLs base OData SAP sem nomes de serviço
  • Verifique se os serviços OData estão ativados (transação SICF)
  • Use a descoberta de serviços para encontrar serviços disponíveis

Erros de Certificado SSL

  • Defina SAP_VALIDATE_SSL=false para desenvolvimento
  • Instale certificados adequados para produção
  • Verifique a cadeia de certificados e expiração

Modo de Depuração

Habilite o registro detalhado:

DEBUG=axios npm start

Verificação do Sistema SAP

  1. Teste a URL OData no navegador: Navegue até sua URL OData SAP
  2. Verifique a ativação do serviço: Transação SICF → /sap/opu/odata
  3. Verifique os serviços de gateway: Transação /IWFND/MAINT_SERVICE
  4. Teste com o cliente de gateway: Transação /IWFND/GW_CLIENT

Melhores Práticas de Segurança

Implantação em Produção

  • Use HTTPS para todas as conexões OData SAP
  • Armazene credenciais com segurança - nunca codifique senhas
  • Crie usuários de serviço dedicados com permissões mínimas necessárias
  • Habilite proteção CSRF para operações de escrita
  • Implemente autorização adequada no SAP para serviços OData
  • Monitore logs de acesso e configure alertas
  • Auditorias regulares de segurança das permissões de usuário

Segurança de Rede

  • Use VPN ou redes privadas para acesso SAP
  • Implemente restrições de IP quando possível
  • Habilite recursos de segurança do SAP Gateway
  • Use gerenciamento adequado de certificados

Serviços OData SAP Comuns

Serviços SAP Padrão

  • GWSAMPLE_BASIC - Serviço de amostra básico para testes
  • GWDEMO - Serviço de demonstração abrangente
  • RMTSAMPLEFLIGHT - Demonstração de reserva de voos

Serviços de Negócios

  • API_MATERIAL_SRV - Gestão de Materiais
  • API_BUSINESS_PARTNER - Gestão de Parceiros de Negócios
  • API_SALES_ORDER_SRV - Gestão de Pedidos de Venda
  • API_PURCHASEORDER_PROCESS_SRV - Processamento de Pedidos de Compra

Conjuntos de Entidades por Módulo

  • MM (Gestão de Materiais): MaterialSet, MaterialPlantDataSet
  • SD (Vendas e Distribuição): SalesOrderSet, CustomerSet, PricingConditionSet
  • FI (Contabilidade Financeira): GeneralLedgerEntrySet, AccountingDocumentSet
  • HR (Recursos Humanos): EmployeeSet, OrganizationalUnitSet

Desenvolvimento

Scripts Disponíveis

# Build TypeScript
npm run build

# Start production server
npm start

# Development mode with auto-reload
npm run dev

# Code quality
npm run lint
npm run format

Adicionando Novos Recursos

  1. Adicione a definição da ferramenta em tool-definitions.ts
  2. Implemente o manipulador em handlers.ts
  3. Adicione a rota na instrução switch de server.ts
  4. Atualize os tipos em types.ts se necessário
  5. Compile e teste

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso
  3. Faça suas alterações com tipos TypeScript adequados
  4. Teste com um sistema SAP real
  5. Envie um pull request

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.