mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-05 14:52:09 +03:00
d8baf4434d
Update the seeded default compression combo to use the RTK then Caveman pipeline in both fresh installs and upgraded databases. Add a targeted migration and runtime guard that only rewrites the legacy seeded record when its original metadata and single-step pipeline still match, preserving user-customized default combos. Refresh docs and tests to reflect the stacked default and expanded RTK filter catalog.
120 lines
6.5 KiB
Markdown
120 lines
6.5 KiB
Markdown
# OmniRoute MCP Server Documentation
|
|
|
|
> Model Context Protocol server with 37 tools across routing, cache, compression, memory, skills, and proxy operations
|
|
|
|
## Installation
|
|
|
|
OmniRoute MCP is built-in. Start it with:
|
|
|
|
```bash
|
|
omniroute --mcp
|
|
```
|
|
|
|
Or via the open-sse transport:
|
|
|
|
```bash
|
|
# HTTP streamable transport (port 20130)
|
|
omniroute --dev # MCP auto-starts on /mcp endpoint
|
|
```
|
|
|
|
## IDE Configuration
|
|
|
|
See [MCP Client Configuration](SETUP_GUIDE.md#mcp-client-configuration) for Claude Desktop,
|
|
Cursor, Cline, and compatible MCP client setup.
|
|
|
|
---
|
|
|
|
## Essential Tools (8)
|
|
|
|
| Tool | Description |
|
|
| :------------------------------ | :--------------------------------------- |
|
|
| `omniroute_get_health` | Gateway health, circuit breakers, uptime |
|
|
| `omniroute_list_combos` | All configured combos with models |
|
|
| `omniroute_get_combo_metrics` | Performance metrics for a specific combo |
|
|
| `omniroute_switch_combo` | Switch active combo by ID/name |
|
|
| `omniroute_check_quota` | Quota status per provider or all |
|
|
| `omniroute_route_request` | Send a chat completion through OmniRoute |
|
|
| `omniroute_cost_report` | Cost analytics for a time period |
|
|
| `omniroute_list_models_catalog` | Full model catalog with capabilities |
|
|
|
|
## Advanced Tools (8)
|
|
|
|
| Tool | Description |
|
|
| :--------------------------------- | :---------------------------------------------------------- |
|
|
| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree |
|
|
| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions |
|
|
| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset |
|
|
| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request |
|
|
| `omniroute_get_provider_metrics` | Detailed metrics for one provider |
|
|
| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives |
|
|
| `omniroute_explain_route` | Explain a past routing decision |
|
|
| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors |
|
|
|
|
## Cache Tools (2)
|
|
|
|
| Tool | Description |
|
|
| :---------------------- | :-------------------------------------------------- |
|
|
| `omniroute_cache_stats` | Semantic cache, prompt-cache, and idempotency stats |
|
|
| `omniroute_cache_flush` | Flush cache globally or by signature/model |
|
|
|
|
## Compression Tools (5)
|
|
|
|
| Tool | Description |
|
|
| :---------------------------------- | :------------------------------------------------------------- |
|
|
| `omniroute_compression_status` | Compression settings, analytics summary, and cache-aware stats |
|
|
| `omniroute_compression_configure` | Configure compression mode, threshold, and runtime options |
|
|
| `omniroute_set_compression_engine` | Set Caveman, RTK, or stacked compression mode and pipeline |
|
|
| `omniroute_list_compression_combos` | List named compression combos and routing assignments |
|
|
| `omniroute_compression_combo_stats` | Analytics grouped by compression combo and engine |
|
|
|
|
`omniroute_compression_status` reports MCP description compression separately under
|
|
`analytics.mcpDescriptionCompression`. Those values are metadata-size estimates for MCP listable
|
|
descriptions (`tools`, `prompts`, `resources`, and `resourceTemplates`); they are not provider usage
|
|
receipts and are marked with `source: "mcp_metadata_estimate"`.
|
|
|
|
See [Compression Engines](COMPRESSION_ENGINES.md) and [RTK Compression](RTK_COMPRESSION.md) for
|
|
the runtime compression model behind these tools.
|
|
|
|
## Other Tool Groups
|
|
|
|
The remaining MCP surface includes 1proxy tools, memory tools, and skill tools. The live source of
|
|
truth is `open-sse/mcp-server/tools/` and `open-sse/mcp-server/schemas/tools.ts`.
|
|
|
|
## Authentication
|
|
|
|
MCP tools are authenticated via API key scopes. Each tool requires specific scopes:
|
|
|
|
| Scope | Tools |
|
|
| :-------------------- | :------------------------------------------------------------------- |
|
|
| `read:health` | get_health, get_provider_metrics |
|
|
| `read:combos` | list_combos, get_combo_metrics |
|
|
| `write:combos` | switch_combo |
|
|
| `read:quota` | check_quota |
|
|
| `write:route` | route_request, simulate_route, test_combo |
|
|
| `read:usage` | cost_report, get_session_snapshot, explain_route |
|
|
| `write:config` | set_budget_guard, set_resilience_profile |
|
|
| `read:models` | list_models_catalog, best_combo_for_task |
|
|
| `read:cache` | cache_stats |
|
|
| `write:cache` | cache_flush |
|
|
| `read:compression` | compression_status, list_compression_combos, compression_combo_stats |
|
|
| `write:compression` | compression_configure, set_compression_engine |
|
|
| `execute:completions` | route_request, test_combo |
|
|
|
|
## Audit Logging
|
|
|
|
Every tool call is logged to `mcp_tool_audit` with:
|
|
|
|
- Tool name, arguments, result
|
|
- Duration (ms), success/failure
|
|
- API key hash, timestamp
|
|
|
|
## Files
|
|
|
|
| File | Purpose |
|
|
| :------------------------------------------- | :------------------------------------------------ |
|
|
| `open-sse/mcp-server/server.ts` | MCP server creation and scoped tool registrations |
|
|
| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport |
|
|
| `open-sse/mcp-server/auth.ts` | API key + scope validation |
|
|
| `open-sse/mcp-server/audit.ts` | Tool call audit logging |
|
|
| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers |
|