Skip to content
Back to search

odata_mcp_go

OData MCP Bridge (Go)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oisee--odata-mcp-go/badge.svg)](/listings/oisee--odata-mcp-go)

HTML

<a href="/listings/oisee--odata-mcp-go"><img src="/api/listings/oisee--odata-mcp-go/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Download Binary

Download the appropriate binary for your platform from the [releases page](https://github.com/oisee/odata_mcp_go/releases).

Pre-built binaries are available for: - Linux (amd64) - Windows (amd64) - macOS (Intel and Apple Silicon)

Build from Source

Quick Build (Go required)

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

Using Makefile (Recommended)

# 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

Using Build Script

# Build for current platform
./build.sh

# Build for all platforms
./build.sh all

# See all options
./build.sh help

Cross-Compilation Examples

# 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

Docker Build

# Build Docker image
make docker

# Or manually
docker build -t odata-mcp .

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

Building in WSL (Windows Subsystem for Linux)

When building in WSL, you can use special targets that automatically copy the Windows binary to your Windows file system:

# 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

Note: These commands will check if `/mnt/c/bin` exists and skip the copy if not found, so they're safe to use on any system.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 979 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OData MCP Bridge (Go)
  2. A Go implementation of the OData to Model Context Protocol (MCP) bridge, providing universal access to OData services through MCP tools.
  3. This is a Go port of the Python OData-MCP bridge implementation, designed to be easier to run on different operating systems with better performance and simpler deployment. It supports both OData v2 and v4 services.
  4. ## 🆕 What's New (v1.6.0)
  5. ### Universal Tool Mode — One Tool to Rule Them All
  6. The biggest addition is **Universal Tool Mode** (`--universal`), a game-changer for large OData services:
  7. ```bash
  8. # Before: 485 tools, ~37,000 tokens, Claude says "no API available"
  9. ./odata-mcp https://large-sap-service.com/odata/
  10. # After: 1 tool, ~900 tokens, works perfectly
  11. ./odata-mcp --universal https://large-sap-service.com/odata/
  12. ```
  13. | Metric | Standard Mode | Universal Mode | Reduction |
  14. |--------|---------------|----------------|-----------|
  15. | Tools (Northwind) | 157 | 1 | 99.4% |
  16. | Tools (SAP BP) | 485 | 1 | 99.8% |
  17. | Token usage | ~37,000 | ~900 | 97.6% |
  18. **Why is it opt-in?** Universal mode changes how you interact with OData:
  19. - Standard mode: Each entity gets dedicated tools (`filter_Products`, `get_Orders`, etc.)
  20. - Universal mode: One `odata` tool with `action`, `target`, and `params`
  21. We made it opt-in because:
  22. 1. **Backward compatibility** — existing configs and workflows continue working
  23. 2. **Discoverability** — per-entity tools are self-documenting; LLMs can see exactly what's available
  24. 3. **Simplicity for small services** — if you have 20 tools, per-entity mode works great
  25. 4. **Explicit choice** — users should consciously choose the trade-off
  26. **When to use `--universal`:**
  27. - Service has 50+ entity sets
  28. - Running multiple OData services simultaneously
  29. - Experiencing "no API available" or tool selection failures
  30. - Want minimal token footprint
  31. See [Universal Tool Architecture](docs/008-issue-14-universal-tool-architecture.md) for the full story.
  32. ### MCP Header Forwarding
  33. New `--forward-mcp-headers` flag enables passing HTTP headers from MCP clients to OData services:
  34. ```bash
  35. ./odata-mcp --transport streamable-http --forward-mcp-headers https://secured-service.com/odata/
  36. ```
  37. This enables:
  38. - **Dynamic authentication** — pass credentials per-request instead of at startup
  39. - **Multi-tenant scenarios** — different users with different tokens
  40. - **Custom headers** — `X-*` headers flow through to OData
  41. ### Issue Fixes Bonanza
  42. This release fixes 10 open issues:
  43. | Issue | Problem | Fix |
  44. |-------|---------|-----|
  45. | #12 | SAP OData shows no tools | Fixed XML namespace parsing (`sap:creatable` etc.) |
  46. | #13 | `--max-items 99999` crashes | Added validation (max 10,000) |
  47. | #14 | Multiple services = Claude stuck | Universal tool mode |
  48. | #16 | GUID formatting wrong | Auto-detect SAP, add `guid'...'` prefix |
  49. | #17 | Timeout instead of error | Immediate error response |
  50. | #18 | Wildcard search fails | Parse `SearchRestrictions` annotation |
  51. | #19 | Timeout hides SAP error | Return actual error message |
  52. | #22 | BaseType not exposed | Added to EntityType model |
  53. | #23 | Header handling | `--forward-mcp-headers` flag |
  54. | #25 | Windows build no .exe | Fixed Makefile for Windows |
  55. ### Previous Releases
  56. - **AI Foundry Compatibility** (v1.5.1): `--protocol-version` flag for AI Foundry's `2025-06-18` protocol
  57. - **SAP GUID Filtering** (v1.5.0): Automatic `guid'...'` formatting for SAP services
  58. - **Streamable HTTP Transport** (v1.5.0): Modern MCP protocol with `--transport streamable-http`
  59. ## Features
  60. - **Universal OData Support**: Works with both OData v2 and v4 services
  61. - **Dynamic Tool Generation**: Automatically creates MCP tools based on OData metadata
  62. - **Multiple Authentication Methods**: Basic auth, cookie auth, and anonymous access
  63. - **SAP OData Extensions**: Full support for SAP-specific OData features including CSRF tokens
  64. - **Comprehensive CRUD Operations**: Generated tools for create, read, update, delete operations
  65. - **Advanced Query Support**: OData query options ($filter, $select, $expand, $orderby, etc.)
  66. - **Function Import Support**: Call OData function imports as MCP tools
  67. - **Flexible Tool Naming**: Configurable tool naming with prefix/postfix options
  68. - **Entity Filtering**: Selective tool generation with wildcard support
  69. - **Cross-Platform**: Native Go binary for easy deployment on any OS
  70. - **Read-Only Modes**: Restrict operations with `--read-only` or `--read-only-but-functions`
  71. - **MCP Protocol Debugging**: Built-in trace logging with `--trace-mcp` for troubleshooting
  72. - **Service-Specific Hints**: Flexible hint system with pattern matching for known service issues
  73. - **Full MCP Compliance**: Complete protocol implementation for all MCP clients
  74. - **Multiple Transports**: Support for stdio (default), HTTP/SSE, and Streamable HTTP
  75. - **AI Foundry Compatible**: Configurable protocol version for AI Foundry and other MCP clients
  76. ## Installation
  77. ### Download Binary
  78. Download the appropriate binary for your platform from the [releases page](https://github.com/oisee/odata_mcp_go/releases).
  79. Pre-built binaries are available for:
  80. - Linux (amd64)
  81. - Windows (amd64)
  82. - macOS (Intel and Apple Silicon)
  83. ### Build from Source
  84. #### Quick Build (Go required)
  85. ```bash
  86. git clone https://github.com/oisee/odata_mcp_go.git
  87. cd odata_mcp_go
  88. go build -o odata-mcp cmd/odata-mcp/main.go
  89. ```
  90. #### Using Makefile (Recommended)
  91. ```bash
  92. # Build for current platform
  93. make build
  94. # Build for all platforms
  95. make build-all
  96. # Build for all platforms with WSL integration (copies to /mnt/c/bin)
  97. make build-all-wsl
  98. # Build and test
  99. make dev
  100. # Check current version
  101. make version
  102. # See all options
  103. make help
  104. ```
  105. #### Using Build Script
  106. ```bash
  107. # Build for current platform
  108. ./build.sh
  109. # Build for all platforms
  110. ./build.sh all
  111. # See all options
  112. ./build.sh help
  113. ```
  114. #### Cross-Compilation Examples
  115. ```bash
  116. # Using Make
  117. make build-linux # Linux (amd64)
  118. make build-windows # Windows (amd64)
  119. make build-macos # macOS (Intel + Apple Silicon)
  120. # WSL-specific builds (copies Windows binary to /mnt/c/bin)
  121. make build-windows-wsl # Build Windows + WSL integration
  122. make build-all-wsl # Build all platforms + WSL integration
  123. # Using build script
  124. ./build.sh linux # Linux (amd64)
  125. ./build.sh windows # Windows (amd64)
  126. ./build.sh macos # macOS (Intel + Apple Silicon)
  127. # Manual Go build
  128. GOOS=linux GOARCH=amd64 go build -o odata-mcp-linux cmd/odata-mcp/main.go
  129. GOOS=windows GOARCH=amd64 go build -o odata-mcp.exe cmd/odata-mcp/main.go
  130. ```
  131. #### Docker Build
  132. ```bash
  133. # Build Docker image
  134. make docker
  135. # Or manually
  136. docker build -t odata-mcp .
  137. # Run in container
  138. docker run --rm -it odata-mcp --help
  139. ```
  140. #### Building in WSL (Windows Subsystem for Linux)
  141. When building in WSL, you can use special targets that automatically copy the Windows binary to your Windows file system:
  142. ```bash
  143. # Build all platforms and copy Windows binary to C:\bin
  144. make build-all-wsl
  145. # Build only Windows and copy to C:\bin
  146. make build-windows-wsl
  147. ```
  148. Note: These commands will check if `/mnt/c/bin` exists and skip the copy if not found, so they're safe to use on any system.
  149. ## Usage
  150. ### Claude Desktop Configuration
  151. Claude Desktop uses the stdio transport by default. Here are example configurations:
  152. #### Finding Your Configuration File
  153. The Claude Desktop configuration file location varies by platform:
  154. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  155. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  156. - **Linux**: `~/.config/Claude/claude_desktop_config.json`
  157. #### Basic Configuration
  158. ```json
  159. {
  160. "mcpServers": {
  161. "northwind-v2": {
  162. "command": "C:/bin/odata-mcp.exe",
  163. "args": [
  164. "--service",
  165. "https://services.odata.org/V2/Northwind/Northwind.svc/",
  166. "--tool-shrink"
  167. ]
  168. },
  169. "northwind-v4": {
  170. "command": "C:/bin/odata-mcp.exe",
  171. "args": [
  172. "--service",
  173. "https://services.odata.org/V4/Northwind/Northwind.svc/",
  174. "--tool-shrink"
  175. ]
  176. }
  177. }
  178. }
  179. ```
  180. #### With Authentication
  181. ```json
  182. {
  183. "mcpServers": {
  184. "my-sap-service": {
  185. "command": "/usr/local/bin/odata-mcp",
  186. "args": [
  187. "--service",
  188. "https://my-sap-system.com/sap/opu/odata/sap/MY_SERVICE/",
  189. "--user",
  190. "myusername",
  191. "--password",
  192. "mypassword",
  193. "--tool-shrink",
  194. "--entities",
  195. "Products,Orders,Customers"
  196. ]
  197. }
  198. }
  199. }
  200. ```
  201. #### Using Environment Variables (More Secure)
  202. ```json
  203. {
  204. "mcpServers": {
  205. "my-secure-service": {
  206. "command": "/usr/local/bin/odata-mcp",
  207. "args": [
  208. "--service",
  209. "https://my-service.com/odata/",
  210. "--tool-shrink"
  211. ],
  212. "env": {
  213. "ODATA_USERNAME": "myusername",
  214. "ODATA_PASSWORD": "mypassword"
  215. }
  216. }
  217. }
  218. }
  219. ```
  220. **Note:** Claude Desktop currently doesn't support reading environment variables from your system. The `env` field in the configuration sets environment variables specifically for that MCP server process.
  221. #### Security Best Practices for Claude Desktop
  222. 1. **Use environment variables** in the `env` field rather than hardcoding credentials in `args`
  223. 2. **Limit entity access** using the `--entities` flag to only expose necessary data
  224. 3. **Use read-only accounts** when possible for OData services
  225. 4. **Store configuration file securely** with appropriate file permissions
  226. **Note:** Claude Desktop does not currently support API key authentication for MCP servers. All MCP servers run locally with the same permissions as Claude Desktop itself.
  227. #### Read-Only Configuration Examples
  228. ```json
  229. {
  230. "mcpServers": {
  231. "production-readonly": {
  232. "command": "/usr/local/bin/odata-mcp",
  233. "args": [
  234. "--service",
  235. "https://production.company.com/odata/",
  236. "--read-only",
  237. "--tool-shrink"
  238. ],
  239. "env": {
  240. "ODATA_USERNAME": "readonly_user",
  241. "ODATA_PASSWORD": "readonly_pass"
  242. }
  243. },
  244. "dev-with-functions": {
  245. "command": "/usr/local/bin/odata-mcp",
  246. "args": [
  247. "--service",
  248. "https://dev.company.com/odata/",
  249. "--read-only-but-functions",
  250. "--trace-mcp" // Enable debugging
  251. ]
  252. }
  253. }
  254. }
  255. ```
  256. #### Claude Code CLI Compatibility
  257. The Claude Code CLI has stricter property name validation than other Claude tools. If you encounter errors like:
  258. ```
  259. 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}$"}}
  260. ```
  261. Use the `--claude-code-friendly` flag to remove the `$` prefix from OData parameter names:
  262. ```json
  263. {
  264. "mcpServers": {
  265. "northwind-claude-code": {
  266. "command": "/usr/local/bin/odata-mcp",
  267. "args": [
  268. "--service",
  269. "https://services.odata.org/V2/Northwind/Northwind.svc/",
  270. "--claude-code-friendly", // Removes $ from parameter names
  271. "--tool-shrink"
  272. ]
  273. }
  274. }
  275. }
  276. ```
  277. This transforms parameter names:
  278. - `$filter` → `filter`
  279. - `$select` → `select`
  280. - `$expand` → `expand`
  281. - `$orderby` → `orderby`
  282. - `$top` → `top`
  283. - `$skip` → `skip`
  284. - `$count` → `count`
  285. The server internally maps these friendly names back to their OData equivalents when making requests.
  286. #### Operation Filtering Configuration Examples
  287. ```json
  288. {
  289. "mcpServers": {
  290. "large-service-readonly": {
  291. "command": "/usr/local/bin/odata-mcp",
  292. "args": [
  293. "--service",
  294. "https://large-erp.company.com/odata/",
  295. "--disable", "cud", // Disable create, update, delete
  296. "--tool-shrink",
  297. "--entities", "Orders,Products,Customers"
  298. ],
  299. "env": {
  300. "ODATA_USERNAME": "readonly_user",
  301. "ODATA_PASSWORD": "readonly_pass"
  302. }
  303. },
  304. "minimal-tools": {
  305. "command": "/usr/local/bin/odata-mcp",
  306. "args": [
  307. "--service",
  308. "https://api.company.com/odata/",
  309. "--enable", "gf", // Only get and filter operations
  310. "--tool-shrink"
  311. ]
  312. },
  313. "no-actions": {
  314. "command": "/usr/local/bin/odata-mcp",
  315. "args": [
  316. "--service",
  317. "https://api.company.com/odata/",
  318. "--disable", "a", // Disable all function imports/actions
  319. "--verbose"
  320. ]
  321. }
  322. }
  323. }
  324. ### AI Foundry Configuration
  325. For AI Foundry integration, use the `--protocol-version` flag to specify the `2025-06-18` protocol:
  326. ```json
  327. {
  328. "mcpServers": {
  329. "odata-for-ai-foundry": {
  330. "command": "/usr/local/bin/odata-mcp",
  331. "args": [
  332. "--service",
  333. "https://your-odata-service.com/",
  334. "--protocol-version", "2025-06-18",
  335. "--user", "your-username",
  336. "--password", "your-password"
  337. ]
  338. }
  339. }
  340. }
  341. ```
  342. Or via command line:
  343. ```bash
  344. ./odata-mcp --service https://your-service.com/odata --protocol-version "2025-06-18"
  345. ```
  346. See the [AI Foundry Compatibility Guide](AI_FOUNDRY_COMPATIBILITY.md) for detailed setup instructions.
  347. ### Transport Options
  348. The OData MCP bridge supports two transport mechanisms:
  349. 1. **STDIO (default)** - Standard input/output communication, used by Claude Desktop
  350. 2. **HTTP/SSE** - HTTP server with Server-Sent Events for web-based clients
  351. > 🔒 **SECURITY MODEL**: HTTP transport uses a strict security model.
  352. >
  353. > **Security Requirements:**
  354. > - **Localhost**: Token required (`--mcp-token`)
  355. > - **Non-localhost**: Token + TLS required, no exceptions
  356. > - **All interfaces (0.0.0.0/::)**: Requires `--allow-all-interfaces` + token + TLS
  357. >
  358. > Token can be any string - for dev, `--mcp-token dev` works fine.
  359. #### Using Streamable HTTP Transport (Modern MCP Protocol)
  360. **New in v1.5.0**: Support for Streamable HTTP transport (protocol version 2024-11-05)
  361. ```bash
  362. # Start server with Streamable HTTP (recommended for modern clients)
  363. ./odata-mcp --transport streamable-http https://services.odata.org/V2/Northwind/Northwind.svc/
  364. # Use custom localhost port
  365. ./odata-mcp --transport streamable-http --http-addr localhost:3000 https://services.odata.org/V2/Northwind/Northwind.svc/
  366. ```
  367. Streamable HTTP endpoints:
  368. - `POST /mcp` - Main MCP endpoint (supports automatic SSE upgrade)
  369. - `GET /health` - Health check endpoint
  370. - `POST /sse` - Legacy SSE endpoint (for backward compatibility)
  371. #### Using HTTP/SSE Transport (Legacy)
  372. ```bash
  373. # Start server on localhost (default: localhost:8080)
  374. ./odata-mcp --transport http --mcp-token "dev" https://services.odata.org/V2/Northwind/Northwind.svc/
  375. # Use custom localhost port
  376. ./odata-mcp --transport http --http-addr localhost:3000 --mcp-token "dev" https://services.odata.org/V2/Northwind/Northwind.svc/
  377. # Non-localhost requires token + TLS
  378. ./odata-mcp --transport http --http-addr 192.168.1.100:8080 \
  379. --mcp-token "my-secret-token" --tls --tls-cert cert.pem --tls-key key.pem \
  380. https://services.odata.org/V2/Northwind/Northwind.svc/
  381. # All interfaces requires explicit flag + token + TLS
  382. ./odata-mcp --transport http --http-addr 0.0.0.0:8080 \
  383. --allow-all-interfaces --mcp-token "my-secret-token" \
  384. --tls --tls-cert cert.pem --tls-key key.pem \
  385. https://services.odata.org/V2/Northwind/Northwind.svc/
  386. ```
  387. Legacy HTTP/SSE endpoints:
  388. - `GET /health` - Health check endpoint
  389. - `GET /sse` - Server-Sent Events endpoint for real-time communication
  390. - `POST /rpc` - JSON-RPC endpoint for request/response communication
  391. #### Testing HTTP/SSE Transport
  392. 1. **Using the provided HTML client:**
  393. ```bash
  394. # Start the server
  395. ./odata-mcp --transport http https://services.odata.org/V2/Northwind/Northwind.svc/
  396. # Open examples/sse_client.html in a web browser
  397. ```
  398. 2. **Using curl:**
  399. ```bash
  400. # Test SSE endpoint
  401. curl -N -H 'Accept: text/event-stream' http://localhost:8080/sse
  402. # Test RPC endpoint
  403. curl -X POST http://localhost:8080/rpc \
  404. -H "Content-Type: application/json" \
  405. -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
  406. ```
  407. 3. **Using the test scripts:**
  408. ```bash
  409. # Test SSE with interactive script
  410. ./test_sse.sh
  411. # Test HTTP/RPC communication
  412. ./test_http_rpc.sh
  413. ```
  414. ### Basic Usage
  415. ```bash
  416. # Using positional argument
  417. ./odata-mcp https://services.odata.org/V2/Northwind/Northwind.svc/
  418. # Using --service flag
  419. ./odata-mcp --service https://services.odata.org/V2/Northwind/Northwind.svc/
  420. # Using environment variable
  421. export ODATA_SERVICE_URL=https://services.odata.org/V2/Northwind/Northwind.svc/
  422. ./odata-mcp
  423. ```
  424. ### Authentication
  425. ```bash
  426. # Basic authentication
  427. ./odata-mcp --user admin --password secret https://my-service.com/odata/
  428. # Cookie file authentication
  429. ./odata-mcp --cookie-file cookies.txt https://my-service.com/odata/
  430. # Cookie string authentication
  431. ./odata-mcp --cookie-string "session=abc123; token=xyz789" https://my-service.com/odata/
  432. # Environment variables
  433. export ODATA_USERNAME=admin
  434. export ODATA_PASSWORD=secret
  435. ./odata-mcp https://my-service.com/odata/
  436. ```
  437. ### Tool Naming Options
  438. ```bash
  439. # Use custom prefix instead of postfix
  440. ./odata-mcp --no-postfix --tool-prefix "myservice" https://my-service.com/odata/
  441. # Use custom postfix
  442. ./odata-mcp --tool-postfix "northwind" https://my-service.com/odata/
  443. # Use shortened tool names
  444. ./odata-mcp --tool-shrink https://my-service.com/odata/
  445. ```
  446. ### Entity and Function Filtering
  447. ```bash
  448. # Filter to specific entities (supports wildcards)
  449. ./odata-mcp --entities "Products,Categories,Order*" https://my-service.com/odata/
  450. # Filter to specific functions (supports wildcards)
  451. ./odata-mcp --functions "Get*,Create*" https://my-service.com/odata/
  452. ```
  453. ### Read-Only Modes
  454. ```bash
  455. # Hide all modifying operations (create, update, delete, and functions)
  456. ./odata-mcp --read-only https://my-service.com/odata/
  457. ./odata-mcp -ro https://my-service.com/odata/ # Short form
  458. # Hide create/update/delete but allow function imports
  459. ./odata-mcp --read-only-but-functions https://my-service.com/odata/
  460. ./odata-mcp -robf https://my-service.com/odata/ # Short form
  461. ```
  462. ### Operation Type Filtering
  463. Fine-grained control over which operation types are available. Operation types are:
  464. - `C` - Create operations
  465. - `S` - Search operations
  466. - `F` - Filter/list operations
  467. - `G` - Get (single entity) operations
  468. - `U` - Update operations
  469. - `D` - Delete operations
  470. - `A` - Actions/function imports
  471. - `R` - Read operations (expands to S, F, G)
  472. ```bash
  473. # Enable only read operations (search, filter, get)
  474. ./odata-mcp --enable "r" https://my-service.com/odata/
  475. ./odata-mcp --enable "sfg" https://my-service.com/odata/ # Same as above
  476. # Disable all modifying operations
  477. ./odata-mcp --disable "cud" https://my-service.com/odata/
  478. # Enable only get and filter operations
  479. ./odata-mcp --enable "gf" https://my-service.com/odata/
  480. # Disable actions/function imports
  481. ./odata-mcp --disable "a" https://my-service.com/odata/
  482. # Case-insensitive
  483. ./odata-mcp --disable "CUD" https://my-service.com/odata/
  484. ```
  485. Note: `--enable` and `--disable` cannot be used together.
  486. ### Universal Tool Mode
  487. For large OData services with many entities, the standard per-entity tool generation can create hundreds of tools, causing:
  488. - **Context rot**: LLMs struggle to reason when tool count exceeds ~128
  489. - **High token usage**: Tool schemas can consume 15,000-40,000 tokens
  490. - **Tool selection failures**: LLMs may report "no API available"
  491. Universal mode solves this by generating a single tool that handles all operations:
  492. ```bash
  493. # Enable universal tool mode
  494. ./odata-mcp --universal https://my-service.com/odata/
  495. # Compare tool counts
  496. ./odata-mcp --trace https://my-service.com/odata/ # Standard: many tools
  497. ./odata-mcp --universal --trace https://my-service.com/odata/ # Universal: 1 tool
  498. ```
  499. **When to use universal mode:**
  500. - Service has more than ~50 entity sets
  501. - Using multiple OData services simultaneously
  502. - Experiencing "no API available" errors with large services
  503. **Universal tool usage:**
  504. ```json
  505. {"action": "list", "target": "Products", "params": {"filter": "Price gt 100", "top": 10}}
  506. {"action": "get", "target": "Products", "params": {"key": {"ProductID": 1}}}
  507. {"action": "create", "target": "Orders", "params": {"data": {"CustomerID": "C001"}}}
  508. {"action": "call", "target": "ReleaseOrder", "params": {"OrderID": "O001"}}
  509. ```
  510. ### Debugging and Inspection
  511. ```bash
  512. # Enable verbose output
  513. ./odata-mcp --verbose https://my-service.com/odata/
  514. # Trace mode - show all tools without starting server
  515. ./odata-mcp --trace https://my-service.com/odata/
  516. # Enable MCP protocol trace logging (saves to temp directory)
  517. ./odata-mcp --trace-mcp https://my-service.com/odata/
  518. # Linux/WSL: /tmp/mcp_trace_*.log
  519. # Windows: %TEMP%\mcp_trace_*.log
  520. ```
  521. ### Service Hints
  522. The OData MCP bridge includes a flexible hint system to provide guidance for services with known issues or special requirements:
  523. ```bash
  524. # Use default hints.json from binary directory
  525. ./odata-mcp https://my-service.com/odata/
  526. # Use custom hints file
  527. ./odata-mcp --hints-file /path/to/custom-hints.json https://my-service.com/odata/
  528. # Inject hint directly from command line
  529. ./odata-mcp --hint "Remember to use \$expand for complex queries" https://my-service.com/odata/
  530. # Combine file and CLI hints (CLI has higher priority)
  531. ./odata-mcp --hints-file custom.json --hint '{"notes":["Override note"]}' https://my-service.com/odata/
  532. ```
  533. ## Configuration
  534. ### Command Line Flags
  535. | Flag | Description | Default |
  536. |------|-------------|---------|
  537. | `--service` | OData service URL | |
  538. | `-u, --user` | Username for basic auth | |
  539. | `-p, --password` | Password for basic auth | |
  540. | `--cookie-file` | Path to cookie file (Netscape format) | |
  541. | `--cookie-string` | Cookie string (key1=val1; key2=val2) | |
  542. | `--tool-prefix` | Custom prefix for tool names | |
  543. | `--tool-postfix` | Custom postfix for tool names | |
  544. | `--no-postfix` | Use prefix instead of postfix | `false` |
  545. | `--tool-shrink` | Use shortened tool names | `false` |
  546. | `--entities` | Comma-separated entity filter (supports wildcards) | |
  547. | `--functions` | Comma-separated function filter (supports wildcards) | |
  548. | `--sort-tools` | Sort tools alphabetically | `true` |
  549. | `-v, --verbose` | Enable verbose output | `false` |
  550. | `--debug` | Alias for --verbose | `false` |
  551. | `--trace` | Show tools and exit (debug mode) | `false` |
  552. | `--trace-mcp` | Enable MCP protocol trace logging | `false` |
  553. | `--read-only, -ro` | Hide all modifying operations | `false` |
  554. | `--read-only-but-functions, -robf` | Hide create/update/delete but allow functions | `false` |
  555. | `--enable` | Enable only specified operation types (C,S,F,G,U,D,A,R) | |
  556. | `--disable` | Disable specified operation types (C,S,F,G,U,D,A,R) | |
  557. | `--hints-file` | Path to hints JSON file | `hints.json` in binary dir |
  558. | `--hint` | Direct hint JSON or text from CLI | |
  559. | `--transport` | Transport type: 'stdio', 'http' (SSE), or 'streamable-http' | `stdio` |
  560. | `--http-addr` | HTTP server address (with --transport http/streamable-http) | `localhost:8080` |
  561. | `--mcp-token` | Authentication token for HTTP transport (required) | |
  562. | `--mcp-token-file` | Path to file containing authentication token | |
  563. | `--tls` | Enable TLS for HTTP transport | `false` |
  564. | `--tls-cert` | Path to TLS certificate file | |
  565. | `--tls-key` | Path to TLS key file | |
  566. | `--allow-all-interfaces` | Allow binding to 0.0.0.0/:: (requires --mcp-token and --tls) | `false` |
  567. | `--legacy-dates` | Enable legacy date format conversion | `true` |
  568. | `--no-legacy-dates` | Disable legacy date format conversion | `false` |
  569. | `--convert-dates-from-sap` | Convert SAP date formats in responses | `false` |
  570. | `--response-metadata` | Include __metadata blocks in responses | `false` |
  571. | `--pagination-hints` | Add pagination information to responses | `false` |
  572. | `--max-response-size` | Maximum response size in bytes | `5MB` |
  573. | `--max-items` | Maximum number of items in response | `100` |
  574. | `--verbose-errors` | Provide detailed error context | `false` |
  575. | `--claude-code-friendly, -c` | Remove $ prefix from OData parameters for Claude Code CLI compatibility | `false` |
  576. | `--protocol-version` | Override MCP protocol version (e.g., '2025-06-18' for AI Foundry) | `2024-11-05` |
  577. | `--forward-mcp-headers` | Forward HTTP headers from MCP connection to OData service (Streamable HTTP only) | `false` |
  578. | `--universal` | Use single universal OData tool instead of per-entity tools (reduces context for large services) | `false` |
  579. ### Environment Variables
  580. | Variable | Description |
  581. |----------|-------------|
  582. | `ODATA_SERVICE_URL` or `ODATA_URL` | OData service URL |
  583. | `ODATA_USERNAME` or `ODATA_USER` | Username for basic auth |
  584. | `ODATA_PASSWORD` or `ODATA_PASS` | Password for basic auth |
  585. | `ODATA_COOKIE_FILE` | Path to cookie file |
  586. | `ODATA_COOKIE_STRING` | Cookie string |
  587. ### .env File Support
  588. Create a `.env` file in the working directory:
  589. ```env
  590. ODATA_SERVICE_URL=https://my-service.com/odata/
  591. ODATA_USERNAME=admin
  592. ODATA_PASSWORD=secret
  593. ```
  594. ## Generated Tools
  595. The bridge automatically generates MCP tools based on the OData service metadata:
  596. ### Entity Set Tools
  597. For each entity set, the following tools are generated (if the entity set supports the operation):
  598. - `filter_{EntitySet}` - List/filter entities with OData query options
  599. - `count_{EntitySet}` - Get count of entities with optional filter
  600. - `search_{EntitySet}` - Full-text search (if supported by the service)
  601. - `get_{EntitySet}` - Get a single entity by key
  602. - `create_{EntitySet}` - Create a new entity (if allowed)
  603. - `update_{EntitySet}` - Update an existing entity (if allowed)
  604. - `delete_{EntitySet}` - Delete an entity (if allowed)
  605. ### Function Import Tools
  606. Each function import is mapped to an individual tool with the function name.
  607. ### Service Information Tool
  608. - `odata_service_info` - Get metadata and capabilities of the OData service
  609. ## Examples
  610. ### Northwind Service (v2)
  611. ```bash
  612. # Connect to the public Northwind OData v2 service
  613. ./odata-mcp --trace https://services.odata.org/V2/Northwind/Northwind.svc/
  614. # This will show generated tools like:
  615. # - filter_Products_for_northwind
  616. # - get_Products_for_northwind
  617. # - filter_Categories_for_northwind
  618. # - get_Orders_for_northwind
  619. # - etc.
  620. ```
  621. ### Northwind Service (v4)
  622. ```bash
  623. # Connect to the public Northwind OData v4 service
  624. ./odata-mcp --trace https://services.odata.org/V4/Northwind/Northwind.svc/
  625. # OData v4 is automatically detected and handled appropriately
  626. # Supports v4 specific features like:
  627. # - $count parameter instead of $inlinecount
  628. # - contains() filter function
  629. # - New data types (Edm.Date, Edm.TimeOfDay, etc.)
  630. ```
  631. ### SAP OData Service
  632. ```bash
  633. # Connect to SAP service with CSRF token support
  634. ./odata-mcp --user admin --password secret \
  635. https://my-sap-system.com/sap/opu/odata/sap/SERVICE_NAME/
  636. ```
  637. ## Differences from Python Version
  638. While maintaining the same CLI interface and functionality, this Go implementation offers:
  639. - **Better Performance**: Native compiled binary with lower memory usage
  640. - **Easier Deployment**: Single binary with no runtime dependencies
  641. - **Cross-Platform**: Native binaries for Windows, macOS, and Linux
  642. - **Type Safety**: Go's type system provides better reliability
  643. - **Simpler Installation**: No need for Python runtime or package management
  644. ## Versioning
  645. This project uses automatic versioning based on git tags and commit history:
  646. - **Tagged releases**: Uses git tags (e.g., `v1.0.0`)
  647. - **Development builds**: Uses `0.1.<commit-count>` format
  648. - **Uncommitted changes**: Appends `-dirty` suffix
  649. ```bash
  650. # Check current version
  651. make version
  652. # Create a release
  653. git tag -a v1.0.0 -m "Release v1.0.0"
  654. git push origin v1.0.0
  655. ```
  656. See [VERSIONING.md](VERSIONING.md) for detailed versioning guide.
  657. ## Releasing
  658. This project uses automated GitHub Actions for releases. See [RELEASING.md](RELEASING.md) for the release process.
  659. ## Troubleshooting
  660. ### MCP Client Issues
  661. If you're experiencing issues with MCP clients (Claude Desktop, RooCode, GitHub Copilot):
  662. 1. **Enable trace logging** to diagnose protocol issues:
  663. ```bash
  664. ./odata-mcp --trace-mcp https://my-service.com/odata/
  665. ```
  666. Then check the trace file in your temp directory.
  667. 2. **Common issues and solutions**:
  668. - **Tools not appearing**: Ensure the service URL is correct and accessible
  669. - **Validation errors**: Update to the latest version which includes MCP compliance fixes
  670. - **Connection failures**: Check authentication credentials and network connectivity
  671. 3. **Service-specific hints**: The `odata_service_info` tool now includes automatic hints for known problematic services
  672. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed troubleshooting guide.
  673. ### Service Hints System
  674. The OData MCP bridge includes a sophisticated hint system that helps users work around known service issues and provides implementation guidance.
  675. #### Hint File Format
  676. Create a `hints.json` file with the following structure:
  677. ```json
  678. {
  679. "version": "1.0",
  680. "hints": [
  681. {
  682. "pattern": "*/sap/opu/odata/*",
  683. "priority": 10,
  684. "service_type": "SAP OData Service",
  685. "known_issues": ["List of known issues"],
  686. "workarounds": ["List of workarounds"],
  687. "field_hints": {
  688. "FieldName": {
  689. "type": "Edm.String",
  690. "format": "Expected format",
  691. "example": "12345",
  692. "description": "Field description"
  693. }
  694. },
  695. "examples": [
  696. {
  697. "description": "Example description",
  698. "query": "filter_EntitySet with $filter=...",
  699. "note": "Additional note"
  700. }
  701. ]
  702. }
  703. ]
  704. }
  705. ```
  706. #### Pattern Matching
  707. The hint system supports wildcard patterns:
  708. - `*` matches any sequence of characters
  709. - `?` matches a single character
  710. - Multiple patterns can match the same service (hints are merged by priority)
  711. #### Default Hints
  712. The bridge includes default hints for common services:
  713. - **SAP OData Services** (`*/sap/opu/odata/*`): General SAP OData guidance including the critical workaround for HTTP 501 errors using `$expand`
  714. - **SAP PO Tracking** (`*SRA020_PO_TRACKING_SRV*`): Specific hints for purchase order tracking including field formatting
  715. - **Northwind Demo** (`*Northwind*`): Identifies the public demo service
  716. #### Using Hints
  717. Hints appear in the `odata_service_info` tool response under `implementation_hints`:
  718. ```bash
  719. # View hints for your service
  720. ./odata-mcp https://my-service.com/odata/
  721. # Then call the odata_service_info tool in your MCP client
  722. # The response includes:
  723. {
  724. "implementation_hints": {
  725. "service_type": "SAP OData Service",
  726. "known_issues": [...],
  727. "workarounds": [...],
  728. "field_hints": {...},
  729. "examples": [...],
  730. "hint_source": "Hints file: hints.json"
  731. }
  732. }
  733. ```
  734. ## Security
  735. This project includes comprehensive security measures to prevent credential leaks. See [SECURITY.md](SECURITY.md) for details.
  736. **Important**: Never commit `.zmcp.json` or any files containing real credentials.
  737. ## Documentation
  738. - [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Quick command reference
  739. - [HINTS.md](HINTS.md) - Complete guide to the service hints system
  740. - [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions
  741. - [SECURITY.md](SECURITY.md) - Security considerations
  742. - [CHANGELOG.md](CHANGELOG.md) - Version history and changes
  743. ## Contributing
  744. Contributions are welcome! Please feel free to submit issues and pull requests.
  745. For questions and community discussion, visit our [GitHub Discussions](https://github.com/oisee/odata_mcp_go/discussions/11).
  746. ### Development
  747. For development setup and testing:
  748. ```bash
  749. # Run tests
  750. make test
  751. # Run with verbose output for debugging
  752. ./odata-mcp --verbose --trace-mcp https://my-service.com/odata/
  753. # Check MCP compliance
  754. ./simple_compliance_test.sh
  755. ```
  756. ## License
  757. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.