OData MCP Bridge (Go)

Uma ponte Go que fornece acesso universal a serviços OData v2 por meio de ferramentas MCP, com suporte para múltiplos métodos de autenticação.

GitHub

142

Experimente este MCPPatrocinado

Documentação

OData MCP Bridge (Go)

Uma implementação em Go da ponte OData para Model Context Protocol (MCP), fornecendo acesso universal a serviços OData por meio de ferramentas MCP.

Esta é uma versão em Go da implementação da ponte OData-MCP em Python, projetada para ser mais fácil de executar em diferentes sistemas operacionais, com melhor desempenho e implantação mais simples. Ela suporta serviços OData v2 e v4.

🆕 Novidades (v1.6.0)

Modo de Ferramenta Universal — Uma Ferramenta para Governar Todas

A maior novidade é o Modo de Ferramenta Universal (--universal), um divisor de águas para grandes serviços OData:

# Before: 485 tools, ~37,000 tokens, Claude says "no API available"
./odata-mcp https://large-sap-service.com/odata/

# After: 1 tool, ~900 tokens, works perfectly
./odata-mcp --universal https://large-sap-service.com/odata/

Métrica	Modo Padrão	Modo Universal	Redução
Ferramentas (Northwind)	157	1	99.4%
Ferramentas (SAP BP)	485	1	99.8%
Uso de tokens	~37,000	~900	97.6%

Por que é opcional? O modo universal muda a forma como você interage com o OData:

Modo padrão: Cada entidade recebe ferramentas dedicadas (filter_Products, get_Orders, etc.)
Modo universal: Uma ferramenta odata com action, target e params

Nós o tornamos opcional porque:

Compatibilidade reversa — configurações e fluxos de trabalho existentes continuam funcionando
Descoberta — ferramentas por entidade são autodocumentadas; LLMs podem ver exatamente o que está disponível
Simplicidade para serviços pequenos — se você tem 20 ferramentas, o modo por entidade funciona muito bem
Escolha explícita — os usuários devem escolher conscientemente o trade-off

Quando usar --universal:

O serviço tem 50+ conjuntos de entidades
Executando vários serviços OData simultaneamente
Enfrentando erros de "nenhuma API disponível" ou falhas na seleção de ferramentas
Quer um consumo mínimo de tokens

Veja Arquitetura de Ferramenta Universal para a história completa.

Encaminhamento de Cabeçalhos MCP

A nova flag --forward-mcp-headers permite passar cabeçalhos HTTP de clientes MCP para serviços OData:

./odata-mcp --transport streamable-http --forward-mcp-headers https://secured-service.com/odata/

Isso permite:

Autenticação dinâmica — passe credenciais por solicitação em vez de na inicialização
Cenários multi-tenant — diferentes usuários com diferentes tokens
Cabeçalhos personalizados — cabeçalhos X-* fluem para o OData

Maratona de Correções de Problemas

Esta versão corrige 10 problemas em aberto:

Issue	Problema	Correção
#12	OData SAP não mostra ferramentas	Correção no parsing de namespace XML (`sap:creatable` etc.)
#13	`--max-items 99999` trava	Validação adicionada (máx. 10,000)
#14	Vários serviços = Claude travado	Modo de ferramenta universal
#16	Formatação GUID incorreta	Detecção automática de SAP, adicionar prefixo `guid'...'`
#17	Timeout em vez de erro	Resposta de erro imediata
#18	Busca com curinga falha	Analisar anotação `SearchRestrictions`
#19	Timeout esconde erro do SAP	Retornar mensagem de erro real
#22	BaseType não exposto	Adicionado ao modelo EntityType
#23	Tratamento de cabeçalhos	Flag `--forward-mcp-headers`
#25	Build do Windows sem .exe	Makefile corrigido para Windows

Versões Anteriores

Compatibilidade com AI Foundry (v1.5.1): flag --protocol-version para o protocolo 2025-06-18 do AI Foundry
Filtragem de GUID SAP (v1.5.0): Formatação automática de guid'...' para serviços SAP
Transporte HTTP Streamable (v1.5.0): Protocolo MCP moderno com --transport streamable-http

Recursos

