MCP Documentation Server

Локальное управление документами и семантический поиск для ИИ-агентов разработки. Без внешних баз данных, облачных API и привязки к вендору.

В отличие от других MCP-серверов, которые работают только через CLI, этот поставляется с полноценной веб-панелью — просматривайте, ищите, загружайте и управляйте своей базой знаний прямо из браузера. Каждый MCP-инструмент также доступен через REST API, что даёт ИИ-агентам лёгкий интерфейс без схем.

• 🏠 Работает полностью офлайн — векторная база данных Orama с локальными ИИ-эмбеддингами (Transformers.js)

• 🌐 Встроенный веб-интерфейс — запускается автоматически на порту 3080 вместе с MCP-сервером

• 🔍 Гибридный поиск — полнотекстовый + векторный поиск по сходству с чанкингом «родитель-потомок»

• 🤖 Опциональный ИИ-поиск — Google Gemini для расширенного анализа документов (используйте свой ключ)

• 📁 Загрузка перетаскиванием — поддержка .txt, .md, .pdf

• 📦 Опубликован в MCP Registry — устанавливается через npx, клонирование не требуется

Быстрый старт

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@Unity-Billal-mesloub/mcp-documentation-server"]
    }
  }
}

🤖 Навык агента (REST API) — рекомендуется для ИИ-агентов

Каждый MCP-инструмент также доступен через REST API на ``. Это рекомендуемый способ взаимодействия для ИИ-агентов (Claude Code, OpenCode, Gemini CLI, Cursor), поскольку он позволяет не загружать схемы MCP-инструментов в контекст разговора — в него попадает только JSON ответа.

  -H "Content-Type: application/json" \
  -d '{"query": "your search", "limit": 5}'

Готовый к использованию навык включён в skills/documentation-server/SKILL.md — он обучает вашего агента работе с каждой конечной точкой на примерах. Установите его:

npx skills add https://github.com/Unity-Billal-mesloub/mcp-documentation-server --skill documentation-server

Базовый рабочий процесс

1. Добавьте документы с помощью add_document или поместите файлы .txt / .md / .pdf в папку загрузок и вызовите process_uploads.

2. Ищите по всем документам с помощью search_all_documents или в пределах одного документа с помощью search_documents.

3. Используйте get_context_window, чтобы получить соседние чанки и предоставить LLM более широкий контекст.

Related MCP server: OpenLMlib

Веб-интерфейс

Веб-интерфейс автоматически запускается на порту 3080 при запуске MCP-сервера. Из веб-интерфейса вы можете:

• 📊 Панель управления — обзор всех документов и статистика

• 📄 Документы — просмотр, чтение и удаление документов

• ➕ Добавить документ — создание документов с заголовком, содержимым и метаданными

• 🔍 Поиск по всем — семантический поиск по всем документам

• 🎯 Поиск в документе — поиск в пределах конкретного документа

• 🤖 ИИ-поиск — анализ на базе Gemini (если задан GEMINI_API_KEY)

• 📁 Загрузить файлы — перетаскивание файлов и их обработка в базе знаний

• 🪟 Контекстное окно — просмотр чанков вокруг конкретного индекса

Настройка MCP-клиента

Минимальная конфигурация

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@Unity-Billal-mesloub/mcp-documentation-server"]
    }
  }
}

С переменными окружения (все необязательные)

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@Unity-Billal-mesloub/mcp-documentation-server"],
      "env": {
        "MCP_BASE_DIR": "/path/to/workspace",
        "GEMINI_API_KEY": "your-api-key-here",
        "MCP_EMBEDDING_MODEL": "Xenova/all-MiniLM-L6-v2",
        "START_WEB_UI": "true",
        "WEB_HOST": "127.0.0.1",
        "WEB_PORT": "3080"
      }
    }
  }
}

Все переменные окружения необязательны. Без GEMINI_API_KEY доступны только локальные инструменты поиска на основе эмбеддингов.

MCP-инструменты

Сервер регистрирует следующие инструменты (все проверяются схемами Zod):

📄 Управление документами

📁 Обработка файлов

🔍 Поиск

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

Настройте с помощью переменных окружения или файла .env в корне проекта:

Структура хранения

~/.mcp-documentation-server/     # Or custom path via MCP_BASE_DIR
├── data/
│   ├── orama-chunks.msp         # Orama vector DB (child chunks + embeddings)
│   ├── orama-docs.msp           # Orama document DB (full content + metadata)
│   ├── orama-parents.msp        # Orama parent chunks DB (context sections)
│   ├── migration-complete.flag   # Written after legacy JSON migration
│   └── *.md                     # Markdown copies of documents
└── uploads/                     # Drop .txt, .md, .pdf files here

Модели эмбеддингов

Задаётся через MCP_EMBEDDING_MODEL:

Модели загружаются при первом использовании (~80–420 МБ). Размерность векторов определяется автоматически на основе провайдера.

⚠️ Важно: Смена модели эмбеддингов требует повторного добавления всех документов — эмбеддинги из разных моделей несовместимы. База данных Orama пересоздаётся автоматически при изменении размерности.

Архитектура

Server (FastMCP, stdio)
  ├─ Web UI (Express, port 3080)
  │    └─ REST API → DocumentManager
  └─ MCP Tools
       └─ DocumentManager
            ├─ OramaStore          — Orama vector DB (chunks DB + docs DB + parents DB), persistence, migration
            ├─ IntelligentChunker  — Parent-child chunking (code, markdown, text, PDF)
            ├─ EmbeddingProvider   — Local embeddings via @xenova/transformers
            │    └─ EmbeddingCache — LRU in-memory cache
            └─ GeminiSearchService — Optional AI search via Google Gemini

• OramaStore управляет тремя экземплярами Orama: один — для метаданных и содержимого документов, один — для дочерних чанков с векторными эмбеддингами и один — для родительских чанков (контекстных секций). Все они сохраняются в бинарные файлы на диске и восстанавливаются при запуске.

• IntelligentChunker реализует паттерн чанкинга «родитель-потомок»: документы сначала разбиваются на крупные родительские чанки, сохраняющие полный контекст (секции, абзацы), затем каждый родительский чанк дополнительно разбивается на мелкие дочерние для точного векторного поиска. При выполнении запроса результаты дедуплицируются по родительским чанкам, чтобы LLM получала и совпавший фрагмент, и более широкий контекст.

• EmbeddingProvider лениво загружает модель Transformers.js для локального вывода — вызовы API не требуются.

Разработка

git clone https://github.com/Unity-Billal-mesloub/mcp-documentation-server.git
cd mcp-documentation-server
npm install

npm run dev       # FastMCP dev mode with hot reload
npm run build     # TypeScript compilation
npm run inspect   # FastMCP web UI for interactive tool testing
npm start         # Direct tsx execution (MCP server + web UI)
npm run web       # Run only the web UI (development)
npm run web:build # Run only the web UI (compiled)

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

1. Сделайте форк репозитория

2. Создайте ветку для новой функции: git checkout -b feature/name

3. Следуйте правилам Conventional Commits для сообщений коммитов

4. Откройте pull request

Поддержка

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

• 🐛 Сообщить о проблемах

• 💬 Сообщество MCP

• 🤖 Google AI Studio — получите ключ Gemini API

История звёзд

Создано с помощью FastMCP, Orama и TypeScript