OData MCP Bridge (Go)

Un puente en Go que proporciona acceso universal a servicios OData v2 a través de herramientas MCP, con soporte para múltiples métodos de autenticación.

GitHub

142

Prueba este MCPPatrocinado

Documentación

OData MCP Bridge (Go)

Una implementación en Go del puente OData a Protocolo de Contexto de Modelo (MCP), que proporciona acceso universal a servicios OData a través de herramientas MCP.

Este es un puerto en Go de la implementación del puente OData-MCP en Python, diseñado para ser más fácil de ejecutar en diferentes sistemas operativos con mejor rendimiento y despliegue más simple. Soporta servicios OData v2 y v4.

🆕 Novedades (v1.6.0)

Modo de Herramienta Universal — Una Herramienta para Gobernarlos a Todos

La mayor adición es el Modo de Herramienta Universal (--universal), un cambio de juego para servicios OData grandes:

# 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 Estándar	Modo Universal	Reducción
Herramientas (Northwind)	157	1	99.4%
Herramientas (SAP BP)	485	1	99.8%
Uso de tokens	~37,000	~900	97.6%

¿Por qué es opcional? El modo universal cambia cómo interactúas con OData:

Modo estándar: Cada entidad obtiene herramientas dedicadas (filter_Products, get_Orders, etc.)
Modo universal: Una herramienta odata con action, target y params

Lo hicimos opcional porque:

Compatibilidad hacia atrás — las configuraciones y flujos de trabajo existentes siguen funcionando
Descubribilidad — las herramientas por entidad son autodocumentadas; los LLM pueden ver exactamente qué está disponible
Simplicidad para servicios pequeños — si tienes 20 herramientas, el modo por entidad funciona muy bien
Elección explícita — los usuarios deben elegir conscientemente el equilibrio

Cuándo usar --universal:

El servicio tiene 50+ conjuntos de entidades
Ejecutar múltiples servicios OData simultáneamente
Experimentar "no hay API disponible" o fallos de selección de herramientas
Querer una huella de tokens mínima

Consulta Arquitectura de Herramienta Universal para la historia completa.

Reenvío de Cabeceras MCP

Nuevo indicador --forward-mcp-headers permite pasar cabeceras HTTP de clientes MCP a servicios OData:

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

Esto permite:

Autenticación dinámica — pasar credenciales por solicitud en lugar de al inicio
Escenarios multi-tenant — diferentes usuarios con diferentes tokens
Cabeceras personalizadas — las cabeceras X-* fluyen a OData

Bonanza de Correcciones de Problemas

Esta versión corrige 10 problemas abiertos:

Problema	Problema	Corrección
#12	SAP OData no muestra herramientas	Corregido el análisis de espacios de nombres XML (`sap:creatable` etc.)
#13	`--max-items 99999` se bloquea	Añadida validación (máximo 10,000)
#14	Múltiples servicios = Claude atascado	Modo de herramienta universal
#16	Formato GUID incorrecto	Detección automática de SAP, añadir prefijo `guid'...'`
#17	Tiempo de espera en lugar de error	Respuesta de error inmediata
#18	Búsqueda con comodín falla	Analizar anotación `SearchRestrictions`
#19	Tiempo de espera oculta error de SAP	Devolver mensaje de error real
#22	BaseType no expuesto	Añadido al modelo EntityType
#23	Manejo de cabeceras	Indicador `--forward-mcp-headers`
#25	Compilación de Windows sin .exe	Corregido Makefile para Windows

Versiones Anteriores

Compatibilidad con AI Foundry (v1.5.1): Indicador --protocol-version para el protocolo 2025-06-18 de AI Foundry
Filtrado GUID de SAP (v1.5.0): Formato automático guid'...' para servicios SAP
Transporte HTTP Streamable (v1.5.0): Protocolo MCP moderno con --transport streamable-http

Características