Suporte Universal a OData: Funciona com serviços OData v2 e v4
Geração Dinâmica de Ferramentas: Cria automaticamente ferramentas MCP com base nos metadados OData
Múltiplos Métodos de Autenticação: Autenticação básica, autenticação por cookie e acesso anônimo
Extensões SAP OData: Suporte completo para recursos OData específicos da SAP, incluindo tokens CSRF
Operações CRUD Abrangentes: Ferramentas geradas para operações de criar, ler, atualizar e excluir
Suporte Avançado a Consultas: Opções de consulta OData ($filter, $select, $expand, $orderby, etc.)
Suporte a Importação de Funções: Chame importações de funções OData como ferramentas MCP
Nomenclatura Flexível de Ferramentas: Nomenclatura configurável com opções de prefixo/sufixo
Filtragem de Entidades: Geração seletiva de ferramentas com suporte a curingas
Multiplataforma: Binário Go nativo para implantação fácil em qualquer SO
Modos Somente Leitura: Restrinja operações com --read-only ou --read-only-but-functions
Depuração do Protocolo MCP: Registro de rastreamento integrado com --trace-mcp para solução de problemas
Dicas Específicas de Serviço: Sistema flexível de dicas com correspondência de padrões para problemas conhecidos de serviços
Conformidade Total com MCP: Implementação completa do protocolo para todos os clientes MCP
Múltiplos Transportes: Suporte para stdio (padrão), HTTP/SSE e HTTP Streamable
Compatível com AI Foundry: Versão de protocolo configurável para AI Foundry e outros clientes MCP

Instalação

Baixar Binário

Baixe o binário apropriado para sua plataforma na página de releases.

Binários pré-compilados estão disponíveis para:

Linux (amd64)
Windows (amd64)
macOS (Intel e Apple Silicon)

Compilar a partir do Código Fonte

Compilação Rápida (requer Go)

git clone https://github.com/oisee/odata_mcp_go.git
cd odata_mcp_go
go build -o odata-mcp cmd/odata-mcp/main.go

Usando Makefile (Recomendado)

# Build for current platform
make build

# Build for all platforms
make build-all

# Build for all platforms with WSL integration (copies to /mnt/c/bin)
make build-all-wsl

# Build and test
make dev

# Check current version
make version

# See all options
make help

Usando Script de Build

# Build for current platform
./build.sh

# Build for all platforms
./build.sh all

# See all options
./build.sh help

Exemplos de Compilação Cruzada

# Using Make
make build-linux     # Linux (amd64)
make build-windows   # Windows (amd64)
make build-macos     # macOS (Intel + Apple Silicon)

# WSL-specific builds (copies Windows binary to /mnt/c/bin)
make build-windows-wsl  # Build Windows + WSL integration
make build-all-wsl      # Build all platforms + WSL integration

# Using build script
./build.sh linux     # Linux (amd64)
./build.sh windows   # Windows (amd64)
./build.sh macos     # macOS (Intel + Apple Silicon)

# Manual Go build
GOOS=linux GOARCH=amd64 go build -o odata-mcp-linux cmd/odata-mcp/main.go
GOOS=windows GOARCH=amd64 go build -o odata-mcp.exe cmd/odata-mcp/main.go

Build com Docker

# Build Docker image
make docker

# Or manually
docker build -t odata-mcp .

# Run in container
docker run --rm -it odata-mcp --help

Compilando no WSL (Subsistema Windows para Linux)

Ao compilar no WSL, você pode usar alvos especiais que copiam automaticamente o binário do Windows para o seu sistema de arquivos do Windows:

# Build all platforms and copy Windows binary to C:\bin
make build-all-wsl

# Build only Windows and copy to C:\bin
make build-windows-wsl

Nota: Esses comandos verificarão se /mnt/c/bin existe e pularão a cópia se não for encontrado, portanto, são seguros para usar em qualquer sistema.

Uso

Configuração do Claude Desktop

O Claude Desktop usa o transporte stdio por padrão. Aqui estão exemplos de configuração:

Encontrando Seu Arquivo de Configuração

A localização do arquivo de configuração do Claude Desktop varia por plataforma:

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

Configuração Básica

