docs-mcp-server

Docs MCP Server: эксперт по актуальной документации вашего ИИ

Помощники по кодированию ИИ часто сталкиваются с устаревшей документацией, что приводит к неверным предложениям или галлюцинаторным примерам кода. Проверка ответов ИИ на соответствие определенным версиям библиотеки может быть трудоемкой и неэффективной.

Docs MCP Server решает эту проблему, выступая в качестве персональной, постоянно актуальной базы знаний для вашего помощника ИИ. Его основная цель — индексировать стороннюю документацию — библиотеки, которые вы фактически используете в своей кодовой базе. Он скрейпит веб-сайты, репозитории GitHub, менеджеры пакетов (npm, PyPI) и даже локальные файлы, каталогизируя документы локально. Затем он предоставляет мощные инструменты поиска через Model Context Protocol (MCP) вашему агенту кодирования.

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

Обосновывая ответы ИИ в точном контексте с учетом версии, сервер Docs MCP позволяет вам получать краткие и релевантные сведения об интеграции и фрагменты кода, повышая надежность и эффективность разработки с использованием LLM.

Он бесплатный , с открытым исходным кодом , работает локально для обеспечения конфиденциальности и легко интегрируется в ваш рабочий процесс разработки.

Зачем использовать сервер Docs MCP?

Кодирование с помощью LLM обещает скорость и эффективность, но часто оказывается неэффективным из-за:

• 🌀 Устаревшие знания: LLM обучаются на снимках интернета, быстро отставая от новых версий библиотек и изменений API.
• 👻 Кодовые галлюцинации: ИИ может изобрести правдоподобно выглядящий код, который синтаксически верный, но функционально неверный или использует несуществующие API.
• ❓ Неоднозначность версии: общие ответы редко учитывают конкретные зависимости версий в вашем проекте, что приводит к неявным ошибкам.
• ⏳ Накладные расходы на проверку: разработчики тратят драгоценное время на повторную проверку предложений ИИ на соответствие официальной документации.

Docs MCP Server решает эти проблемы напрямую:

• ✅ Предоставление всегда актуального контекста: по запросу он извлекает и индексирует документацию непосредственно из официальных источников (веб-сайтов, GitHub, npm, PyPI, локальных файлов).
• 🎯 Предоставление ответов, специфичных для версии: поисковые запросы могут быть нацелены на точные версии библиотек, гарантируя, что информация соответствует зависимостям вашего проекта.
• 💡 Уменьшение галлюцинаций: основываясь на реальной документации, LLM предоставляет точные примеры и детали интеграции.
• ⚡ Повышение производительности: получайте достоверные ответы быстрее, интегрированные непосредственно в рабочий процесс вашего помощника с искусственным интеллектом.

✨ Основные характеристики

• Актуальные знания: извлекает последнюю документацию непосредственно из источника.
• Поиск с учетом версий: получайте ответы, соответствующие определенным версиям библиотеки (например, react@18.2.0 или react@17.0.0 ).
• Точные фрагменты: Уменьшает галлюцинации ИИ, используя контекст из официальных документов.
• Веб-интерфейс: предоставляет простой в использовании веб-интерфейс для поиска и управления документацией.
• Широкая совместимость с исходным кодом: считывает данные с веб-сайтов, репозиториев GitHub, сайтов менеджеров пакетов (npm, PyPI) и даже локальных файловых каталогов.
• Интеллектуальная обработка: Автоматически семантически разбивает документацию на фрагменты и генерирует встраивания.
• Гибкие модели встраивания: поддерживает OpenAI (включая совместимые API, такие как Ollama), Google Gemini/Vertex AI, Azure OpenAI, AWS Bedrock и другие.
• Мощный гибридный поиск: объединяет векторное сходство с полнотекстовым поиском для обеспечения релевантности.
• Локально и конфиденциально: работает исключительно на вашем компьютере, обеспечивая конфиденциальность ваших данных и запросов.
• Бесплатно и с открытым исходным кодом: создано сообществом для сообщества.
• Простое развертывание: простая настройка через Docker или npx .
• Полная интеграция: работает с MCP-совместимыми клиентами (например, Claude, Cline, Roo).

Как запустить сервер Docs MCP

Быстро приступайте к работе! Мы рекомендуем использовать Docker Desktop (Docker Compose) для самой простой настройки и управления.

• Рекомендовано: Docker Desktop
• Альтернатива: использование Docker
• Альтернатива: использование npx

Рекомендовано: Docker Desktop

Этот метод обеспечивает постоянную локальную настройку, запуская сервер и веб-интерфейс с помощью Docker Compose. Он требует клонирования репозитория, но упрощает управление обеими службами одновременно.

