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

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

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

# 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

# Build for current platform
./build.sh

# Build for all platforms
./build.sh all

# See all options
./build.sh help

# 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 Docker image
make docker

# Or manually
docker build -t odata-mcp .

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

# 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

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

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

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

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

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

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

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

Or via command line:

See the [AI Foundry Compatibility Guide](AI_FOUNDRY_COMPATIBILITY.md) for detailed setup instructions.

### Transport Options

The OData MCP bridge supports two transport mechanisms:

1. **STDIO (default)** - Standard input/output communication, used by Claude Desktop
2. **HTTP/SSE** - HTTP server with Server-Sent Events for web-based clients

> 🔒 **SECURITY MODEL**: HTTP transport uses a strict security model.
>
> **Security Requirements:**
> - **Localhost**: Token required (`--mcp-token`)
> - **Non-localhost**: Token + TLS required, no exceptions
> - **All interfaces (0.0.0.0/::)**: Requires `--allow-all-interfaces` + token + TLS
>
> Token can be any string - for dev, `--mcp-token dev` works fine.

#### Using Streamable HTTP Transport (Modern MCP Protocol)

**New in v1.5.0**: Support for Streamable HTTP transport (protocol version 2024-11-05)

Streamable HTTP endpoints:
- `POST /mcp` - Main MCP endpoint (supports automatic SSE upgrade)
- `GET /health` - Health check endpoint
- `POST /sse` - Legacy SSE endpoint (for backward compatibility)

#### Using HTTP/SSE Transport (Legacy)

Legacy HTTP/SSE endpoints:
- `GET /health` - Health check endpoint
- `GET /sse` - Server-Sent Events endpoint for real-time communication
- `POST /rpc` - JSON-RPC endpoint for request/response communication

#### Testing HTTP/SSE Transport

1. **Using the provided HTML client:**

2. **Using curl:**

3. **Using the test scripts:**

### Basic Usage

### Authentication

### Tool Naming Options

### Entity and Function Filtering

### Read-Only Modes

### Operation Type Filtering

Fine-grained control over which operation types are available. Operation types are:
- `C` - Create operations
- `S` - Search operations
- `F` - Filter/list operations
- `G` - Get (single entity) operations
- `U` - Update operations
- `D` - Delete operations
- `A` - Actions/function imports
- `R` - Read operations (expands to S, F, G)

Note: `--enable` and `--disable` cannot be used together.

### Universal Tool Mode

For large OData services with many entities, the standard per-entity tool generation can create hundreds of tools, causing:
- **Context rot**: LLMs struggle to reason when tool count exceeds ~128
- **High token usage**: Tool schemas can consume 15,000-40,000 tokens
- **Tool selection failures**: LLMs may report "no API available"

Universal mode solves this by generating a single tool that handles all operations:

**When to use universal mode:**
- Service has more than ~50 entity sets
- Using multiple OData services simultaneously
- Experiencing "no API available" errors with large services

**Universal tool usage:**

### Debugging and Inspection

### Service Hints

The OData MCP bridge includes a flexible hint system to provide guidance for services with known issues or special requirements:

## Configuration

### Command Line Flags

| Flag | Description | Default |
|------|-------------|---------|
| `--service` | OData service URL | |
| `-u, --user` | Username for basic auth | |
| `-p, --password` | Password for basic auth | |
| `--cookie-file` | Path to cookie file (Netscape format) | |
| `--cookie-string` | Cookie string (key1=val1; key2=val2) | |
| `--tool-prefix` | Custom prefix for tool names | |
| `--tool-postfix` | Custom postfix for tool names | |
| `--no-postfix` | Use prefix instead of postfix | `false` |
| `--tool-shrink` | Use shortened tool names | `false` |
| `--entities` | Comma-separated entity filter (supports wildcards) | |
| `--functions` | Comma-separated function filter (supports wildcards) | |
| `--sort-tools` | Sort tools alphabetically | `true` |
| `-v, --verbose` | Enable verbose output | `false` |
| `--debug` | Alias for --verbose | `false` |
| `--trace` | Show tools and exit (debug mode) | `false` |
| `--trace-mcp` | Enable MCP protocol trace logging | `false` |
| `--read-only, -ro` | Hide all modifying operations | `false` |
| `--read-only-but-functions, -robf` | Hide create/update/delete but allow functions | `false` |
| `--enable` | Enable only specified operation types (C,S,F,G,U,D,A,R) | |
| `--disable` | Disable specified operation types (C,S,F,G,U,D,A,R) | |
| `--hints-file` | Path to hints JSON file | `hints.json` in binary dir |
| `--hint` | Direct hint JSON or text from CLI | |
| `--transport` | Transport type: 'stdio', 'http' (SSE), or 'streamable-http' | `stdio` |
| `--http-addr` | HTTP server address (with --transport http/streamable-http) | `localhost:8080` |
| `--mcp-token` | Authentication token for HTTP transport (required) | |
| `--mcp-token-file` | Path to file containing authentication token | |
| `--tls` | Enable TLS for HTTP transport | `false` |
| `--tls-cert` | Path to TLS certificate file | |
| `--tls-key` | Path to TLS key file | |
| `--allow-all-interfaces` | Allow binding to 0.0.0.0/:: (requires --mcp-token and --tls) | `false` |
| `--legacy-dates` | Enable legacy date format conversion | `true` |
| `--no-legacy-dates` | Disable legacy date format conversion | `false` |
| `--convert-dates-from-sap` | Convert SAP date formats in responses | `false` |
| `--response-metadata` | Include __metadata blocks in responses | `false` |
| `--pagination-hints` | Add pagination information to responses | `false` |
| `--max-response-size` | Maximum response size in bytes | `5MB` |
| `--max-items` | Maximum number of items in response | `100` |
| `--verbose-errors` | Provide detailed error context | `false` |
| `--claude-code-friendly, -c` | Remove $ prefix from OData parameters for Claude Code CLI compatibility | `false` |
| `--protocol-version` | Override MCP protocol version (e.g., '2025-06-18' for AI Foundry) | `2024-11-05` |
| `--forward-mcp-headers` | Forward HTTP headers from MCP connection to OData service (Streamable HTTP only) | `false` |
| `--universal` | Use single universal OData tool instead of per-entity tools (reduces context for large services) | `false` |