{
    "mcpServers": {
        "northwind-v2": {
            "command": "C:/bin/odata-mcp.exe",
            "args": [
                "--service",
                "https://services.odata.org/V2/Northwind/Northwind.svc/",
                "--tool-shrink"
            ]
        },
        "northwind-v4": {
            "command": "C:/bin/odata-mcp.exe",
            "args": [
                "--service",
                "https://services.odata.org/V4/Northwind/Northwind.svc/",
                "--tool-shrink"
            ]
        }
    }
}

Com Autenticação

{
    "mcpServers": {
        "my-sap-service": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service",
                "https://my-sap-system.com/sap/opu/odata/sap/MY_SERVICE/",
                "--user",
                "myusername",
                "--password",
                "mypassword",
                "--tool-shrink",
                "--entities",
                "Products,Orders,Customers"
            ]
        }
    }
}

Usando Variáveis de Ambiente (Mais Seguro)

{
    "mcpServers": {
        "my-secure-service": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service",
                "https://my-service.com/odata/",
                "--tool-shrink"
            ],
            "env": {
                "ODATA_USERNAME": "myusername",
                "ODATA_PASSWORD": "mypassword"
            }
        }
    }
}

Nota: O Claude Desktop atualmente não suporta a leitura de variáveis de ambiente do seu sistema. O campo env na configuração define variáveis de ambiente especificamente para o processo do servidor MCP.

Melhores Práticas de Segurança para o Claude Desktop

Use variáveis de ambiente no campo env em vez de codificar credenciais em args
Limite o acesso a entidades usando a flag --entities para expor apenas os dados necessários
Use contas somente leitura quando possível para serviços OData
Armazene o arquivo de configuração com segurança com permissões de arquivo apropriadas

Nota: O Claude Desktop atualmente não suporta autenticação por chave de API para servidores MCP. Todos os servidores MCP são executados localmente com as mesmas permissões do próprio Claude Desktop.

Exemplos de Configuração Somente Leitura

{
    "mcpServers": {
        "production-readonly": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service",
                "https://production.company.com/odata/",
                "--read-only",
                "--tool-shrink"
            ],
            "env": {
                "ODATA_USERNAME": "readonly_user",
                "ODATA_PASSWORD": "readonly_pass"
            }
        },
        "dev-with-functions": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service", 
                "https://dev.company.com/odata/",
                "--read-only-but-functions",
                "--trace-mcp"  // Enable debugging
            ]
        }
    }
}

Compatibilidade com Claude Code CLI

O Claude Code CLI tem validação de nomes de propriedades mais rigorosa do que outras ferramentas Claude. Se você encontrar erros como:

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"tools.17.custom.input_schema.properties: Property keys should match pattern ^[a-zA-Z0-9_.-]{1,64}$"}}

Use a flag --claude-code-friendly para remover o prefixo $ dos nomes de parâmetros OData:

{
    "mcpServers": {
        "northwind-claude-code": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service",
                "https://services.odata.org/V2/Northwind/Northwind.svc/",
                "--claude-code-friendly",  // Removes $ from parameter names
                "--tool-shrink"
            ]
        }
    }
}

Isso transforma os nomes de parâmetros:

$filter → filter
$select → select
$expand → expand
$orderby → orderby
$top → top
$skip → skip
$count → count

O servidor mapeia internamente esses nomes amigáveis de volta para seus equivalentes OData ao fazer solicitações.

Exemplos de Configuração de Filtragem de Operações

{
    "mcpServers": {
        "large-service-readonly": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service",
                "https://large-erp.company.com/odata/",
                "--disable", "cud",  // Disable create, update, delete
                "--tool-shrink",
                "--entities", "Orders,Products,Customers"
            ],
            "env": {
                "ODATA_USERNAME": "readonly_user",
                "ODATA_PASSWORD": "readonly_pass"
            }
        },
        "minimal-tools": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service",
                "https://api.company.com/odata/",
                "--enable", "gf",  // Only get and filter operations
                "--tool-shrink"
            ]
        },
        "no-actions": {
            "command": "/usr/local/bin/odata-mcp", 
            "args": [
                "--service",
                "https://api.company.com/odata/",
                "--disable", "a",  // Disable all function imports/actions
                "--verbose"
            ]
        }
    }
}

