my-pi/packages/research-agent/MCP_SERVER.md

Pi Research Agent MCP Server

MCP (Model Context Protocol) server для автономного исследования. Позволяет другим агентам вызывать research agent для глубокого исследования тем.

Установка

npm install @earendil-works/pi-research-agent

Настройка

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

Создайте .env файл в корне проекта:

TAVILY_API_KEY=***
OPENROUTER_API_KEY=***
LLM_MODEL=minimax/minimax-m3

Подключение к MCP клиенту

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "research-agent": {
      "command": "node",
      "args": ["/path/to/pi-research/packages/research-agent/dist/mcp-cli.js"],
      "env": {
        "TAVILY_API_KEY": "***",
        "OPENROUTER_API_KEY": "***"
      }
    }
  }
}

Cursor

Добавьте в .cursor/mcp.json в корне проекта:

{
  "mcpServers": {
    "research-agent": {
      "command": "node",
      "args": ["./node_modules/@earendil-works/pi-research-agent/dist/mcp-cli.js"]
    }
  }
}

Другие MCP клиенты

Любой MCP-совместимый клиент может подключиться к серверу через stdio:

node /path/to/pi-research/packages/research-agent/dist/mcp-cli.js

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

research

Выполняет глубокое автономное исследование темы. Агент ищет в интернете, читает источники, сохраняет находки и генерирует подробный отчёт с цитатами.

Параметры:

• topic (string, required): Тема для исследования
• maxTurns (number, optional, default: 15): Максимальное количество ходов исследования
• format (string, optional, default: "markdown"): Формат отчёта ("markdown", "json", "bullet")

Пример использования:

{
  "topic": "Квантовые вычисления 2026",
  "maxTurns": 10,
  "format": "markdown"
}

Возвращает:

• Полный отчёт с executive summary, ключевыми находками, цитатами источников
• Список собранных заметок с уровнем уверенности (high/medium/low)
• Метаданные: количество ходов, количество заметок

quick_search

Быстрый поиск в интернете без полного research flow. Полезен для быстрого поиска информации.

Параметры:

• query (string, required): Поисковый запрос
• maxResults (number, optional, default: 10): Максимальное количество результатов

Пример использования:

{
  "query": "последние разработки в квантовых вычислениях",
  "maxResults": 5
}

Возвращает:

• Список результатов поиска с заголовками, URL и сниппетами

read_url

Извлекает контент из URL. Полезен для чтения конкретных статей или страниц.

Параметры:

• url (string, required): URL для чтения
• maxLength (number, optional, default: 10000): Максимальное количество символов для извлечения

Пример использования:

{
  "url": "https://example.com/article",
  "maxLength": 5000
}

Возвращает:

• Извлечённый текст со страницы

Программное использование

import { createResearchMcpServer } from "@earendil-works/pi-research-agent";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = createResearchMcpServer();
const transport = new StdioServerTransport();
await server.connect(transport);

Как это работает

1. Инициализация: MCP клиент подключается к серверу через stdio
2. Вызов инструмента: Клиент вызывает research, quick_search или read_url
3. Выполнение:
   • research: Создаёт ResearchAgent, выполняет полное исследование (поиск → чтение → сохранение → синтез)
   • quick_search: Выполняет быстрый поиск через Tavily API
   • read_url: Извлекает контент из URL
4. Результат: Возвращает структурированный результат через MCP protocol

Примеры использования

Исследование с Claude

User: Исследуй последние разработки в области квантовых вычислений

Claude: [вызывает research tool]
- Ищет в интернете
- Читает 5-10 источников
- Сохраняет ключевые находки
- Генерирует отчёт на 2000+ слов
- Возвращает результат с цитатами

Быстрый поиск с Cursor

User: @research-agent Найди информацию о Rust async runtime

Cursor: [вызывает quick_search tool]
- Возвращает 10 результатов поиска
- Пользователь может выбрать URL для глубокого чтения

Чтение конкретной статьи

User: Прочитай эту статью: https://example.com/article

Agent: [вызывает read_url tool]
- Извлекает текст статьи
- Возвращает контент для анализа

Ограничения

• Tavily API: Бесплатный план — 1000 запросов/месяц
• Время выполнения: Полное исследование может занять 2-5 минут
• Контекст: Отчёты могут быть очень длинными (5000-10000 слов)

Troubleshooting

"TAVILY_API_KEY environment variable is not set"

Убедитесь что переменные окружения установлены:

export TAVILY_API_KEY=***
export OPENROUTER_API_KEY=***

Или добавьте их в .env файл.

MCP server не отвечает

Проверьте что:

1. Node.js версия >= 22.19.0
2. Все зависимости установлены: npm install
3. Пакет собран: npm run build

Ошибки типов TypeScript

MCP SDK использует Zod для валидации схем. Если возникают ошибки типов, используйте as any для схем (как в текущей реализации).

Лицензия

MIT