mcp-suite

Сервер MCP на TypeScript промышленного уровня, предоставляющий ИИ-агентам (Claude Desktop, Cursor, Windsurf, пользовательские агенты) структурированный доступ к реальным данным в четырех областях: финансовые рынки, Web3/DeFi, инструменты разработки и здравоохранение (FHIR).

• Приоритет аутентификации — проверка JWT включена по умолчанию

• Изоляция доменов — отсутствие ключей API отключает только один домен, а не весь сервер

• Кэш ответов (LRU + TTL) и ограничение частоты запросов (token-bucket) для каждого домена

• Типизированные схемы (Zod) для всех входных и выходных данных инструментов

• Два транспорта: stdio (локальный) и HTTP + SSE (удаленный/хостинг)

Быстрый старт

# Run directly (no global install required)
npx mcp-suite

# Or install globally
npm install -g mcp-suite
mcp-suite

Требования: Node.js ≥ 20, npm ≥ 10

Установка

1. Настройка переменных окружения

Скопируйте .env.example в .env и заполните ключи для доменов, которые вы хотите включить:

cp .env.example .env

# Authentication (required in production)
MCP_JWT_SECRET=your-secret-here

# Financial Markets (Alpha Vantage + CoinGecko)
ALPHA_VANTAGE_API_KEY=

# Web3 / DeFi (Alchemy + OpenSea + Blur)
ALCHEMY_API_KEY=
OPENSEA_API_KEY=

# Developer Tools (GitHub)
GITHUB_TOKEN=

# Healthcare / FHIR (optional — defaults to public HAPI sandbox)
FHIR_BASE_URL=https://hapi.fhir.org/baseR4

# Server
LOG_LEVEL=info         # debug | info | warn | error
MCP_PORT=3000          # HTTP transport only
AUTH_DISABLED=false    # set true for local dev only

Вам нужны ключи только для тех доменов, которые вы используете. Домены с отсутствующими ключами молча отключаются при запуске.

2. Генерация токена для разработки

npx mcp-suite gen-token
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. Добавление в Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "mcp-suite": {
      "command": "npx",
      "args": ["mcp-suite"],
      "env": {
        "MCP_JWT_SECRET": "your-secret-here",
        "ALPHA_VANTAGE_API_KEY": "...",
        "ALCHEMY_API_KEY": "...",
        "OPENSEA_API_KEY": "...",
        "GITHUB_TOKEN": "..."
      }
    }
  }
}

4. Запуск в качестве HTTP-сервера (удаленные/хостинг-развертывания)

npx mcp-suite --transport http --port 3000

Это открывает GET /health, GET /tools и конечную точку SSE для удаленных клиентов MCP.

Команды CLI

Доступные инструменты

Финансовые рынки

Работает на базе Alpha Vantage и CoinGecko. Требуется: ALPHA_VANTAGE_API_KEY

Пример:

{ "tool": "get_stock_quote", "arguments": { "ticker": "NVDA" } }

Web3 / DeFi

Работает на базе Alchemy, OpenSea и Blur. Требуется: ALCHEMY_API_KEY, OPENSEA_API_KEY

Пример:

{ "tool": "get_nft_floor", "arguments": { "collection_slug": "boredapeyachtclub" } }

Инструменты разработки

Работает на базе GitHub API. Требуется: GITHUB_TOKEN

Пример:

{ "tool": "get_pipeline_status", "arguments": { "repo": "vercel/next.js", "branch": "canary" } }

Здравоохранение (FHIR)

Работает на базе HAPI FHIR R4. Требуется: ничего (по умолчанию используется публичная песочница) или FHIR_BASE_URL для пользовательских конечных точек.

Уведомление HIPAA: Все инструменты здравоохранения подключаются к публичной песочнице только с синтетическими данными. Реальная информация о здоровье пациентов (PHI) не используется. Для промышленного использования замените FHIR_BASE_URL на конечную точку EHR, соответствующую требованиям HIPAA, и настройте соответствующие учетные данные SMART on FHIR OAuth 2.0.