### AI Foundry Configuration

For AI Foundry integration, use the `--protocol-version` flag to specify the `2025-06-18` protocol:

```json
{
    "mcpServers": {
        "odata-for-ai-foundry": {
            "command": "/usr/local/bin/odata-mcp",
            "args": [
                "--service",
                "https://your-odata-service.com/",
                "--protocol-version", "2025-06-18",
                "--user", "your-username",
                "--password", "your-password"
            ]
        }
    }
}

Ou via linha de comando:

./odata-mcp --service https://your-service.com/odata --protocol-version "2025-06-18"

Veja o Guia de Compatibilidade com AI Foundry para instruções detalhadas de configuração.

Opções de Transporte

A ponte OData MCP suporta dois mecanismos de transporte:

STDIO (padrão) - Comunicação padrão de entrada/saída, usada pelo Claude Desktop
HTTP/SSE - Servidor HTTP com Server-Sent Events para clientes baseados na web

🔒 MODELO DE SEGURANÇA: O transporte HTTP usa um modelo de segurança rigoroso.

Requisitos de Segurança:

Localhost: Token obrigatório (--mcp-token)

Não-localhost: Token + TLS obrigatórios, sem exceções

Todas as interfaces (0.0.0.0/::): Requer --allow-all-interfaces + token + TLS

O token pode ser qualquer string - para desenvolvimento, --mcp-token dev funciona bem.

Usando Transporte HTTP Streamable (Protocolo MCP Moderno)

Novo na v1.5.0: Suporte para transporte HTTP Streamable (versão do protocolo 2024-11-05)

# Start server with Streamable HTTP (recommended for modern clients)
./odata-mcp --transport streamable-http https://services.odata.org/V2/Northwind/Northwind.svc/

# Use custom localhost port
./odata-mcp --transport streamable-http --http-addr localhost:3000 https://services.odata.org/V2/Northwind/Northwind.svc/

Endpoints HTTP Streamable:

POST /mcp - Endpoint MCP principal (suporta upgrade automático para SSE)
GET /health - Endpoint de verificação de saúde
POST /sse - Endpoint SSE legado (para compatibilidade reversa)

Usando Transporte HTTP/SSE (Legado)

# Start server on localhost (default: localhost:8080)
./odata-mcp --transport http --mcp-token "dev" https://services.odata.org/V2/Northwind/Northwind.svc/

# Use custom localhost port
./odata-mcp --transport http --http-addr localhost:3000 --mcp-token "dev" https://services.odata.org/V2/Northwind/Northwind.svc/

# Non-localhost requires token + TLS
./odata-mcp --transport http --http-addr 192.168.1.100:8080 \
  --mcp-token "my-secret-token" --tls --tls-cert cert.pem --tls-key key.pem \
  https://services.odata.org/V2/Northwind/Northwind.svc/

# All interfaces requires explicit flag + token + TLS
./odata-mcp --transport http --http-addr 0.0.0.0:8080 \
  --allow-all-interfaces --mcp-token "my-secret-token" \
  --tls --tls-cert cert.pem --tls-key key.pem \
  https://services.odata.org/V2/Northwind/Northwind.svc/

Endpoints HTTP/SSE legados:

GET /health - Endpoint de verificação de saúde
GET /sse - Endpoint de Server-Sent Events para comunicação em tempo real
POST /rpc - Endpoint JSON-RPC para comunicação de solicitação/resposta

Testando o Transporte HTTP/SSE

Usando o cliente HTML fornecido:

# Start the server
./odata-mcp --transport http https://services.odata.org/V2/Northwind/Northwind.svc/

# Open examples/sse_client.html in a web browser

Usando curl:

# Test SSE endpoint
curl -N -H 'Accept: text/event-stream' http://localhost:8080/sse

# Test RPC endpoint
curl -X POST http://localhost:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

Usando os scripts de teste:

# Test SSE with interactive script
./test_sse.sh

# Test HTTP/RPC communication
./test_http_rpc.sh

Uso Básico

# Using positional argument
./odata-mcp https://services.odata.org/V2/Northwind/Northwind.svc/

# Using --service flag
./odata-mcp --service https://services.odata.org/V2/Northwind/Northwind.svc/

# Using environment variable
export ODATA_SERVICE_URL=https://services.odata.org/V2/Northwind/Northwind.svc/
./odata-mcp

Autenticação

# Basic authentication
./odata-mcp --user admin --password secret https://my-service.com/odata/

# Cookie file authentication
./odata-mcp --cookie-file cookies.txt https://my-service.com/odata/

# Cookie string authentication  
./odata-mcp --cookie-string "session=abc123; token=xyz789" https://my-service.com/odata/

# Environment variables
export ODATA_USERNAME=admin
export ODATA_PASSWORD=secret
./odata-mcp https://my-service.com/odata/

Opções de Nomenclatura de Ferramentas

# Use custom prefix instead of postfix
./odata-mcp --no-postfix --tool-prefix "myservice" https://my-service.com/odata/

# Use custom postfix
./odata-mcp --tool-postfix "northwind" https://my-service.com/odata/

# Use shortened tool names
./odata-mcp --tool-shrink https://my-service.com/odata/

Filtragem de Entidades e Funções

# Filter to specific entities (supports wildcards)
./odata-mcp --entities "Products,Categories,Order*" https://my-service.com/odata/

# Filter to specific functions (supports wildcards)  
./odata-mcp --functions "Get*,Create*" https://my-service.com/odata/

Modos Somente Leitura

# Hide all modifying operations (create, update, delete, and functions)
./odata-mcp --read-only https://my-service.com/odata/
./odata-mcp -ro https://my-service.com/odata/  # Short form

# Hide create/update/delete but allow function imports
./odata-mcp --read-only-but-functions https://my-service.com/odata/
./odata-mcp -robf https://my-service.com/odata/  # Short form

Filtragem por Tipo de Operação

Controle granular sobre quais tipos de operação estão disponíveis. Os tipos de operação são:

C - Operações de criação
S - Operações de busca
F - Operações de filtro/lista
G - Operações de obtenção (entidade única)
U - Operações de atualização
D - Operações de exclusão
A - Ações/importações de funções
R - Operações de leitura (expande para S, F, G)

# Enable only read operations (search, filter, get)
./odata-mcp --enable "r" https://my-service.com/odata/
./odata-mcp --enable "sfg" https://my-service.com/odata/  # Same as above

# Disable all modifying operations
./odata-mcp --disable "cud" https://my-service.com/odata/

# Enable only get and filter operations
./odata-mcp --enable "gf" https://my-service.com/odata/

# Disable actions/function imports
./odata-mcp --disable "a" https://my-service.com/odata/

# Case-insensitive
./odata-mcp --disable "CUD" https://my-service.com/odata/

Nota: --enable e --disable não podem ser usados juntos.

Modo de Ferramenta Universal

Para grandes serviços OData com muitas entidades, a geração padrão de ferramentas por entidade pode criar centenas de ferramentas, causando:

Deterioração do contexto: LLMs têm dificuldade de raciocinar quando o número de ferramentas excede ~128
Alto uso de tokens: Esquemas de ferramentas podem consumir de 15.000 a 40.000 tokens
Falhas na seleção de ferramentas: LLMs podem relatar "nenhuma API disponível"

O modo universal resolve isso gerando uma única ferramenta que lida com todas as operações:

# Enable universal tool mode
./odata-mcp --universal https://my-service.com/odata/

# Compare tool counts
./odata-mcp --trace https://my-service.com/odata/           # Standard: many tools
./odata-mcp --universal --trace https://my-service.com/odata/  # Universal: 1 tool

Quando usar o modo universal:

O serviço tem mais de ~50 conjuntos de entidades
Usando vários serviços OData simultaneamente
Enfrentando erros de "nenhuma API disponível" com serviços grandes

Uso da ferramenta universal:

{"action": "list", "target": "Products", "params": {"filter": "Price gt 100", "top": 10}}
{"action": "get", "target": "Products", "params": {"key": {"ProductID": 1}}}
{"action": "create", "target": "Orders", "params": {"data": {"CustomerID": "C001"}}}
{"action": "call", "target": "ReleaseOrder", "params": {"OrderID": "O001"}}

Depuração e Inspeção

# Enable verbose output
./odata-mcp --verbose https://my-service.com/odata/

# Trace mode - show all tools without starting server
./odata-mcp --trace https://my-service.com/odata/

# Enable MCP protocol trace logging (saves to temp directory)
./odata-mcp --trace-mcp https://my-service.com/odata/
# Linux/WSL: /tmp/mcp_trace_*.log
# Windows: %TEMP%\mcp_trace_*.log

Dicas de Serviço

A ponte OData MCP inclui um sistema flexível de dicas para fornecer orientação para serviços com problemas conhecidos ou requisitos especiais:

# Use default hints.json from binary directory
./odata-mcp https://my-service.com/odata/

# Use custom hints file
./odata-mcp --hints-file /path/to/custom-hints.json https://my-service.com/odata/

# Inject hint directly from command line
./odata-mcp --hint "Remember to use \$expand for complex queries" https://my-service.com/odata/

# Combine file and CLI hints (CLI has higher priority)
./odata-mcp --hints-file custom.json --hint '{"notes":["Override note"]}' https://my-service.com/odata/

Configuração

Flags de Linha de Comando

Flag	Descrição	Padrão
`--service`	URL do serviço OData
`-u, --user`	Nome de usuário para autenticação básica
`-p, --password`	Senha para autenticação básica
`--cookie-file`	Caminho para o arquivo de cookies (formato Netscape)
`--cookie-string`	String de cookie (key1=val1; key2=val2)
`--tool-prefix`	Prefixo personalizado para nomes de ferramentas
`--tool-postfix`	Sufixo personalizado para nomes de ferramentas
`--no-postfix`	Usar prefixo em vez de sufixo	`false`
`--tool-shrink`	Usar nomes de ferramentas abreviados	`false`
`--entities`	Filtro de entidades separado por vírgulas (suporta curingas)
`--functions`	Filtro de funções separado por vírgulas (suporta curingas)
`--sort-tools`	Ordenar ferramentas alfabeticamente	`true`
`-v, --verbose`	Habilitar saída detalhada	`false`
`--debug`	Alias para --verbose	`false`
`--trace`	Mostrar ferramentas e sair (modo de depuração)	`false`
`--trace-mcp`	Habilitar registro de rastreamento do protocolo MCP	`false`
`--read-only, -ro`	Ocultar todas as operações de modificação	`false`
`--read-only-but-functions, -robf`	Ocultar criar/atualizar/excluir, mas permitir funções	`false`
`--enable`	Habilitar apenas os tipos de operação especificados (C,S,F,G,U,D,A,R)
`--disable`	Desabilitar os tipos de operação especificados (C,S,F,G,U,D,A,R)
`--hints-file`	Caminho para o arquivo JSON de dicas	`hints.json` no diretório do binário
`--hint`	JSON de dica direto ou texto da CLI
`--transport`	Tipo de transporte: 'stdio', 'http' (SSE) ou 'streamable-http'	`stdio`
`--http-addr`	Endereço do servidor HTTP (com --transport http/streamable-http)	`localhost:8080`
`--mcp-token`	Token de autenticação para transporte HTTP (obrigatório)
`--mcp-token-file`	Caminho para o arquivo contendo o token de autenticação
`--tls`	Habilitar TLS para transporte HTTP	`false`
`--tls-cert`	Caminho para o arquivo de certificado TLS
`--tls-key`	Caminho para o arquivo de chave TLS
`--allow-all-interfaces`	Permitir vinculação a 0.0.0.0/:: (requer --mcp-token e --tls)	`false`
`--legacy-dates`	Habilitar conversão de formato de data legado	`true`
`--no-legacy-dates`	Desabilitar conversão de formato de data legado	`false`
`--convert-dates-from-sap`	Converter formatos de data SAP nas respostas	`false`
`--response-metadata`	Incluir blocos __metadata nas respostas	`false`
`--pagination-hints`	Adicionar informações de paginação às respostas	`false`
`--max-response-size`	Tamanho máximo da resposta em bytes	`5MB`
`--max-items`	Número máximo de itens na resposta	`100`
`--verbose-errors`	Fornecer contexto detalhado de erros	`false`
`--claude-code-friendly, -c`	Remover o prefixo $ dos parâmetros OData para compatibilidade com a CLI do Claude Code	`false`
`--protocol-version`	Substituir a versão do protocolo MCP (ex.: '2025-06-18' para AI Foundry)	`2024-11-05`
`--forward-mcp-headers`	Encaminhar cabeçalhos HTTP da conexão MCP para o serviço OData (somente Streamable HTTP)	`false`
`--universal`	Usar uma única ferramenta OData universal em vez de ferramentas por entidade (reduz o contexto para serviços grandes)	`false`

Variáveis de Ambiente

Variável	Descrição
`ODATA_SERVICE_URL` ou `ODATA_URL`	URL do serviço OData
`ODATA_USERNAME` ou `ODATA_USER`	Nome de usuário para autenticação básica
`ODATA_PASSWORD` ou `ODATA_PASS`	Senha para autenticação básica
`ODATA_COOKIE_FILE`	Caminho para o arquivo de cookies
`ODATA_COOKIE_STRING`	String de cookie

Suporte a Arquivo .env

Crie um arquivo .env no diretório de trabalho:

ODATA_SERVICE_URL=https://my-service.com/odata/
ODATA_USERNAME=admin
ODATA_PASSWORD=secret

Ferramentas Geradas

A ponte gera automaticamente ferramentas MCP com base nos metadados do serviço OData:

Ferramentas de Conjuntos de Entidades

Para cada conjunto de entidades, as seguintes ferramentas são geradas (se o conjunto de entidades suportar a operação):

filter_{EntitySet} - Listar/filtrar entidades com opções de consulta OData
count_{EntitySet} - Obter contagem de entidades com filtro opcional
search_{EntitySet} - Pesquisa de texto completo (se suportada pelo serviço)
get_{EntitySet} - Obter uma única entidade por chave
create_{EntitySet} - Criar uma nova entidade (se permitido)
update_{EntitySet} - Atualizar uma entidade existente (se permitido)
delete_{EntitySet} - Excluir uma entidade (se permitido)

Ferramentas de Importação de Funções

Cada importação de função é mapeada para uma ferramenta individual com o nome da função.

Ferramenta de Informações do Serviço

odata_service_info - Obter metadados e capacidades do serviço OData

Exemplos

Serviço Northwind (v2)

# Connect to the public Northwind OData v2 service
./odata-mcp --trace https://services.odata.org/V2/Northwind/Northwind.svc/

# This will show generated tools like:
# - filter_Products_for_northwind
# - get_Products_for_northwind  
# - filter_Categories_for_northwind
# - get_Orders_for_northwind
# - etc.

Serviço Northwind (v4)

# Connect to the public Northwind OData v4 service
./odata-mcp --trace https://services.odata.org/V4/Northwind/Northwind.svc/

# OData v4 is automatically detected and handled appropriately
# Supports v4 specific features like:
# - $count parameter instead of $inlinecount
# - contains() filter function
# - New data types (Edm.Date, Edm.TimeOfDay, etc.)

Serviço OData SAP

# Connect to SAP service with CSRF token support
./odata-mcp --user admin --password secret \
  https://my-sap-system.com/sap/opu/odata/sap/SERVICE_NAME/

Diferenças em relação à versão Python

Embora mantenha a mesma interface e funcionalidade de CLI, esta implementação em Go oferece:

Melhor desempenho: binário nativo compilado com menor uso de memória
Implantação mais fácil: binário único sem dependências de runtime
Multiplataforma: binários nativos para Windows, macOS e Linux
Segurança de tipos: o sistema de tipos do Go oferece maior confiabilidade
Instalação mais simples: sem necessidade de runtime Python ou gerenciamento de pacotes

Versionamento

Este projeto usa versionamento automático baseado em tags git e histórico de commits:

Versões com tag: usa tags git (ex.: v1.0.0)
Builds de desenvolvimento: usa o formato 0.1.<commit-count>
Alterações não commitadas: acrescenta o sufixo -dirty

# Check current version
make version

# Create a release
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

Consulte VERSIONING.md para o guia detalhado de versionamento.

Lançamentos

Este projeto usa GitHub Actions automatizado para lançamentos. Consulte RELEASING.md para o processo de lançamento.

Solução de Problemas

Problemas com Clientes MCP

Se você estiver enfrentando problemas com clientes MCP (Claude Desktop, RooCode, GitHub Copilot):

Habilite o registro de rastreamento para diagnosticar problemas de protocolo:
```
./odata-mcp --trace-mcp https://my-service.com/odata/
```
Em seguida, verifique o arquivo de rastreamento no seu diretório temporário.
Problemas comuns e soluções:
- Ferramentas não aparecendo: verifique se a URL do serviço está correta e acessível
- Erros de validação: atualize para a versão mais recente que inclui correções de conformidade MCP
- Falhas de conexão: verifique as credenciais de autenticação e a conectividade de rede
Dicas específicas do serviço: a ferramenta odata_service_info agora inclui dicas automáticas para serviços problemáticos conhecidos

Consulte TROUBLESHOOTING.md para o guia detalhado de solução de problemas.

Sistema de Dicas de Serviço

A ponte OData MCP inclui um sistema sofisticado de dicas que ajuda os usuários a contornar problemas conhecidos do serviço e fornece orientação de implementação.

Formato do Arquivo de Dicas

Crie um arquivo hints.json com a seguinte estrutura:

{
  "version": "1.0",
  "hints": [
    {
      "pattern": "*/sap/opu/odata/*",
      "priority": 10,
      "service_type": "SAP OData Service",
      "known_issues": ["List of known issues"],
      "workarounds": ["List of workarounds"],
      "field_hints": {
        "FieldName": {
          "type": "Edm.String",
          "format": "Expected format",
          "example": "12345",
          "description": "Field description"
        }
      },
      "examples": [
        {
          "description": "Example description",
          "query": "filter_EntitySet with $filter=...",
          "note": "Additional note"
        }
      ]
    }
  ]
}

Correspondência de Padrões

O sistema de dicas suporta padrões curinga:

* corresponde a qualquer sequência de caracteres
? corresponde a um único caractere
Vários padrões podem corresponder ao mesmo serviço (as dicas são mescladas por prioridade)

Dicas Padrão

A ponte inclui dicas padrão para serviços comuns:

Serviços OData SAP (*/sap/opu/odata/*): orientação geral de OData SAP, incluindo a solução alternativa crítica para erros HTTP 501 usando $expand
Rastreamento de PO SAP (*SRA020_PO_TRACKING_SRV*): dicas específicas para rastreamento de pedidos de compra, incluindo formatação de campos
Demonstração Northwind (*Northwind*): identifica o serviço de demonstração público

Usando Dicas

As dicas aparecem na resposta da ferramenta odata_service_info em implementation_hints:

# View hints for your service
./odata-mcp https://my-service.com/odata/
# Then call the odata_service_info tool in your MCP client

# The response includes:
{
  "implementation_hints": {
    "service_type": "SAP OData Service",
    "known_issues": [...],
    "workarounds": [...],
    "field_hints": {...},
    "examples": [...],
    "hint_source": "Hints file: hints.json"
  }
}

Segurança

Este projeto inclui medidas abrangentes de segurança para evitar vazamentos de credenciais. Consulte SECURITY.md para obter detalhes.

Importante: nunca faça commit de .zmcp.json ou de qualquer arquivo contendo credenciais reais.

Documentação

QUICK_REFERENCE.md - Referência rápida de comandos
HINTS.md - Guia completo do sistema de dicas de serviço
TROUBLESHOOTING.md - Problemas comuns e soluções
SECURITY.md - Considerações de segurança
CHANGELOG.md - Histórico de versões e alterações

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar issues e pull requests.

Para perguntas e discussão com a comunidade, visite nossas Discussões do GitHub.

Desenvolvimento

Para configuração e testes de desenvolvimento:

# Run tests
make test

# Run with verbose output for debugging
./odata-mcp --verbose --trace-mcp https://my-service.com/odata/

# Check MCP compliance
./simple_compliance_test.sh

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.