1. Убедитесь, что Docker и Docker Compose установлены и запущены.
2. Клонируйте репозиторий:
   git clone https://github.com/arabold/docs-mcp-server.git cd docs-mcp-server
3. Настройте свою среду: скопируйте файл примера среды и отредактируйте его, добавив свой ключ API OpenAI (обязательно):
   cp .env.example .env # Edit the .env file and set your OpenAI API key:
   Пример .env :
   OPENAI_API_KEY=your-api-key-here
   Дополнительные параметры конфигурации (например, другие поставщики, расширенные настройки) см. в разделе «Конфигурация» .
4. Запуск служб: Запустите эту команду из корневого каталога репозитория. Она построит образы (при необходимости) и запустит сервер и веб-интерфейс в фоновом режиме.
   docker compose up -d
   • -d : Запускает контейнеры в отсоединенном режиме (в фоновом режиме). Пропустите этот параметр, чтобы просматривать логи прямо в терминале.

   Примечание: если вы извлекаете обновления для репозитория (например, с помощью git pull ), вам потребуется пересобрать образы Docker, чтобы включить изменения, выполнив docker compose up -d --build .

5. Настройте клиент MCP: добавьте следующий блок конфигурации в файл настроек MCP (например, для Claude, Cline, Roo):
   { "mcpServers": { "docs-mcp-server": { "url": "http://localhost:6280/sse", // Connects via HTTP to the Docker Compose service "disabled": false, "autoApprove": [] } } }
   Перезапустите приложение AI-помощника после обновления конфигурации.Примечание: настройка Docker Compose запускает Docs MCP Server в режиме HTTP (через SSE) по замыслу, поскольку он задуман как автономный, подключаемый экземпляр. Он не поддерживает stdio-коммуникацию.
6. Доступ к веб-интерфейсу: веб-интерфейс будет доступен по адресу http://localhost:6281 .

Преимущества этого метода:

• Запускает сервер и веб-интерфейс с помощью одной команды.
• Использует локальный исходный код (автоматически перестраивается, если код изменяется и вы запускаете docker compose up --build ).
• Постоянное хранение данных с помощью тома Docker docs-mcp-data .
• Простое управление конфигурацией через файл .env .

Чтобы остановить службы, запустите docker compose down из каталога репозитория.

Добавление библиотечной документации

После запуска сервера Docs MCP вы можете использовать веб-интерфейс для добавления новой документации для индексации или для поиска в существующей документации .

1. Откройте веб-интерфейс: если вы использовали рекомендуемую настройку Docker Compose, перейдите в браузере по адресу http://localhost:6281 .
2. Найдите форму «Поставить новое задание по очистке в очередь»: обычно она отображается на видном месте на главной странице.
3. Введите данные:
   • URL: укажите начальный URL-адрес документации, которую вы хотите индексировать (например, https://react.dev/reference/react , https://github.com/expressjs/express , https://docs.python.org/3/ ).
   • Имя библиотеки: Дайте ей короткое, запоминающееся имя (например, react , express , python ). Это то, как вы будете ссылаться на нее в поиске.
   • Версия (необязательно): Если вы хотите проиндексировать определенную версию, введите ее здесь (например, 18.2.0 , 4.17.1 , 3.11 ). Если оставить пустым, сервер часто пытается обнаружить последнюю версию или индексирует ее как неверсированную.
   • (Необязательно) Дополнительные настройки: при необходимости настройте Scope (например, «Подстраницы», «Имя хоста», «Домен»), Max Pages , Max Depth и Follow Redirects умолчанию. Обычно достаточно значений по умолчанию.
4. Нажмите «Queue Job»: сервер запустит фоновое задание для извлечения, обработки и индексации документации. Вы можете следить за ходом его выполнения в разделе «Job Queue» веб-интерфейса.
5. Повторите: повторите шаги 3–4 для каждой библиотеки, документацией которой должен управлять сервер.

Вот и все! После успешного завершения задания документация по этой библиотеке и версии становится доступной для поиска через подключенный помощник по кодированию на основе ИИ (с помощью инструмента search_docs ) или непосредственно в веб-интерфейсе, щелкнув по названию библиотеки в разделе «Индексированная документация».

Альтернатива: использование Docker

Этот подход прост, понятен и не требует клонирования репозитория.

1. Убедитесь, что Docker установлен и запущен.
2. Настройте параметры MCP:Пример конфигурации Claude/Cline/Roo: Добавьте следующий блок конфигурации в файл настроек MCP (при необходимости измените путь):
   { "mcpServers": { "docs-mcp-server": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "OPENAI_API_KEY", "-v", "docs-mcp-data:/data", "ghcr.io/arabold/docs-mcp-server:latest" ], "env": { "OPENAI_API_KEY": "sk-proj-..." // Required if using OpenAI (default) }, "disabled": false, "autoApprove": [] } } }
   Не забудьте заменить "sk-proj-..." на ваш фактический ключ API OpenAI и перезапустить приложение.
3. Вот и все! Теперь сервер будет доступен вашему ИИ-помощнику.

Настройки Docker-контейнера:

• -i : Оставить STDIN открытым, что имеет решающее значение для связи MCP через stdio.
• --rm : Автоматически удалять контейнер при его выходе.
• -e OPENAI_API_KEY : Обязательно. Установите свой ключ API OpenAI.
• -v docs-mcp-data:/data : Требуется для сохранения. Монтирует Docker с именем тома docs-mcp-data для хранения базы данных. Вы можете заменить его на определенный путь к хосту, если предпочитаете (например, -v /path/on/host:/data ).

Любая из переменных среды конфигурации (см. Конфигурация выше) может быть передана в контейнер с помощью флага -e . Например:

Запуск веб-интерфейса

Вы можете получить доступ к веб-интерфейсу по адресу http://localhost:6281 для управления и поиска библиотечной документации через свой браузер.

Если вы используете сервер с Docker, используйте Docker и для веб-интерфейса:

Обязательно:

• Используйте то же имя тома (в этом примере docs-mcp-data ), что и на вашем сервере.
• Сопоставьте порт 6281 с -p 6281:6281
• Передайте любые переменные среды конфигурации с флагами -e

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

Вы можете использовать CLI для управления документацией напрямую через Docker, передавая команды CLI после имени образа:

Пример:

Обязательно используйте то же имя тома (в этом примере docs-mcp-data ), что и контейнер вашего сервера MCP, если вы хотите, чтобы они обменивались данными. Любая из переменных среды конфигурации (см. Конфигурация выше) может быть передана с использованием флагов -e .

Основные доступные команды:

• scrape : извлекает и индексирует документацию из URL-адреса.
• search : Поиск в проиндексированной документации.
• list : Список всех проиндексированных библиотек.
• remove : Удаляет индексированную документацию.
• fetch-url : извлекает один URL-адрес и преобразует его в Markdown.
• find-version : находит наиболее подходящую версию для библиотеки.

Для получения подробной информации об использовании команд запустите CLI с флагом --help (например, docker run ... ghcr.io/arabold/docs-mcp-server:latest --help ).

Альтернатива: использование npx

Этот подход полезен, когда вам нужен локальный доступ к файлам (например, индексация документации из локальной файловой системы). Хотя этого также можно добиться путем монтирования путей в контейнер Docker, использование npx проще, но требует установки Node.js.

1. Убедитесь, что Node.js установлен.
2. Настройте параметры MCP:Пример конфигурации Клода/Клайна/Ру: Добавьте следующий блок конфигурации в файл настроек MCP:
   { "mcpServers": { "docs-mcp-server": { "command": "npx", "args": ["-y", "@arabold/docs-mcp-server"], // This will run the default MCP server (stdio). // To run in HTTP mode, add arguments: e.g. // "args": ["-y", "@arabold/docs-mcp-server", "--protocol", "http", "--port", "6280"], "env": { "OPENAI_API_KEY": "sk-proj-..." // Required if using OpenAI (default) }, "disabled": false, "autoApprove": [] } } }
   Не забудьте заменить "sk-proj-..." на ваш фактический ключ API OpenAI и перезапустить приложение.
3. Вот и все! Теперь сервер будет доступен вашему ИИ-помощнику.

Запуск веб-интерфейса

Если вы запускаете сервер MCP с npx (как показано выше, он запускается по умолчанию), используйте npx также для веб-интерфейса:

Вы можете указать другой порт для веб-интерфейса, используя флаг --port .

Подход npx будет использовать каталог данных по умолчанию в вашей системе (обычно в вашем домашнем каталоге), обеспечивая согласованность между сервером и веб-интерфейсом.

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

Если вы запускаете сервер MCP с npx , вы также можете использовать npx для команд CLI:

Пример:

Подход npx будет использовать каталог данных по умолчанию в вашей системе (обычно это ваш домашний каталог), обеспечивая согласованность.

Для получения подробной информации об использовании команд запустите CLI с флагом --help (например, npx -y @arabold/docs-mcp-server --help ).

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

Для настройки поведения модели внедрения поддерживаются следующие переменные среды. Укажите их в файле .env или передайте их как флаги -e при запуске сервера через Docker или npx.

Конфигурация модели встраивания

• DOCS_MCP_EMBEDDING_MODEL : Необязательно. Формат: provider:model_name или просто model_name (по умолчанию text-embedding-3-small ). Поддерживаемые поставщики и требуемые ими переменные среды:
  • openai (поставщик по умолчанию): использует модели встраивания OpenAI.
    • OPENAI_API_KEY : Ваш ключ API OpenAI. Требуется, если openai является активным поставщиком.
    • OPENAI_ORG_ID : Необязательно. Ваш идентификатор организации OpenAI
    • OPENAI_API_BASE : Необязательно. Пользовательский базовый URL для API, совместимых с OpenAI (например, Ollama).
  • vertex : использует вложения Google Cloud Vertex AI
    • GOOGLE_APPLICATION_CREDENTIALS : Обязательно. Путь к файлу ключа JSON учетной записи службы
  • gemini : использует вложения Google Generative AI (Gemini)
    • GOOGLE_API_KEY : Обязательно. Ваш ключ API Google
  • aws : использует встраивания AWS Bedrock
    • AWS_ACCESS_KEY_ID : Обязательно. Ключ доступа AWS
    • AWS_SECRET_ACCESS_KEY : Обязательно. Секретный ключ AWS
    • AWS_REGION или BEDROCK_AWS_REGION : Обязательно. Регион AWS для Bedrock
  • microsoft : Использует встраивание Azure OpenAI
    • AZURE_OPENAI_API_KEY : Обязательно. Ключ API Azure OpenAI
    • AZURE_OPENAI_API_INSTANCE_NAME : Обязательно. Имя экземпляра Azure
    • AZURE_OPENAI_API_DEPLOYMENT_NAME : Обязательно. Имя развертывания Azure
    • AZURE_OPENAI_API_VERSION : Обязательно. Версия Azure API

Векторные размеры

Схема базы данных использует фиксированную размерность 1536 для встраивания векторов. Поддерживаются только модели, которые производят векторы с размерностью ≤ 1536, за исключением некоторых поставщиков (например, Gemini), которые поддерживают сокращение размерности.

Для API, совместимых с OpenAI (например, Ollama), используйте провайдера openai с OPENAI_API_BASE , указывающим на вашу конечную точку.

Разработка

В этом разделе рассматривается запуск сервера/CLI напрямую из исходного кода для целей разработки. Основной метод использования — через публичный образ Docker ( ghcr.io/arabold/docs-mcp-server:latest ), как подробно описано в разделе «Альтернатива: использование Docker», или через Docker Compose, как описано в разделе «Рекомендуется: Docker Desktop».

Работает из источника

Примечание: Браузеры Playwright не устанавливаются автоматически во время npm install . Если вам нужно запустить тесты или использовать функции, требующие Playwright, выполните:

npx playwright install --no-shell --with-deps chromium

Это обеспечивает изолированную среду и предоставляет доступ к серверу через конечные точки HTTP.

Этот метод полезен для внесения вклада в проект или запуска неопубликованных версий.

1. Клонируйте репозиторий:
   git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different cd docs-mcp-server
2. Установить зависимости:
   npm install
3. Соберите проект: он скомпилирует TypeScript в JavaScript в каталоге dist/ .
   npm run build
4. Настройка среды: Создайте и настройте файл .env , как описано в разделе «Конфигурация» . Это важно для предоставления OPENAI_API_KEY .
5. Бегать:
   • Сервер MCP по умолчанию (разработка):
     • Режим stdio (по умолчанию): npm run dev:server
     • Режим HTTP: npm run dev:server:http (использует порт по умолчанию)
     • Пользовательский HTTP: vite-node src/index.ts -- --protocol http --port <your_port>
   • Веб-интерфейс (разработка): npm run dev:web
     • Это запустит веб-сервер (например, на порту 6281) и отслеживает изменения активов.
   • Команды CLI (разработка): npm run dev:cli -- <command> [options]
     • Пример: npm run dev:cli -- list
     • Пример: vite-node src/index.ts scrape <library> <url>
   • Режим производства (после npm run build ):
     • Сервер MCP по умолчанию (stdio): npm run start (или node dist/index.js )
     • Сервер MCP (HTTP): npm run start -- --protocol http --port <your_port> (или node dist/index.js --protocol http --port <your_port> )
     • Веб-интерфейс: npm run web -- --port <web_port> (или node dist/index.js web --port <web_port> )
     • Команды CLI: npm run cli -- <command> [options] (или node dist/index.js <command> [options] )

Тестирование

Поскольку серверы MCP взаимодействуют через stdio при запуске напрямую через Node.js (или vite-node ), отладка может быть сложной. Мы рекомендуем использовать MCP Inspector .

После сборки проекта ( npm run build ):

Если для разработки используется vite-node :

Инспектор предоставит URL-адрес для доступа к инструментам отладки в вашем браузере.

Архитектура

Подробную информацию об архитектуре и принципах проектирования проекта можно найти на сайте ARCHITECTURE.md .

Примечательно, что подавляющая часть кода этого проекта была сгенерирована помощником искусственного интеллекта Клайном, использующим возможности этого самого сервера MCP.