Soporte Universal de OData: Funciona con servicios OData v2 y v4
Generación Dinámica de Herramientas: Crea automáticamente herramientas MCP basadas en metadatos OData
Múltiples Métodos de Autenticación: Autenticación básica, autenticación por cookies y acceso anónimo
Extensiones SAP OData: Soporte completo para características OData específicas de SAP, incluidos tokens CSRF
Operaciones CRUD Integrales: Herramientas generadas para operaciones de crear, leer, actualizar, eliminar
Soporte de Consultas Avanzadas: Opciones de consulta OData ($filter, $select, $expand, $orderby, etc.)
Soporte de Importación de Funciones: Llamar importaciones de funciones OData como herramientas MCP
Nombres de Herramientas Flexibles: Nombres de herramientas configurables con opciones de prefijo/sufijo
Filtrado de Entidades: Generación selectiva de herramientas con soporte de comodines
Multiplataforma: Binario nativo de Go para fácil despliegue en cualquier sistema operativo
Modos de Solo Lectura: Restringir operaciones con --read-only o --read-only-but-functions
Depuración de Protocolo MCP: Registro de trazas integrado con --trace-mcp para solución de problemas
Sugerencias Específicas de Servicio: Sistema de sugerencias flexible con coincidencia de patrones para problemas conocidos de servicios
Cumplimiento Total de MCP: Implementación completa del protocolo para todos los clientes MCP
Múltiples Transportes: Soporte para stdio (predeterminado), HTTP/SSE y HTTP Streamable
Compatible con AI Foundry: Versión de protocolo configurable para AI Foundry y otros clientes MCP

Instalación

Descargar Binario

Descarga el binario apropiado para tu plataforma desde la página de versiones.

Los binarios precompilados están disponibles para:

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

Compilar desde el Código Fuente

Compilación Rápida (requiere 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 Compilación

# Build for current platform
./build.sh

# Build for all platforms
./build.sh all

# See all options
./build.sh help

Ejemplos de Compilación 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

Compilación Docker

# Build Docker image
make docker

# Or manually
docker build -t odata-mcp .

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

Compilación en WSL (Subsistema de Windows para Linux)

Al compilar en WSL, puedes usar objetivos especiales que copian automáticamente el binario de Windows a tu sistema de archivos de 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: Estos comandos verificarán si /mnt/c/bin existe y omitirán la copia si no se encuentra, por lo que son seguros de usar en cualquier sistema.

Uso

Configuración de Claude Desktop

Claude Desktop usa el transporte stdio por defecto. Aquí hay configuraciones de ejemplo:

Encontrar tu Archivo de Configuración

La ubicación del archivo de configuración de Claude Desktop varía según la plataforma:

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

Configuración 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"
            ]
        }
    }
}

Con Autenticación

{
    "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 Variables de Entorno (Más 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: Claude Desktop actualmente no admite leer variables de entorno de tu sistema. El campo env en la configuración establece variables de entorno específicamente para ese proceso de servidor MCP.

Mejores Prácticas de Seguridad para Claude Desktop

Usa variables de entorno en el campo env en lugar de codificar credenciales en args
Limita el acceso a entidades usando el indicador --entities para exponer solo los datos necesarios
Usa cuentas de solo lectura cuando sea posible para servicios OData
Almacena el archivo de configuración de forma segura con permisos de archivo apropiados

Nota: Claude Desktop no admite actualmente autenticación por clave API para servidores MCP. Todos los servidores MCP se ejecutan localmente con los mismos permisos que Claude Desktop.

Ejemplos de Configuración de Solo Lectura

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

Compatibilidad con Claude Code CLI

El Claude Code CLI tiene una validación de nombres de propiedades más estricta que otras herramientas de Claude. Si encuentras errores 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}$"}}

Usa el indicador --claude-code-friendly para eliminar el prefijo $ de los nombres 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"
            ]
        }
    }
}

Esto transforma los nombres de parámetros:

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

El servidor mapea internamente estos nombres amigables de vuelta a sus equivalentes OData al hacer solicitudes.

Ejemplos de Configuración de Filtrado de Operaciones

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

O mediante línea de comandos:

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

Consulta la Guía de Compatibilidad con AI Foundry para instrucciones detalladas de configuración.

Opciones de Transporte

El puente OData MCP admite dos mecanismos de transporte:

