sofya-mcp

MCP-сервер для Sofya: веб-поиск, получение и извлечение данных, а также углублённые исследования для AI-агентов через Model Context Protocol.

Сервер можно использовать двумя способами:

Хостинг (без установки): подключите клиент к https://sofya.co/mcp, указав API key в качестве Bearer-токена. В реестре MCP сервер представлен как co.sofya/sofya.
Локальный запуск: запустите пакет sofya-mcp через stdio. Это лёгкая обёртка над REST API Sofya с теми же инструментами.

Все четыре инструмента доступны только для чтения. Аккаунты GitHub, соответствующие условиям, получают 2 000 бесплатных кредитов в месяц.

Инструменты

Инструмент	Назначение	Стоимость
`search`	Поиск в интернете и получение извлечённого содержимого страниц, а не только кратких фрагментов. Поддерживаются тема `news`, фильтрация по доменам, ограничение по дате публикации и необязательный ответ, синтезированный AI.	1–2 кредита (+10 за `include_answer`)
`fetch`	Получение до 10 URL в формате чистого markdown. Поддерживаются PDF, DOCX, XLSX, PPTX, EPUB и другие форматы.	2 кредита за URL
`extract`	Получение страницы и извлечение из неё конкретных структурированных данных с помощью AI.	10 кредитов
`research`	Разбиение вопроса на подтемы, параллельный анализ множества источников и подготовка сводного отчёта со ссылками на источники.	50 кредитов

Хостинг-сервер (VS Code / Copilot и другие клиенты)

Получите API key на sofya.co (ключи имеют формат ay_live_...), затем укажите адрес хостинг-сервера в настройках клиента.

VS Code / GitHub Copilot (.vscode/mcp.json):

{
  "servers": {
    "sofya": {
      "type": "http",
      "url": "https://sofya.co/mcp",
      "headers": { "Authorization": "Bearer ay_live_..." }
    }
  }
}

Claude Code:

claude mcp add --transport http sofya https://sofya.co/mcp --header "Authorization: Bearer ay_live_..."

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "sofya": {
      "url": "https://sofya.co/mcp",
      "headers": { "Authorization": "Bearer ay_live_..." }
    }
  }
}

После настройки можно задавать агенту вопросы, например: «Найди последние заметки о выпуске Node.js LTS», «Получи этот PDF и кратко изложи его содержание» или «Исследуй, как Закон ЕС об AI регулирует модели с открытыми весами». Полная документация API: sofya.co/docs.

Локальный сервер (npm)

Требования

Node.js 18+
API key Sofya — получите его на sofya.co (ключи имеют формат ay_live_...)

Быстрый запуск

Запустите сервер напрямую с помощью npx — установка не требуется:

SOFYA_API_KEY=ay_live_... npx -y sofya-mcp

Настройка

Claude Code

claude mcp add sofya --env SOFYA_API_KEY=ay_live_... -- npx -y sofya-mcp

Claude Desktop / Cursor / Windsurf / VS Code

Добавьте эту конфигурацию в файл настроек MCP, например claude_desktop_config.json или .cursor/mcp.json:

{
  "mcpServers": {
    "sofya": {
      "command": "npx",
      "args": ["-y", "sofya-mcp"],
      "env": {
        "SOFYA_API_KEY": "ay_live_..."
      }
    }
  }
}

Codex

Добавьте сервер с помощью Codex CLI:

codex mcp add sofya --env SOFYA_API_KEY=ay_live_... -- npx -y sofya-mcp

Также можно отредактировать файл ~/.codex/config.toml напрямую. Обратите внимание: Codex размещает переменные окружения во вложенной таблице [mcp_servers..env]:

[mcp_servers.sofya]
command = "npx"
args = ["-y", "sofya-mcp"]

[mcp_servers.sofya.env]
SOFYA_API_KEY = "ay_live_..."

Чтобы убедиться, что сервер подключён, выполните /mcp в Codex.

Переменные окружения

Переменная	Обязательная	Значение по умолчанию	Описание
`SOFYA_API_KEY`	да	-	Ваш API key Sofya (`ay_live_...`).
`SOFYA_BASE_URL`	нет	`https://sofya.co`	Переопределяет базовый URL API Sofya.

Параметры CLI --api-key и --base-url имеют приоритет над переменными окружения.

Запустите npx sofya-mcp --list-tools, чтобы вывести схемы инструментов, или используйте --help, чтобы посмотреть доступные параметры.

Разработка

git clone https://github.com/sofya-co/sofya-mcp.git
cd sofya-mcp
npm install          # also builds via the prepare script
npm run build        # compile TypeScript to build/
npm run watch        # recompile on change
npm run inspector    # debug with @modelcontextprotocol/inspector

Сервер состоит из одного файла — src/index.ts. Описания инструментов в точности соответствуют хостинг-серверу MCP Sofya: совпадают названия, параметры и значения по умолчанию.

Лицензия

MIT — см. LICENSE.