Serve7 MCP Connector Library

Переиспользуемые MCP инструменты для Amazon Connect AI Agents и Bedrock AgentCore. Семь универсальных коннекторов — поиск клиента, создание обращения в техподдержку, проверка статуса обращения, запись на приём, обновление записи в CRM, получение знаний и создание задачи — написаны один раз здесь и затем переиспользуются во всех сценариях взаимодействия Serve7 с клиентами, вместо того чтобы собирать их с нуля для каждого проекта.

Это проект #6 из списка идей кооп-программы осени 2026 года («Serve7 MCP Connector Library»). Это рабочая первая версия: каждый коннектор уже сегодня работает по полному циклу end-to-end против in-memory мок-бэкенда (для запуска не нужны AWS-аккаунт, настоящая CRM или какие-либо учётные данные), с чистой точкой стыка для замены на реальный бэкенд позже.

Почему адаптер, а не прямая интеграция

Бизнес-логика каждого коннектора (валидация схемы, что считается ошибкой, какие поля входят и выходят) находится в src/connectors/*.ts и никогда не обращается напрямую к конкретному бэкенд-токенодактора. Вместо этого она вызывает один из пяти небольших интерфейсов в src/adapters/types.ts — CrmAdapter, TicketingAdapter, SchedulingAdapter, KnowledgeAdapter, TaskAdapter. Сегодня все они реализованы как моки в памяти (src/adapters/mock.ts). Завтра подключение реального бэкенда Salesforce/ServiceNow/Connect-Cases/Bedrock-Knowledge-Base означает написание одного нового класса адаптера и переключение одного switch-оператора (src/adapters/index.ts) — без изменений в коде коннектора, его тестах и определениях MCP-инструментов, которые видит агент. См. docs/adding-a-real-adapter.md.

MCP client (Claude Desktop, Bedrock AgentCore, ...)
        │  tool call: customer_lookup({ customerId: "cust-1001" })
        ▼
src/server.ts (stdio) or src/http-server.ts (deployed)
        │  registers every connector as an MCP tool
        ▼
src/connectors/customer-lookup.ts
        │  validates input (zod), calls adapters.crm.lookupCustomer(...)
        ▼
src/adapters/index.ts  →  mock.ts today, a real adapter later

Related MCP server: Runtime MCP Server

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

src/
  connectors/       one file per MCP tool — schema + business logic only
  adapters/          the CRM/ticketing/scheduling/knowledge/task interfaces,
                      plus the in-memory mock implementations
  mock-data/         seed data the mock adapters serve
  mcp-server-factory.ts   registers every connector on an McpServer instance
  server.ts          stdio entrypoint (local dev, Claude Desktop, Claude Code)
  http-server.ts      Streamable-HTTP entrypoint (deployed, e.g. behind Lambda)
tests/               one test file per connector + a registry sanity test
deploy/              Dockerfile + AWS SAM template for a Lambda deployment
docs/                per-connector reference + how to add a real adapter

Запуск в локальном окружении

npm install
npm test              # 29 tests, all against the mock adapters
npm run typecheck      # strict TypeScript, zero `any` in connector code
npm start              # stdio MCP server — Ctrl+C to stop
npm run start:http      # HTTP MCP server on :8080 (curl http://localhost:8080/health)
npm run smoke           # real MCP client over stdio, calls all 7 tools end to end
npm run smoke:http      # same, over HTTP — start:http must be running first

Подключение в Claude Desktop / Claude Code

Укажите MCP-клиенту на stdio-сервер, например в конфигурационном файле Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "serve7-connectors": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/serve7-mcp-connectors/src/server.ts"]
    }
  }
}

После этого попросите что-нибудь вроде «найди клиента cust-1001» или «какие статьи базы знаний есть по экстренным объявлениям о закрытии?» — он вызовет customer_lookup / retrieve_knowledge и вернёт данные из мока.

Развёртывание для реального использования (например, из Bedrock AgentCore)

См. deploy/README.md — создание Lambda-функции из контейнерного образа за Function URL с IAM-аутентификацией с помощью sam deploy.

Как добавить восьмой коннектор

1. Создайте src/connectors/my-new-tool.ts и используйте defineConnector() — скопируйте структуру существующего коннектора, например create-task.ts.

2. Добавьте его в массив CONNECTORS в src/connectors/index.ts.

3. Добавьте тестовый файл в tests/.

4. Опишите его в docs/connectors.md.

server.ts, http-server.ts и тест реестра подхватят его автоматически — больше ничего трогать не надо.

Что намеренно осталось за рамкам этой первой версии

Согласно исходному техническому заданию, каждый коннектор должен в итоге покрывать также подход к аутентификации (готово, на уровне адаптера), шаблон развёртывания (готово, deploy/) и документацию (готово, docs/) — всё уже в поставке. Пока не сделано, но имеет смысл быстрым следующим шагом: реальный адаптер хотя бы для одного бэкенда (чтобы проект перестал быть полностью моковым) и подключение живого агента Bedrock AgentCore, который сможет вызывать коннектор через развернутый HTTP-эндпоинт в сквозном сценарии.