### Environment Variables

| Variable | Description |
|----------|-------------|
| `ODATA_SERVICE_URL` or `ODATA_URL` | OData service URL |
| `ODATA_USERNAME` or `ODATA_USER` | Username for basic auth |
| `ODATA_PASSWORD` or `ODATA_PASS` | Password for basic auth |
| `ODATA_COOKIE_FILE` | Path to cookie file |
| `ODATA_COOKIE_STRING` | Cookie string |

### .env File Support

Create a `.env` file in the working directory:

## Generated Tools

The bridge automatically generates MCP tools based on the OData service metadata:

### Entity Set Tools

For each entity set, the following tools are generated (if the entity set supports the operation):

- `filter_{EntitySet}` - List/filter entities with OData query options
- `count_{EntitySet}` - Get count of entities with optional filter
- `search_{EntitySet}` - Full-text search (if supported by the service)
- `get_{EntitySet}` - Get a single entity by key
- `create_{EntitySet}` - Create a new entity (if allowed)
- `update_{EntitySet}` - Update an existing entity (if allowed)  
- `delete_{EntitySet}` - Delete an entity (if allowed)

### Function Import Tools

Each function import is mapped to an individual tool with the function name.

### Service Information Tool

- `odata_service_info` - Get metadata and capabilities of the OData service

## Examples

### Northwind Service (v2)

### Northwind Service (v4)

### SAP OData Service

## Differences from Python Version

While maintaining the same CLI interface and functionality, this Go implementation offers:

- **Better Performance**: Native compiled binary with lower memory usage
- **Easier Deployment**: Single binary with no runtime dependencies
- **Cross-Platform**: Native binaries for Windows, macOS, and Linux
- **Type Safety**: Go's type system provides better reliability
- **Simpler Installation**: No need for Python runtime or package management

## Versioning

This project uses automatic versioning based on git tags and commit history:

- **Tagged releases**: Uses git tags (e.g., `v1.0.0`)
- **Development builds**: Uses `0.1.` format
- **Uncommitted changes**: Appends `-dirty` suffix

See [VERSIONING.md](VERSIONING.md) for detailed versioning guide.

## Releasing

This project uses automated GitHub Actions for releases. See [RELEASING.md](RELEASING.md) for the release process.

## Troubleshooting

### MCP Client Issues

If you're experiencing issues with MCP clients (Claude Desktop, RooCode, GitHub Copilot):

1. **Enable trace logging** to diagnose protocol issues:

Then check the trace file in your temp directory.

2. **Common issues and solutions**:
   - **Tools not appearing**: Ensure the service URL is correct and accessible
   - **Validation errors**: Update to the latest version which includes MCP compliance fixes
   - **Connection failures**: Check authentication credentials and network connectivity

3. **Service-specific hints**: The `odata_service_info` tool now includes automatic hints for known problematic services

See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed troubleshooting guide.

### Service Hints System

The OData MCP bridge includes a sophisticated hint system that helps users work around known service issues and provides implementation guidance.

#### Hint File Format

Create a `hints.json` file with the following structure:

#### Pattern Matching

The hint system supports wildcard patterns:
- `*` matches any sequence of characters
- `?` matches a single character
- Multiple patterns can match the same service (hints are merged by priority)

#### Default Hints

The bridge includes default hints for common services:

- **SAP OData Services** (`*/sap/opu/odata/*`): General SAP OData guidance including the critical workaround for HTTP 501 errors using `$expand`
- **SAP PO Tracking** (`*SRA020_PO_TRACKING_SRV*`): Specific hints for purchase order tracking including field formatting
- **Northwind Demo** (`*Northwind*`): Identifies the public demo service

#### Using Hints

Hints appear in the `odata_service_info` tool response under `implementation_hints`:

## Security

This project includes comprehensive security measures to prevent credential leaks. See [SECURITY.md](SECURITY.md) for details.

**Important**: Never commit `.zmcp.json` or any files containing real credentials.

## Documentation

- [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Quick command reference
- [HINTS.md](HINTS.md) - Complete guide to the service hints system
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions
- [SECURITY.md](SECURITY.md) - Security considerations
- [CHANGELOG.md](CHANGELOG.md) - Version history and changes

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

For questions and community discussion, visit our [GitHub Discussions](https://github.com/oisee/odata_mcp_go/discussions/11).

### Development

For development setup and testing:

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.