Сервер Exir MCP

Многопользовательский шлюз Model Context Protocol, который располагается между MCP-хостами (Claude, ChatGPT или любой другой MCP-совместимый агент) и API Exir CRM (Perfex CRM под капотом).

                    ┌──────────────────────┐
                    │   ChatGPT / Agent     │
                    │ Claude / Other Host   │
                    └──────────┬────────────┘
                               │
                         MCP / HTTPS
                               │
                               ▼
              ┌────────────────────────────────┐
              │        Exir MCP Server          │
              │                                 │
              │ OAuth 2.1 / OIDC                │
              │ Tenant Resolver                 │
              │ Permission Engine               │
              │ Tool Registry                   │
              │ Audit Logger                    │
              │ Rate Limiter                    │
              │ Input Validation                │
              └───────────────┬─────────────────┘
                               │
                        Internal API
                               │
                               ▼
              ┌────────────────────────────────┐
              │          Exir CRM API           │
              │                                 │
              │ Customers / Leads / Sales       │
              │ Tasks / Projects / Tickets      │
              │ Invoices / Contracts / ...      │
              └───────────────┬─────────────────┘
                               │
                               ▼
                    ┌──────────────────┐
                    │ Customer Tenant   │
                    │ Data / Database   │
                    └──────────────────┘

Как обрабатывается запрос

1. Транспорт — MCP-хост отправляет POST /mcp (Streamable HTTP) запрос с Bearer токеном доступа.

2. OAuth 2.1 / OIDC (src/auth/oidc.ts) — подпись токена, издатель, аудитория и срок действия проверяются с помощью JWKS-ключей поставщика удостоверений. Непроверенные токены никогда не достигают слоёв ниже.

3. Резолвер тенантов (src/tenant/tenantResolver.ts) — идентификатор тенанта считывается из утверждения (claim) в проверенном токене и сопоставляется с подключением к Exir CRM этого тенанта (base URL + API key). Запросы никогда не могут пересекать границы тенантов.

4. Ограничитель запросов (src/middleware/rateLimiter.ts) — запросы ограничиваются для каждого тенанта, чтобы один шумный вызывающий не мог лишить ресурсов другого в рамках общего развёртывания.

5. Реестр инструментов (src/tools/) — MCP-сервер для этого запроса создаётся путём оборачивания каждого зарегистрированного инструмента (src/mcp/server.ts) с помощью:

   • Механизма разрешений (src/permissions/permissionEngine.ts) — проверяет OAuth-скоупы токена на соответствие требуемому скоупу инструмента.

   • Проверки входных данных — каждый инструмент объявляет zod схему; недопустимые входные данные отклоняются до обращения к CRM.

   • Журнала аудита (src/audit/auditLogger.ts) — каждый вызов (разрешённый, отклонённый, успешный или ошибочный) записывается с указанием тенанта, субъекта, имени инструмента и результата.

6. Внутренний API (src/crm/perfexClient.ts) — HTTP-клиент в рамках тенанта вызывает реальный API Exir CRM (REST API Perfex CRM, аутентификация через заголовок authtoken) и возвращает результат обратно вверх по цепочке как выходные данные инструмента.

Related MCP server: Nervora

Структура проекта

src/
  auth/oidc.ts            OAuth 2.1 / OIDC bearer-token verification
  tenant/tenantResolver.ts Tenant lookup + per-tenant CRM connection details
  permissions/permissionEngine.ts  Scope-based authorization
  audit/auditLogger.ts     Structured audit trail for every tool call
  middleware/rateLimiter.ts Per-tenant rate limiting
  crm/perfexClient.ts      Internal API client to the Exir CRM API
  tools/                   Tool Registry + one file per CRM domain
    customers.ts leads.ts tasks.ts invoices.ts
  mcp/server.ts            Wires tools -> permissions -> validation -> audit -> CRM
  http/app.ts              Express app: /healthz, POST /mcp
  index.ts                 Process entrypoint
tests/                     Vitest unit tests (permission engine, tool registry)

Начало работы

npm install
cp .env.example .env   # fill in OIDC_ISSUER, CRM_API_BASE_URL, CRM_API_KEY, ...
npm run dev             # ts-node/tsx dev server on :3333

Сборка и запуск для продакшена:

npm run build
npm start

Или через Docker:

docker compose up --build

Запуск тестов:

npm test

Добавление нового инструмента

1. Добавьте вызов registry.register({...}) в соответствующий файл в src/tools/ (или создайте новый файл для новой предметной области CRM) с указанием name, description, requiredScope, zod inputSchema и handler(crm, input), который вызывает PerfexClient.

2. Если это новый файл, подключите его в buildToolRegistry() в src/tools/index.ts.

3. Добавьте тест в tests/tools.test.ts, проверяющий, что инструмент зарегистрирован и его схема отклоняет некорректные входные данные.

Больше никаких изменений не требуется — разрешения, проверка и аудит применяются автоматически к каждому зарегистрированному инструменту через src/mcp/server.ts.

Мультитенантность

src/tenant/tenantResolver.ts поставляется с запасным вариантом EnvTenantStore для разработки, который сопоставляет каждый идентификатор тенанта с единственным подключением к CRM из .env. Для реальных мультитенантных развёртываний реализуйте интерфейс TenantStore на основе вашего каталога тенантов (Postgres, конфигурационный сервис и т.д.), сопоставляя идентификатор тенанта -> { baseUrl, apiKey }, и передайте его в tenantResolver(myStore) в src/http/app.ts.

Заметки по безопасности

• Идентификатор тенанта всегда берётся только из утверждения в криптографически проверенном токене доступа, никогда — из заголовка, предоставленного клиентом, если только TENANT_HEADER_FALLBACK=true не задан явно для доверенных внутренних вызывающих (например, при локальной разработке).

• Ключи API CRM для каждого тенанта никогда не логируются (src/logger.ts скрывает Authorization, *.apiKey, *.token).

• Каждый вызов инструмента проверяется дважды: сначала MCP SDK по JSON-схеме инструмента, затем zod.safeParse внутри обработчика, прежде чем будет сделан любой запрос к CRM API.

• Сервер работает без сохранения состояния (sessionIdGenerator: undefined): новый экземпляр MCP-сервера создаётся для каждого HTTP-запроса в рамках проверенного тенанта и его разрешений, поэтому общее состояние сессии между тенантами отсутствует.