mcp-facade

Универсальный MCP-фасад: один stdio-процесс стоит перед вышестоящим MCP-сервером и предоставляет наружу только настроенное подмножество его инструментов — со сжатыми схемами — плюс три метаинструмента (discover, describe, call), которые позволяют по запросу обращаться к остальной части каталога.

Зачем

Каждый инструмент, который предоставляет MCP-сервер, попадает в контекст модели в виде JSON-схемы в каждом запросе. «Тяжёлый» сервер с 40 инструментами может стоить десятки тысяч токенов за сессию ещё до начала работы — причём большей частью это токены за инструменты, которые вы никогда не вызываете.

Фасад меняет экономику: вы платите полные токены схемы только за те инструменты, которые действительно используете (перечисленные в used), сжаты до самой сути. Всё остальное остаётся доступным через метаинструменты, которые суммарно стоят три небольшие схемы.

Related MCP server: @zhangzwd/mcp-gateway

Как он работает

• Запускается как stdio MCP-сервер: bun run facade.ts --server <name>. Один процесс на каждый вышестоящий сервер.

• Читает facade.servers.json (рядом с facade.ts) и выбирает запись <name>.

• При первом tools/list загружает каталог вышестоящего сервера и кэширует его на диск (~/.omp/agent/mcp-facade/catalogs/<name>.json, TTL 7 дней). Подключение к вышестоящему серверу ленивое — до первого использования ничего не соединяется.

• Обслуживает каждый инструмент used со сжатой схемой:

  • каждая строка description (на уровне инструмента и внутри JSON-схемы) обрезается до первого предложения, максимум 140 символов;

  • ключи $comment, examples и default рекурсивно удаляются;

  • структура (types, properties, required, enums) остаётся нетронутой;

  • имена инструментов приводятся к нижней регистру; поиск по имени без учёта регистра.

• Всегда добавляет три метаинструмента (см. ниже).

• Если каталог не удаётся получить при tools/list, он деградирует до отдачи только метаинструментов и записывает причину в stderr.

• Пересылает вызовы вышестоящему серверу. Для HTTP-вышестоящих серверов с credentialId, ошибка 401/unauthorized/expired-token вызывает одно принудительное обновление токена и одну повторную попытку.

Метаинструменты

Типичный сценарий агента: discover "worklog" → describe addworklog → call { tool: "addworklog", args: { ... } }.

Требования

• Bun (фасад запускает TypeScript напрямую).

• Для HTTP-вышестоящих серверов, защищённых OAuth: CLI omp от OMP, установленный в ~/.bun/bin/omp, с уже авторизованными учётными данными. Фасад получает токены через omp token <credentialId> (и omp token --force-refresh <credentialId> при повторной попытке). Секреты никогда не хранятся в конфигурации.

• Для stdio-вышестоящих серверов, которым нужны переменные окружения (ключи API, токены): существующая конфигурация хоста Claude в ~/.claude.json, содержащая блок env этого сервера (см. envFrom ниже).

Установка

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

Файл facade.servers.json не отслеживается git — он может содержать локальные пути.

Конфигурация

Файл facade.servers.json сопоставляет имя сервера с его вышестоящим сервером и списком используемых инструментов:

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

Примечания:

• Записи used сопоставляются без учёта регистра и отдаются в нижнем регистре.

• envFrom в данный момент поддерживает только префикс claude:<name>.

• Пустой список used допустим: в этом случае фасад предоставляет только метаинструменты.

Регистрация у хоста

Укажите в MCP-конфигурации хоста фасад, одну запись на вышестоящий сервер:

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

⚠️ stdout — это протокол

Транспорт stdio владеет stdout. Никогда не выводите логи, диагностику или отладочные сообщения в stdout — всё, что попадает в stdout, портит поток JSON-RPC и подвешивает хост. Фасад пишет логи только в stderr (console.error); сохраняйте это поведение в любом форке.

Ограничения

• Жёстко заданные пути: каталог кэша в ~/.omp/agent/mcp-facade/catalogs/, бинарник OMP в ~/.bun/bin/omp, envFrom читает только ~/.claude.json.

• Каталог загружается одним вызовом listTools — без пагинации, без обработки tools/list_changed. Чтобы получить изменения инструментов вышестоящего сервера, перезапустите фасад (или дождитесь окончания 7-дневного TTL).

• discover — простое сопоставление подстроки, ограничено 10 результатами.

• Одна повторная попытка при сбое аутентификации; остальные ошибки вышестоящего сервера передаются как есть.

• Не поддерживаются промпты, ресурсы и семплинг вышестоящего сервера — только инструменты.