Exa Websets MCP Server

Сервер протокола контекста модели (MCP), который интегрирует API Exa Websets с Claude Desktop, Cursor, Windsurf и другими клиентами, поддерживающими MCP.

Что такое Websets?

Websets — это коллекции веб-сущностей (компаний, людей, научных статей), которые можно автоматически находить, проверять и обогащать пользовательскими данными. Представьте их как умные, самообновляющиеся электронные таблицы, работающие на основе ИИ-исследований в интернете.

Основные возможности:

• 🔍 Автоматизированный поиск: поиск сущностей, соответствующих критериям на естественном языке

• 📊 Обогащение данных: извлечение пользовательской информации с помощью ИИ-агентов

• 🎯 Проверка: ИИ подтверждает, что сущности соответствуют вашим критериям

• 🔗 Вебхуки: уведомления в реальном времени об обновлениях коллекции

• 📥 Импорт: загрузка собственных данных CSV в Websets для обогащения или фильтрации

Related MCP server: Exa Websets MCP Server

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

Этот MCP-сервер предоставляет следующие инструменты:

Управление Webset

Управление элементами

Поисковые операции

Операции обогащения

Вебхуки

Импорт

События

Установка

Установка через Smithery

Чтобы установить Exa Websets автоматически через Smithery:

npx -y @smithery/cli install @exa-labs/websets-mcp-server

Предварительные требования

• Node.js v18 или выше

• Claude Desktop, Cursor или другой клиент, поддерживающий MCP

• API-ключ Exa с сайта exa.ai

Использование Claude Code (рекомендуется)

Самый быстрый способ настроить Websets MCP:

claude mcp add websets -e EXA_API_KEY=YOUR_API_KEY -- npx -y websets-mcp-server

Замените YOUR_API_KEY на ваш API-ключ Exa.

Использование NPX

# Install globally
npm install -g websets-mcp-server

# Or run directly with npx
npx websets-mcp-server

Конфигурация

Конфигурация Claude Desktop

1. Включите режим разработчика

   • Откройте Claude Desktop

   • Нажмите меню → Enable Developer Mode

   • Перейдите в Settings → Developer → Edit Config

2. Добавьте в файл конфигурации:

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "websets": {
         "command": "npx",
         "args": [
           "-y",
           "websets-mcp-server"
         ],
         "env": {
           "EXA_API_KEY": "your-api-key-here"
         }
       }
     }
   }

3. Перезапустите Claude Desktop

   • Полностью закройте Claude Desktop

   • Запустите его снова

   • Ищите значок 🔌 для проверки подключения

Конфигурация Cursor и Claude Code

Используйте конфигурацию на основе HTTP. Передайте ваш API-ключ Exa в качестве токена Bearer в заголовке Authorization (или в качестве параметра запроса ?exaApiKey=... в качестве резервного варианта):

{
  "mcpServers": {
    "websets": {
      "type": "http",
      "url": "https://websetsmcp.exa.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_EXA_API_KEY"
      }
    }
  }
}

Справочник схем инструментов

⚠️ Важно для ИИ-вызовов: См. TOOL_SCHEMAS.md для получения точных форматов параметров и примеров.

Основные правила схемы:

• criteria должен быть массивом объектов: [{description: "..."}] (НЕ массивом строк)

• entity должен быть объектом: {type: "company"} (НЕ строкой)

• options должен быть массивом объектов: [{label: "..."}] (НЕ массивом строк)

Эти форматы обеспечивают согласованность всех инструментов и соответствуют спецификации API Websets.

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

После настройки вы можете попросить Claude взаимодействовать с Websets:

Создание Webset

Create a webset of AI startups in San Francisco with 20 companies. 
Add enrichments for revenue, employee count, and funding stage.

Список и просмотр Websets

List all my websets and show me the details of the one called "AI Startups"

Управление элементами

Show me the first 10 items from my "AI Startups" webset with all their enrichment data

Добавление дополнительных элементов

Run another search on my "AI Startups" webset for 20 more companies focused on
enterprise voice agents, appending to the existing items

Расширенное обогащение

Add an enrichment to my webset that extracts the company's latest product launch 
and the CEO's LinkedIn profile

Пример рабочего процесса

Вот полный рабочий процесс для создания базы данных исследований компаний:

1. Создайте коллекцию:

   Create a webset called "SaaS Companies" that searches for 
   "B2B SaaS companies with $10M+ revenue"

2. Добавьте обогащения:

   Add enrichments to extract: annual recurring revenue, number of customers, 
   primary market segment, and tech stack used

3. Подпишитесь на события:

   Create a webhook to https://example.com/hook subscribed to
   webset.search.completed and webset.enrichment.completed

4. Просмотрите результаты:

   Show me all items with their enrichment data, sorted by revenue

Подробности инструментов

create_webset

Создает новую коллекцию webset с опциональным автоматическим заполнением и обогащением.

Параметры:

• externalId (опционально): Ваш собственный идентификатор для webset (макс. 300 символов)

• searchQuery (опционально): Запрос на естественном языке для поиска сущностей

• searchCount (опционально): Количество сущностей для поиска (по умолчанию: 10, мин: 1)

• searchEntity (опционально): Тип сущности для поиска, например {type: "company"}. Для типа "custom" включите description.

• searchCriteria (опционально): Дополнительные критерии фильтрации — [{description: "..."}] (макс. 5)

• searchBehavior (опционально): "override" (по умолчанию) заменяет существующие элементы, "append" добавляет к ним

