mcp-suite
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
Related MCP server: APIbase
Установка
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
Команда | Описание |
| Запуск сервера (транспорт stdio, по умолчанию) |
| Запуск сервера HTTP + SSE |
| Генерация JWT для разработки |
| Вывод всех активных инструментов, сгруппированных по доменам |
Доступные инструменты
Финансовые рынки
Работает на базе Alpha Vantage и CoinGecko.
Требуется: ALPHA_VANTAGE_API_KEY
Инструмент | Описание |
| Цена акций США, объем, изменение в % |
| Обменный курс валютной пары (ISO 4217) |
| Цена криптовалюты, рыночная капитализация, изменение за 24ч |
| Финансовые заголовки с оценками тональности |
Пример:
{ "tool": "get_stock_quote", "arguments": { "ticker": "NVDA" } }Web3 / DeFi
Работает на базе Alchemy, OpenSea и Blur.
Требуется: ALCHEMY_API_KEY, OPENSEA_API_KEY
Инструмент | Описание |
| Лучшая минимальная цена на OpenSea + Blur (ETH, Base, Arbitrum) |
| Последние N продаж с характеристиками и маркетплейсом |
| Мультичейн-токены + владения NFT, разрешение ENS |
| Резервы пулов Uniswap V2/V3 и ценовое соотношение |
| Оценки проскальзывания сделок по объему |
Пример:
{ "tool": "get_nft_floor", "arguments": { "collection_slug": "boredapeyachtclub" } }Инструменты разработки
Работает на базе GitHub API.
Требуется: GITHUB_TOKEN
Инструмент | Описание |
| Звезды, форки, тикеты, язык, последний коммит |
| Сводка diff PR, рецензенты, проверки CI, статус слияния |
| Последние запуски GitHub Actions по веткам |
| URL активного развертывания и статус |
Пример:
{ "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 для каждого вызова инструмента: домен, имя инструмента, задержка, попадание в кэш, статус.
Добавление домена
Каждый домен следует одному и тому же шаблону. Чтобы добавить новый домен:
Создайте
src/domains/[name]/с файламиindex.ts,schemas.ts,client.tsи папкойtools/Экспортируйте объект
Domain:
export const myDomain: Domain = {
name: 'my-domain',
isAvailable: () => !!config.MY_API_KEY,
registerTools: (server) => { /* server.tool(...) calls */ }
}Зарегистрируйте его в
src/server.tsЗадокументируйте инструменты в
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:
Конечная точка | Аутентификация | Описание |
| Нет | Статус доступности по доменам |
| Да | Все зарегистрированные инструменты, сгруппированные по доменам |
| Да | Конечная точка протокола MCP (SSE) |
Справочник ошибок
Код | Описание |
| JWT отсутствует, истек срок действия или неверная подпись |
| Входные данные не прошли проверку схемы Zod |
| Ключ API домена не настроен при запуске |
| Превышен лимит запросов для домена |
| Внешний API вернул ошибку или истекло время ожидания |
Лицензия
MIT — см. LICENSE
Участие в разработке
Приветствуются сообщения об ошибках и PR. Пожалуйста, прочитайте docs/CODING_STANDARDS.md перед отправкой.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Hosted MCP server for live public-data APIs and Skills for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Discover and call 10,000+ production APIs from one MCP server. Pay-per-call billing for AI agents.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceA production-ready TypeScript MCP server providing basic tools (add, echo, timestamp), resources (server info, greetings, data access), and prompt templates (analyze, code-review, summarize). Serves as a foundation for building custom MCP servers with extensible architecture.547 npm-
- AlicenseBqualityBmaintenanceUnified MCP gateway for AI agents with 56+ tools and growing. Travel (Amadeus, Sabre GDS), e-commerce, local services, financial markets (Polymarket), and marketing APIs — all through a single endpoint. Pay-per-call via x402 micropayments in USDC.50010MIT
- AlicenseNot gradedqualityCmaintenanceA unified MCP server providing AI agents with 40+ developer APIs including geolocation, crypto prices, DNS lookup, and web scraping. Enables natural language access to various tools through a single gateway.1MIT
- AlicenseNot gradedqualityDmaintenanceA production-grade MCP server designed for multi-tenant, authenticated, and observable AI agent systems, enabling secure tool execution across heterogeneous data sources.68MIT