MCP Router Gateway & Semantic Proxy

A C# ASP.NET Core gateway router, OAuth 2.0 provider, and semantic proxy for the Model Context Protocol (MCP).

mcp-router aggregates backend MCP servers (Docker, Plex, Home Assistant, Actual Budget, Excel) and proxies them to clients via a single unified connection.

---

🌟 Key Features

• MCP 2026-07-28 Spec Support: Spec-compliant header annotation; routing is body/path based (Mcp-Method & Mcp-Name) via McpDualSpecMiddleware with legacy JSON body fallback.
• Dynamic Docker Auto-Discovery: Mounts /var/run/docker.sock to automatically discover and register backend MCP containers labeled with mcp.enabled=true, mcp.id, mcp.port, and mcp.categories (see docs/features-guide.md).
• Pluggable Identity Providers: Dual authentication support for Active Directory (Kerberos/NTLM Windows SIDs) and OIDC / Reverse Proxy Headers (Remote-User, Remote-Groups headers from Authentik, Authelia, PocketID, Keycloak, etc.).
• Pluggable Secret Retrievers: Fetch downstream server API keys and tokens dynamically from HashiCorp Vault (KV v2), Windows Registry (DPAPI), or Environment Variables per server (SecretProvider column).
• Windows Enterprise Hosting & Automation: First-class support for IIS In-Process (AspNetCoreModuleV2) with unbuffered SSE streaming (responseBufferLimit="0"), Managed Windows Services with SCM crash auto-recovery, Windows DPAPI registry secrets, and automated PowerShell deployment toolkits. See docs/windows-deployment-and-validation-guide.md.
• Multi-Database & Stored Procedure Engine: Complete stored procedure suites for MS SQL Server (Microsoft.Data.SqlClient), MySQL (MySqlConnector), and SQLite (Microsoft.Data.Sqlite) using Dapper. See docs/database-providers.md.
• Observability & PII Audit Logging: Automatic payload redaction of Bearer tokens, API keys, and passwords (PiiSanitizer) paired with stored procedure audit logging (sp_InsertAuditLog).
• Consolidated Tools Gateway: Merges 300+ tools from dozens of isolated backend servers into a single endpoint.
• Meta-Mode Dynamic Tool Filtering:
  • Defaults to Meta-Mode on the main /sse connection path to prevent context window bloat and tool confusion.
  • Instantly returns only two bootstrap tools: search_tools and execute_tool.
  • Asynchronously warms backend caches in the background using a thread-safe, single-execution initialization lock.
  • Performs semantic scoring and ranking of backend tools on-demand when search_tools is called.
• Dual-Provider Semantic Search:
  • Local ONNX (In-Process): CPU-friendly vector embeddings using a local all-MiniLM-L6-v2 model and Microsoft.ML.Tokenizers (no external APIs). Automatically downloads model/vocab files into persistent volumes.
  • API Provider: OpenAI-compatible embedding calls (LiteLLM, Open WebUI, OpenAI, etc.).
  • Secure DB Storage: Embedding configurations and API keys are stored securely inside the SQLCipher-encrypted SQLite database.
• Developer Test Bench & Dashboard:
  • Interactive UI: Form builder renders interactive input controls directly from tools' JSON schema specs.
  • Logs Console: Styled real-time terminal rendering thread-safe in-memory gateway logs.
  • Search Simulator: Real-time evaluation panel for intent ranking.
  • Provider Management Controls: Interactive UI cards in Settings to toggle and configure Auth and Secret providers.
• Target-Specific Proxying: Exposes separate endpoints (/{targetServerId}) to route directly to specific backends (e.g., /plex, /docker).
• OAuth 2.0 Security & CORS Config: Integrates a lightweight OAuth 2.0 authorization server for secure API access. Leverages strict, configurable CORS protection with CORS_ALLOWED_ORIGINS to prevent cross-origin request hijacking / forgery vulnerabilities.
• Built-in Web Dashboard: A responsive, dark-mode, glassmorphic UI to monitor connected clients, stats, and backend health status.

---

🎯 Evaluation & Product Overview Guide

For details on context window management, STDIO secret security, authorization, and reverse proxy comparisons, see:

• Evaluation & Product Overview Guide

---

🏛️ Comprehensive Architecture & Specification Guide

For architectural specifications, Mermaid sequence diagrams, component models, ERDs, authorization flows, transport lifecycles, and AES-256-GCM encryption pipelines, see:

• Comprehensive Enterprise Architecture Guide
• Executive Architecture Overview

---

📖 Official User Guide & Manual

For UI guides, server registration, secret provider configuration, RBAC, client setup, and test bench operations, see:

• Official User Guide Suite
  • 01. Dashboard & Navigation Interface
  • 02. Server Management & Secret Providers
  • 03. RBAC, Security & Approvals
  • 04. Client Setup & App Key Management
  • 05. Interactive Test Bench
  • 06. System Settings & Vector Embeddings

---

💻 Developer & Operations Guides

For setup, testing, production deployment, database management, observability, and disaster recovery:

• Developer Guide & Local Setup
• Windows Deployment & Validation Guide
• Software Requirements Specification (SRS) & Test Catalog
• Test Catalog & Annotation Developer Guide
• Operations & Production Runbook
• Contributing Guide

---

🚀 Transport Capability & Configuration Guide

For an in-depth breakdown of downstream transports (sse, http/streamable, stdio, target proxying /{targetServerId}), subprocess STDIO security policies, environment variable secret injection, process tree lifecycle management, SSE concurrency/ID isolation, configuration examples, and troubleshooting procedures, see docs/transports.md.

---

🔑 AppKey Scopes & Authorization Guide

For complete scope syntax grammar (*, server:*, category:*, tool:*, prompt:*, resource:*), multi-stage pipeline evaluation rules, the capability authorization matrix, cryptographic token hashing, and least-privilege persona recipes, see the canonical AppKey Scopes & Authorization Guide.

---

🔐 Enterprise Secret Providers & Key Management Guide

For detailed documentation on supported secret providers (HashiCorp Vault KV v2 with JIT renewal, Windows Registry DPAPI, Environment Variables), AES-256-GCM encryption at rest, dynamic runtime reloading, audit safety, and Docker Compose setup snippets, see docs/secret-providers.md.

---

🗄️ Database Provider Support, Data Model & ERD

For complete dialect specifications across SQLite, Microsoft SQL Server, and MySQL, the complete 12-table Canonical Data Model & Database ERD, stored procedure suites (sp_*), AES-256-GCM envelope encryption, and Docker Compose deployment recipes, see:

• Canonical Data Model & Database ERD
• Database Provider Support & Deployment Matrix

---

📡 Features & Usage Guide

For deep technical walkthroughs, setup configuration examples, connection guidelines, secret retrievers, and usage instructions for the Web UI/Test Bench, see docs/features-guide.md.

---

🤖 Client Agent Integration Guidelines

When using agentic coding assistants (such as Antigravity/AGY) connected to this gateway, the agent should follow these core patterns:

1. Bootstrap Search (Meta-Mode): By default, the gateway hides all underlying tools to prevent context bloat. The agent must first query search_tools with a natural language query describing the desired action (e.g., "restart actual budget container").
2. Namespaced Execution: After search_tools returns matching namespaced tools (e.g. docker__restart_container), the agent must invoke it via execute_tool(name, arguments).
3. Semantic Knowledge Retrieval (notes-rag): AI agents MUST query the notes-rag service first (using the search_notes tool) for system architecture or setup questions before attempting to grep the filesystem. This leverages the local SilverBullet/Obsidian notes database.

---

📜 Release Changelog

For complete release history and version logs, see CHANGELOG.md.

Version	Release Date	Summary of Key Changes
v4.18.1	2026-08-18	fix(ci): fix frontend test assertions, preserve provider display names, and update test catalog
v4.18.0	2026-08-18	feat(ui): implement dynamic DB-backed dashboard branding customization and CSS variable centralization
v4.17.6	2026-08-17	docs(refactor): refine documentation for conciseness and add pitch deck
v4.17.5	2026-08-17	chore(release): bump version to 4.17.5 and align verification badges
v4.17.4	2026-08-17	test(coverage): close frontend unit, Playwright E2E, and live MySQL repository coverage gaps

---

🧪 Code Coverage & Quality Gates

Our core modules maintain high code coverage and automated CI quality gates on pull requests and pushes to main. For the complete breakdown and documentation, see:

• Software Requirements Specification & Test Verification Catalog
• Test Catalog Developer & Annotation Guide
• CI Quality Gates & Security Scanning Guide
• Detailed Code Coverage Report

Module	Line Coverage	Branch Coverage	Status
Core Session	92.4%	88.1%	🟢 Passing
Routing Engine	89.7%	85.3%	🟢 Passing
Controllers	94.2%	91.0%	🟢 Passing
Security & Providers	98.5%	95.8%	🟢 Passing
CI Quality Gates	100%	100%	🟢 Passing

---

🛠️ Contributor & Developer Guide

For complete developer onboarding, environment setup, testing protocols, and release verification, see docs/developer-guide.md.

Quick Quality & Release Verification

Run the unified verification engine locally before creating pull requests:

./scripts/verify-release.sh

C# Backend (Roslyn & .NET Analyzers)

• EditorConfig: Supported globally across C#, TSX, JSON, and YAML. Indentation is 4 spaces for C# and 2 spaces for web files.
• Analysis Policy: Rules are configured via Directory.Build.props at the workspace root, applying implicit usings, nullable context, deterministic builds, and latest-recommended Roslyn analyzers.
• Verification Command:

  dotnet format McpRouter.slnx --verify-no-changes

TypeScript / React Frontend (ESLint Flat Config)

• ESLint v10: Managed via flat configuration (frontend/eslint.config.js) supporting React 19, TypeScript-ESLint, and React Hooks/Refresh checks.
• Verification Command:

  cd frontend
  npm run lint