• searchExclude (опционально): Импорты/websets, результаты которых нужно исключить — [{source: "webset"|"import", id: "..."}]

• searchScope (опционально): Ограничение поиска существующим импортом или webset — включает поиск по связям с relationship

• searchRecall (опционально): Нужно ли вычислять метрики полноты (recall) для поиска

• searchMaxPeoplePerCompany (опционально): Мягкое ограничение на количество людей на компанию для поиска людей

• searchMetadata (опционально): Метаданные «ключ-значение» для связи с поиском

• enrichments (опционально): Обогащения данных для автоматического извлечения для каждого элемента

• metadata (опционально): Метаданные «ключ-значение» для связи с webset

• excludes (опционально): Глобальные исключения — источники, результаты которых опускаются во всех операциях с этим webset

Примечание: у самого webset нет параметра верхнего уровня name или description. Используйте update_webset с title после создания или metadata для добавления произвольных пар «ключ-значение».

Пример:

{
  "externalId": "tech-unicorns-2024",
  "searchQuery": "Technology companies valued over $1 billion",
  "searchCount": 50,
  "searchEntity": {"type": "company"},
  "searchCriteria": [
    {"description": "Valued at over $1 billion"},
    {"description": "Technology sector"}
  ],
  "enrichments": [
    {
      "description": "Current company valuation in USD",
      "format": "number"
    },
    {
      "description": "Names of company founders",
      "format": "text"
    },
    {
      "description": "Company stage",
      "format": "options",
      "options": [
        {"label": "Series A"},
        {"label": "Series B"},
        {"label": "Series C+"},
        {"label": "Public"}
      ]
    }
  ]
}

create_enrichment

Добавляет новое обогащение данных для извлечения пользовательской информации из каждого элемента webset.

Параметры:

• websetId: ID webset

• description: Подробное описание того, что нужно извлечь

• format (опционально): Один из "text", "date", "number", "options", "email", "phone", "url" — выбирается автоматически, если пропущено

• options (опционально): Когда format равен "options", варианты выбора, из которых агент обогащения делает выбор — [{label: "..."}]

• metadata (опционально): Метаданные «ключ-значение» для связи с этим обогащением

Пример:

{
  "websetId": "webset_abc123",
  "description": "Total number of full-time employees as of the most recent data",
  "format": "number"
}

Мониторы (плановое обновление/поиск) предоставляются базовым API Websets, но в настоящее время не представлены как инструменты MCP в этом сервере. Настраивайте мониторы напрямую через API Websets или websets.exa.ai.

API-эндпоинты

Сервер подключается к API Exa Websets по адресу https://api.exa.ai/websets/v0.

Полная документация API: docs.exa.ai/reference/websets

Расширенная конфигурация

Включение только определенных инструментов

Чтобы включить только определенные инструменты, используйте конфигурацию enabledTools:

{
  "mcpServers": {
    "websets": {
      "command": "npx",
      "args": [
        "-y",
        "websets-mcp-server",
        "--tools=create_webset,list_websets,list_webset_items"
      ],
      "env": {
        "EXA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Режим отладки

Включите ведение журнала отладки для устранения неполадок:

{
  "mcpServers": {
    "websets": {
      "command": "npx",
      "args": [
        "-y",
        "websets-mcp-server",
        "--debug"
      ],
      "env": {
        "EXA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Устранение неполадок

Проблемы с подключением

1. Проверьте, действителен ли ваш API-ключ

2. Убедитесь, что вокруг API-ключа нет пробелов или кавычек

3. Полностью перезапустите ваш MCP-клиент (не просто закройте окно)

4. Проверьте журналы MCP на наличие сообщений об ошибках

Ограничения скорости API

API Websets имеет следующие ограничения:

• Проверьте ограничения вашего плана на exa.ai/dashboard

• Используйте пагинацию для больших websets

• Отслеживайте использование API на панели управления

Распространенные ошибки

• 401 Unauthorized: Неверный или отсутствующий API-ключ

• 404 Not Found: ID webset не существует или был удален

• 422 Unprocessable: Неверный формат запроса или критериев

• 429 Rate Limited: Слишком много запросов, подождите и повторите попытку

Ресурсы

• Документация Exa Websets

• Панель управления Exa

• Спецификация протокола MCP

• Получить API-ключ Exa

Разработка

Сборка из исходного кода

git clone https://github.com/exa-labs/websets-mcp-server.git
cd websets-mcp-server
npm install
npm run build

Структура проекта

websets-mcp-server/
├── src/
│   ├── index.ts              # Main server setup
│   ├── types.ts              # TypeScript type definitions
│   ├── tools/                # MCP tool implementations
│   │   ├── config.ts         # API configuration
│   │   ├── createWebset.ts
│   │   ├── listWebsets.ts
│   │   ├── getWebset.ts
│   │   ├── updateWebset.ts
│   │   ├── deleteWebset.ts
│   │   ├── listItems.ts
│   │   ├── createEnrichment.ts
│   │   ├── createSearch.ts
│   │   ├── createWebhook.ts
│   │   ├── createImport.ts
│   │   └── ...
│   └── utils/
│       ├── api.ts            # Shared API client and error handling
│       └── logger.ts         # Logging utilities
├── package.json
└── tsconfig.json

Лицензия

MIT

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

Вклад приветствуется! Пожалуйста, откройте issue или PR на github.com/exa-labs/websets-mcp-server.

Поддержка

• Документация: docs.exa.ai

• Discord: Присоединяйтесь к сообществу Exa

• Email: support@exa.ai