mcp-facade

Eine generische MCP-Fassade: Ein stdio-Prozess läuft vor einem vorgelagerten MCP-Server und legt nur eine konfigurierte Teilmenge seiner Tools offen – mit kompaktierten Schemas – sowie drei Meta-Tools (discover, describe, call), die den Rest des Katalogs bei Bedarf erreichbar halten.

Warum

Jedes Tool, das ein MCP-Server bereitstellt, wird bei jeder Anfrage als JSON-Schema in den Kontext des Modells gespielt. Ein üppiger Server mit 40 Tools kann pro Sitzung Zehntausende von Tokens kosten, bevor überhaupt etwas passiert – der größte Teil davon für Tools, die du nie aufrufst.

Die Fassade dreht die Rechnung um: Volle Schema-Tokens zahlst du nur für die Tools, die du tatsächlich nutzt (in used aufgeführt), kompaktiert auf das Wesentliche. Alles andere bleibt über die Meta-Tools erreichbar, die zusammen nur drei kleine Schemas benötigen.

Related MCP server: @zhangzwd/mcp-gateway

Was die Fassade tut

• Läuft als stdio-MCP-Server: bun run facade.ts --server <name>. Ein Prozess für jeden vorgelagerten Server.

• Liest facade.servers.json (neben facade.ts) und wählt den Eintrag <name> aus.

• Beim ersten tools/list wird der Katalog des Upstream abgerufen und auf der Platte gecacht: ~/.omp/agent/mcp-facade/catalogs/<name>.json, TTL: 7 Tage. Die Verbindung zum Upstream ist lazy aufgebaut – erst bei der tatsächlichen Nutzung wird eine Verbindung hergestellt.

• Stellt jedes in used genannte Tool mit einem kompaktierten Schema bereit:

  • Jede description-Zeichenfolge wir mit einzelnen Sätzen gekürzt, maximal 140 Zeichen;

  • $comment, examples und default werden rekursiv verworfen;

  • Struktur (type, properties, required, enums) bleibt unverändert;

  • Tool-Namen in Kleinbuchstaben; Suche unabhängig von Groß-/Kleinschreibung.

• Hängt immer die drei Meta-Werkzeuge (siehe unten) an.

• Falls der Katalog beim tools/list nicht abgefragt werden kann, liefert die Fassade nur die Meta-Werkzeuge aus und protokolliert die Ursache auf stderr.

• Leitet Aufrufe an den Upstream weiter. Bei HTTP-Upstreams mit einem credentialId führt ein 401/unauthorized/expired-token Fehler zu einem erzwungenen Token-Refresh und einem weiteren Versuch.

Die Meta-Werkzeuge

Typischer Ablauf des Agenten: discover "werklog" → describe addworklog → call { tool: "addworklog", args: { ... } } (Quellcode-Original beibehalten).

Voraussetzungen

• Bun (die Fassade führt TypeScript direkt aus).

• Für OAuth-geschützte HTTP-Upstreams: OMP CLI bei ~/.bun/bin/omp, besagte Anmeldeinformationen bereits autorisiert. Die Fassade holt Tokens über omp token <credentialId> und omp token --force-refresh <credentialId> beim Retry; Secrets nie mit speichern.

• Für stdio-Upstreams mit Umgebungsvariablen (API-Keys, Tokens): bestehende Claude-Host-Konfiguration unter ~/.claude.json mit dem Env-Block env des Servers (siehe envFrom unten).

Install

bun install
cp facade.servers.example.json facade.servers.json   # then edit

facade.servers.json wird nicht in die Versionskontrolle (.gitignore) aufgenommen – sie darf lokale Pfade enthalten.

Konfiguration

facade.servers.json ordnet einem Servernamen den Upstream und die Liste der verwendeten Tools-Tools zu:

{
  "<name>": {
    "upstream": {
      // HTTP upstream (Streamable HTTP transport):
      "url": "https://mcp.example.com/v1/mcp",
      "credentialId": "mcp_oauth:profile:default:https://mcp.example.com/v1/mcp" // optional

      // …or stdio upstream:
      // "command": "/usr/local/bin/npx",
      // "args": ["-y", "@example/mcp-server"],
      // "envFrom": "claude:<server-name>",  // optional: pull env from ~/.claude.json mcpServers.<server-name>.env
      // "env": { "EXTRA": "value" }          // optional: merged on top
    },
    "used": ["tool_one", "tool_two"]  // exposed directly; everything else via meta-tools
  }
}

Hinweise:

• used-Einträge werden fallweise zugeordnet und in Kleinbuchstaben gespeichert.

• envFrom unterstützt aktuell nur das Präfix claude:<name>.

• Eine leere used-Liste ist gültig: Die Fassade offen dann nur Meta-Werkzeuge.

Beim Host registrieren

Weise die Host-MCP-Konfiguration dem Innenbereit der Fassade zu – ein Eintrag pro vorgelagerten Server:

{
  "mcpServers": {
    "acme": {
      "command": "/path/to/bun",
      "args": ["run", "/path/to/mcp-facade/facade.ts", "--server", "acme-http"]
    }
  }
}

⚠️ stdout ist das Protokoll

Der stdio-Transport besitzt stdout. Schreiben Sie niemals Protokolle, Diagnostic- oder Debug-Daten dazu – was etwas auf stdout landet, zerstört den JSON-RPC-Stream und blockiert den Host (stdout). Die Fassade protokolliert nur auf stderr (console.error); in jedem Fork so beibehalten.

Einschränkungen

• Feste Pfade: Katalog-Cache unter ~/.omp/agent/mcp-facade/catalogs/, OMP-BINARY in ~/.bun/bin/omp; envFrom nur für ~/.claude.json.

• Der Katalog wird mit einzelnem listTools-Aufruf geladen – keine Paginierung, keine Bearbeitung von tools/list_changed. Die Fassade neu starten oder die 7-Tage-TTL abwarten, um Upstream-Änderungen zu aktualisieren.

• discover ist ein einfacher Teilstring-Math, begrenzt auf 10 Treffer.

• Bei Auth-Fehlern ein einziger Retry; andere Upstream-Fehler werden unverändert weitergegeben.

• Keine Unterstützung für upstream-Aufforderung, Ressourcen oder Abtastung – nur Tools.