STDIO (predeterminado) - Comunicación estándar de entrada/salida, usado por Claude Desktop
HTTP/SSE - Servidor HTTP con Eventos Enviados por el Servidor para clientes basados en web

🔒 MODELO DE SEGURIDAD: El transporte HTTP usa un modelo de seguridad estricto.

Requisitos de Seguridad:

Localhost: Token requerido (--mcp-token)

No-localhost: Token + TLS requerido, sin excepciones

Todas las interfaces (0.0.0.0/::): Requiere --allow-all-interfaces + token + TLS

El token puede ser cualquier cadena - para desarrollo, --mcp-token dev funciona bien.

Usando Transporte HTTP Streamable (Protocolo MCP Moderno)

Nuevo en v1.5.0: Soporte para transporte HTTP Streamable (versión de 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 de HTTP Streamable:

POST /mcp - Endpoint principal de MCP (soporta actualización automática a SSE)
GET /health - Endpoint de verificación de salud
POST /sse - Endpoint SSE heredado (para compatibilidad hacia atrás)

Usando Transporte HTTP/SSE (Heredado)

# 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 heredados:

GET /health - Endpoint de verificación de salud
GET /sse - Endpoint de Eventos Enviados por el Servidor para comunicación en tiempo real
POST /rpc - Endpoint JSON-RPC para comunicación de solicitud/respuesta

Probando Transporte HTTP/SSE

Usando el cliente HTML proporcionado:

# 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 los scripts de prueba:

# 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

Autenticación

# 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/

Opciones de Nombres de Herramientas

# 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/

Filtrado de Entidades y Funciones

# 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 de Solo Lectura

# 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

Filtrado por Tipo de Operación

Control fino sobre qué tipos de operación están disponibles. Los tipos de operación son:

C - Operaciones de creación
S - Operaciones de búsqueda
F - Operaciones de filtro/listado
G - Operaciones de obtener (entidad única)
U - Operaciones de actualización
D - Operaciones de eliminación
A - Acciones/importaciones de funciones
R - Operaciones de lectura (se expande a 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 y --disable no se pueden usar juntos.

Modo de Herramienta Universal

Para servicios OData grandes con muchas entidades, la generación estándar de herramientas por entidad puede crear cientos de herramientas, causando:

Rotación de contexto: Los LLM tienen dificultades para razonar cuando el número de herramientas supera ~128
Alto uso de tokens: Los esquemas de herramientas pueden consumir 15,000-40,000 tokens
Fallos de selección de herramientas: Los LLM pueden reportar "no hay API disponible"

El modo universal resuelve esto generando una sola herramienta que maneja todas las operaciones:

# 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

Cuándo usar el modo universal:

El servicio tiene más de ~50 conjuntos de entidades
Usar múltiples servicios OData simultáneamente
Experimentar errores de "no hay API disponible" con servicios grandes

Uso de la herramienta 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"}}

Depuración e Inspección

# 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

Sugerencias de Servicio

El puente OData MCP incluye un sistema de sugerencias flexible para proporcionar orientación para servicios con problemas conocidos o requisitos especiales:

# 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/

Configuración

Indicadores de Línea de Comandos

Bandera	Descripción	Por defecto
`--service`	URL del servicio OData
`-u, --user`	Nombre de usuario para autenticación básica
`-p, --password`	Contraseña para autenticación básica
`--cookie-file`	Ruta al archivo de cookies (formato Netscape)
`--cookie-string`	Cadena de cookies (key1=val1; key2=val2)
`--tool-prefix`	Prefijo personalizado para nombres de herramientas
`--tool-postfix`	Sufijo personalizado para nombres de herramientas
`--no-postfix`	Usar prefijo en lugar de sufijo	`false`
`--tool-shrink`	Usar nombres de herramientas abreviados	`false`
`--entities`	Filtro de entidades separado por comas (admite comodines)
`--functions`	Filtro de funciones separado por comas (admite comodines)
`--sort-tools`	Ordenar herramientas alfabéticamente	`true`
`-v, --verbose`	Habilitar salida detallada	`false`
`--debug`	Alias para --verbose	`false`
`--trace`	Mostrar herramientas y salir (modo depuración)	`false`
`--trace-mcp`	Habilitar registro de trazas del protocolo MCP	`false`
`--read-only, -ro`	Ocultar todas las operaciones de modificación	`false`
`--read-only-but-functions, -robf`	Ocultar crear/actualizar/eliminar pero permitir funciones	`false`
`--enable`	Habilitar solo los tipos de operación especificados (C,S,F,G,U,D,A,R)
`--disable`	Deshabilitar los tipos de operación especificados (C,S,F,G,U,D,A,R)
`--hints-file`	Ruta al archivo JSON de sugerencias	`hints.json` en el directorio del binario
`--hint`	JSON de sugerencias directo o texto desde CLI
`--transport`	Tipo de transporte: 'stdio', 'http' (SSE) o 'streamable-http'	`stdio`
`--http-addr`	Dirección del servidor HTTP (con --transport http/streamable-http)	`localhost:8080`
`--mcp-token`	Token de autenticación para transporte HTTP (obligatorio)
`--mcp-token-file`	Ruta al archivo que contiene el token de autenticación
`--tls`	Habilitar TLS para transporte HTTP	`false`
`--tls-cert`	Ruta al archivo de certificado TLS
`--tls-key`	Ruta al archivo de clave TLS
`--allow-all-interfaces`	Permitir enlace a 0.0.0.0/:: (requiere --mcp-token y --tls)	`false`
`--legacy-dates`	Habilitar conversión de formato de fecha heredado	`true`
`--no-legacy-dates`	Deshabilitar conversión de formato de fecha heredado	`false`
`--convert-dates-from-sap`	Convertir formatos de fecha SAP en las respuestas	`false`
`--response-metadata`	Incluir bloques __metadata en las respuestas	`false`
`--pagination-hints`	Añadir información de paginación a las respuestas	`false`
`--max-response-size`	Tamaño máximo de respuesta en bytes	`5MB`
`--max-items`	Número máximo de elementos en la respuesta	`100`
`--verbose-errors`	Proporcionar contexto de error detallado	`false`
`--claude-code-friendly, -c`	Eliminar el prefijo $ de los parámetros OData para compatibilidad con Claude Code CLI	`false`
`--protocol-version`	Anular la versión del protocolo MCP (p. ej., '2025-06-18' para AI Foundry)	`2024-11-05`
`--forward-mcp-headers`	Reenviar cabeceras HTTP de la conexión MCP al servicio OData (solo Streamable HTTP)	`false`
`--universal`	Usar una única herramienta OData universal en lugar de herramientas por entidad (reduce el contexto para servicios grandes)	`false`

Variables de entorno

Variable	Descripción
`ODATA_SERVICE_URL` o `ODATA_URL`	URL del servicio OData
`ODATA_USERNAME` o `ODATA_USER`	Nombre de usuario para autenticación básica
`ODATA_PASSWORD` o `ODATA_PASS`	Contraseña para autenticación básica
`ODATA_COOKIE_FILE`	Ruta al archivo de cookies
`ODATA_COOKIE_STRING`	Cadena de cookies

Soporte de archivo .env

Cree un archivo .env en el directorio de trabajo:

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

Herramientas generadas

El puente genera automáticamente herramientas MCP basadas en los metadatos del servicio OData:

Herramientas de conjuntos de entidades

Para cada conjunto de entidades, se generan las siguientes herramientas (si el conjunto de entidades admite la operación):

filter_{EntitySet} - Listar/filtrar entidades con opciones de consulta OData
count_{EntitySet} - Obtener el recuento de entidades con filtro opcional
search_{EntitySet} - Búsqueda de texto completo (si el servicio lo admite)
get_{EntitySet} - Obtener una única entidad por clave
create_{EntitySet} - Crear una nueva entidad (si está permitido)
update_{EntitySet} - Actualizar una entidad existente (si está permitido)
delete_{EntitySet} - Eliminar una entidad (si está permitido)

Herramientas de importación de funciones

Cada importación de función se asigna a una herramienta individual con el nombre de la función.

Herramienta de información del servicio

odata_service_info - Obtener metadatos y capacidades del servicio OData

Ejemplos

Servicio 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.

Servicio 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.)

Servicio 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/

Diferencias con la versión de Python

Si bien mantiene la misma interfaz CLI y funcionalidad, esta implementación en Go ofrece:

Mejor rendimiento: binario compilado nativo con menor uso de memoria
Implementación más fácil: binario único sin dependencias de tiempo de ejecución
Multiplataforma: binarios nativos para Windows, macOS y Linux
Seguridad de tipos: el sistema de tipos de Go proporciona mayor fiabilidad
Instalación más simple: no se necesita tiempo de ejecución de Python ni gestión de paquetes

Control de versiones

Este proyecto utiliza control de versiones automático basado en etiquetas git e historial de confirmaciones:

Lanzamientos etiquetados: usa etiquetas git (p. ej., v1.0.0)
Compilaciones de desarrollo: usa el formato 0.1.<commit-count>
Cambios no confirmados: añade el sufijo -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 obtener una guía detallada de control de versiones.

Publicación de versiones

Este proyecto utiliza GitHub Actions automatizado para las publicaciones. Consulte RELEASING.md para conocer el proceso de publicación.

Solución de problemas

Problemas con clientes MCP

Si está experimentando problemas con clientes MCP (Claude Desktop, RooCode, GitHub Copilot):

Habilite el registro de trazas para diagnosticar problemas de protocolo:
```
./odata-mcp --trace-mcp https://my-service.com/odata/
```
Luego revise el archivo de trazas en su directorio temporal.
Problemas comunes y soluciones:
- Las herramientas no aparecen: asegúrese de que la URL del servicio sea correcta y accesible
- Errores de validación: actualice a la última versión que incluye correcciones de cumplimiento MCP
- Fallos de conexión: verifique las credenciales de autenticación y la conectividad de red
Sugerencias específicas del servicio: la herramienta odata_service_info ahora incluye sugerencias automáticas para servicios problemáticos conocidos

Consulte TROUBLESHOOTING.md para obtener una guía detallada de solución de problemas.

Sistema de sugerencias de servicios

El puente OData MCP incluye un sistema de sugerencias sofisticado que ayuda a los usuarios a sortear problemas conocidos del servicio y proporciona orientación de implementación.

Formato del archivo de sugerencias

Cree un archivo hints.json con la siguiente estructura:

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

Coincidencia de patrones

El sistema de sugerencias admite patrones comodín:

* coincide con cualquier secuencia de caracteres
? coincide con un solo carácter
Varios patrones pueden coincidir con el mismo servicio (las sugerencias se combinan por prioridad)

Sugerencias predeterminadas

El puente incluye sugerencias predeterminadas para servicios comunes:

Servicios OData SAP (*/sap/opu/odata/*): orientación general de OData SAP, incluida la solución crítica para errores HTTP 501 mediante $expand
Seguimiento de PO SAP (*SRA020_PO_TRACKING_SRV*): sugerencias específicas para el seguimiento de órdenes de compra, incluido el formato de campos
Demo Northwind (*Northwind*): identifica el servicio de demostración público

Uso de sugerencias

Las sugerencias aparecen en la respuesta de la herramienta odata_service_info bajo 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"
  }
}

Seguridad

Este proyecto incluye medidas de seguridad integrales para evitar fugas de credenciales. Consulte SECURITY.md para obtener más detalles.

Importante: nunca confirme .zmcp.json ni ningún archivo que contenga credenciales reales.

Documentación

QUICK_REFERENCE.md - Referencia rápida de comandos
HINTS.md - Guía completa del sistema de sugerencias de servicios
TROUBLESHOOTING.md - Problemas comunes y soluciones
SECURITY.md - Consideraciones de seguridad
CHANGELOG.md - Historial de versiones y cambios

Contribuciones

¡Las contribuciones son bienvenidas! No dude en enviar problemas y solicitudes de extracción.

Para preguntas y debates comunitarios, visite nuestras Discusiones de GitHub.

Desarrollo

Para configuración y pruebas de desarrollo:

# 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

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulte el archivo LICENSE para obtener más detalles.