Пример:

{ "tool": "lookup_patient", "arguments": { "name": "Smith", "birth_date": "1980-01-15" } }

Аутентификация

Аутентификация включена по умолчанию. Каждый вызов инструмента должен содержать действительный JWT.

Промышленная эксплуатация

Установите MCP_JWT_SECRET в качестве надежного секретного ключа. Сервер отказывается запускаться в промышленном режиме без него.

Разработка

Вариант А — полное отключение аутентификации (только локально):

AUTH_DISABLED=true

Вариант Б — использование JWT для разработки:

npx mcp-suite gen-token

Передайте сгенерированный токен в поле _meta запроса MCP (stdio) или в заголовке Authorization: Bearer (HTTP).

Структура JWT

{
  "sub": "your-client-id",
  "scope": "mcp:tools",
  "iat": 1713484800,
  "exp": 1716076800
}

Архитектура

MCP Clients (Claude Desktop · Cursor · Windsurf · Custom Agents)
        │  MCP Protocol
┌───────▼────────────────────────────────────────┐
│  Transport Layer  (stdio  |  HTTP + SSE)        │
├────────────────────────────────────────────────┤
│  Auth Middleware  (JWT validation / bypass)     │
├────────────────────────────────────────────────┤
│  Tool Registry    (register · list · route)     │
├──────────┬──────────┬──────────┬───────────────┤
│Financial │  Web3    │ DevTools │  Healthcare   │
├──────────┴──────────┴──────────┴───────────────┤
│  Shared: Rate Limiter · Cache · Logger · Errors │
└─────────────────────────────────────────────────┘
         │           │          │          │
   Alpha Vantage  Alchemy   GitHub API  HAPI FHIR
   CoinGecko      OpenSea
                  Blur

• Кэширование: Внутрипроцессный кэш LRU + TTL (node-cache). TTL соответствуют доменам (15с для криптовалют, 300с для статистики репозиториев GitHub).

• Ограничение частоты запросов: Token-bucket для каждого домена защищает квоты API бесплатного уровня.

• Типы ошибок: AuthError, ValidationError, DomainUnavailableError, UpstreamError, RateLimitError — все они создают структурированные ответы об ошибках MCP.

• Логирование: Структурированный JSON для каждого вызова инструмента: домен, имя инструмента, задержка, попадание в кэш, статус.

Добавление домена

Каждый домен следует одному и тому же шаблону. Чтобы добавить новый домен:

1. Создайте src/domains/[name]/ с файлами index.ts, schemas.ts, client.ts и папкой tools/

2. Экспортируйте объект Domain:

export const myDomain: Domain = {
  name: 'my-domain',
  isAvailable: () => !!config.MY_API_KEY,
  registerTools: (server) => { /* server.tool(...) calls */ }
}

3. Зарегистрируйте его в src/server.ts

4. Задокументируйте инструменты в docs/API.md

См. docs/TDD.md §5 и docs/CODING_STANDARDS.md для полного описания шаблона.

Разработка

git clone https://github.com/ayenisholah/mcp-suite.git
cd mcp-suite
npm install
cp .env.example .env   # fill in your API keys

npm run build          # compile TypeScript → dist/
npm run dev            # watch mode
npm run typecheck      # type check without emit
npm run lint           # ESLint
npm test               # unit tests (Vitest)
npm run test:coverage  # tests + coverage report

# Integration tests — hits real APIs, requires .env keys
RUN_INTEGRATION=true npm test

Конечные точки транспорта HTTP

При запуске с параметром --transport http:

Справочник ошибок

Лицензия

MIT — см. LICENSE

Участие в разработке

Приветствуются сообщения об ошибках и PR. Пожалуйста, прочитайте docs/CODING_STANDARDS.md перед отправкой.