framework-mcp

Удалённый MCP-сервер, который даёт кодинг-агентам (Claude Code, Cursor и т. д.) проверенные ответы с привязкой к версиям о быстро меняющихся фреймворках — начиная с Expo SDK 54.

Зачем: данные обучения LLM устаревают быстрее, чем выходят новые версии фреймворков. Агенты продолжают угадывать одни и те же вопросы, зависящие от версии, вместо того чтобы обращаться к проверенному источнику с привязкой к версии. Этот сервер и есть такой источник.

Стек

Node 24 + TypeScript, @modelcontextprotocol/sdk через транспорт Streamable HTTP (с сохранением состояния, сессия на каждое подключение), Express, Postgres (pg), аутентификация по API-ключу через собственное промежуточное ПО requireBearerAuth из SDK.

Хостинг: Railway (вычисления, ~$5/мес по тарифу Hobby) + Neon (Postgres, бесплатный тариф, с ветвлением).

Локальная настройка

1. Создайте бесплатный аккаунт и проект в Neon. Скопируйте строку подключения для ветки dev.

2. cp .env.example .env и заполните DATABASE_URL (из Neon) и API_KEY_PEPPER (любая длинная случайная строка — сгенерируйте с помощью node -e "console.log(require('crypto').randomBytes(32).toString('hex'))").

3. Установите зависимости, выполните миграции, загрузите начальные данные, соберите проект:

   npm install
   npm run db:migrate
   npm run db:seed
   npm run build

4. Создайте себе API-ключ:

   npm run create-api-key -- "my laptop"

   Эта команда выводит сырой ключ один раз — сохраните его, восстановить его невозможно.

5. Запустите локально:

   npm run dev

   curl http://localhost:3000/health должен вернуть ok.

Проверка с помощью MCP Inspector

npx @modelcontextprotocol/inspector

Подключитесь к http://localhost:3000/mcp с транспортом "Streamable HTTP" и укажите заголовок Authorization: Bearer <ваш-api-ключ> в настройках подключения. Убедитесь, что все 3 инструмента (ping, query_framework_doc, report_outcome) отображаются и вызываются.

Деплой на Railway

1. curl -fsSL agents.railway.com | sh, затем railway login.

2. Из этого репозитория: railway init (или railway link, если проект уже существует).

3. Задайте переменные окружения (в панели управления или через railway variable set KEY=value): DATABASE_URL (строка подключения к вашей production-ветке Neon, отдельно от dev-ветки), API_KEY_PEPPER, NODE_ENV=production.

4. railway up.

5. В панели Railway: Settings → Networking → Generate Domain. Установите PUBLIC_HOSTNAME на этот домен (нужно для проверки хоста от DNS-rebinding в SDK, чтобы разрешить реальный трафик).

6. Выполните npm run db:migrate && npm run db:seed один раз для production-DATABASE_URL (с вашей машины, указав production-строку подключения).

7. Создайте production API-ключ с помощью npm run create-api-key, указав production-DATABASE_URL.

Получение API-ключа

Самостоятельно: посетите https://framework-mcp-production.up.railway.app/, введите email, получите ключ мгновенно (один активный ключ на email, с ограничением частоты запросов).

Для мейнтейнера/локально: npm run create-api-key -- "label".

Подключение удалённого клиента

В файле .mcp.json для Claude Code:

{
  "mcpServers": {
    "framework-mcp": {
      "type": "http",
      "url": "https://<your-railway-domain>/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

Инструменты

• ping(message) — проверка работоспособности

• query_framework_doc(framework, version, question) — поиск проверенного ответа, возвращает query_id

• report_outcome(query_id, worked, note?) — запись, сработал ли возвращённый ответ

Статус

Начальные данные в db/seed/expo-54.json (20 записей) проверены по https://expo.dev/changelog/sdk-54 и https://docs.expo.dev/modules/autolinking/ 2026-08-21.

Самостоятельная регистрация доступна на / (email → мгновенный API-ключ, один на email, с IP-ограничением). Проект размещён на Smithery / Glama / mcp.so.

Отложено (этап B, ещё не реализовано): биллинг через Stripe, plan_tier / credit_balance / ограничение частоты запросов на ключ в api_keys, другие фреймворки, оценка/ранжирование по отзывам.