# Custom Framework MCP

MCP-сервер для внутренней документации построенной на основе Markdown-документации. Строит легковесный индекс и предоставляет инструменты для поиска и объяснений.
Так же включает crawler, который может скачивать документацию Xafari с официального сайта, извлекать чистый текст и примеры кода. 

## Зачем нужен MCP

MCP (Model Context Protocol) позволяет IDE и агентам обращаться к локальным данным
как к «инструментам». Вместо ручного поиска по сайту документации, ассистент
вызывает методы `search_docs`, `get_page` и `get_examples`, а сервер отвечает
структурированными данными. Это ускоряет работу, дает воспроизводимые ответы и
снижает зависимость от внешних источников.

### Как MCP ускоряет работу:

- Меньше ручного поиска: вместо переходов по сайту и копипасты — один вызов `search_docs/get_page`.
- Мгновенная выборка: локальный индекс и кэш дают ответы быстрее, чем браузер + поиск.
- Точнее ответы: инструменты возвращают структуру (заголовки, ссылки, код), а не разрозненный текст.
- Повторяемость: один и тот же запрос даёт одинаковый результат — удобно для командной работы.
- Автодогрузка: если страницы нет в кэше, get_page может скачать её автоматически.
- Офлайн-режим: можно работать без доступа к сайту после первичного краула.

### Как работает MCP в этом проекте

- Краулер
  - Скачивает HTML, извлекает читабельный markdown и сохраняет в `data/pages`.
  - Кэширует страницы и использует ETag/Last-Modified при повторных запусках.
  - Из markdown строится индекс `pages.json` + `index.json` для быстрого поиска.
- MCP-сервер читает индекс и отвечает на вызовы инструментов через stdio/http.
- IDE подключается к серверу и использует инструменты прямо в чате.

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

1. Запустить краулер и собрать локальный индекс:
   - `npm run crawl`
2. Запустить MCP-сервер (stdio):
   - `npm run start`
3. Запустить HTTP-режим (опционально):
   - `npm run start:http`
4. Пересобрать индекс без краулинга:
   - `npm run reindex`

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

- `DOCS_BASE_URL` (например: `https://documentation.galaktika-soft.com/xafari/`)
- `MAX_PAGES_PER_SESSION` (по умолчанию: `10000`)
- `FETCH_ON_MISS` (по умолчанию: `true`, **только если** задан `DOCS_BASE_URL`)
- `DATA_DIR` (по умолчанию: `./data`)
- `REQUEST_TIMEOUT_MS` (по умолчанию: `15000`)
- `USER_AGENT`
- `LOG_FILE` (по умолчанию: `logs/mcp.jsonl`, путь относительно `DATA_DIR`)
- `LOG_STDOUT` (по умолчанию: `false`) — если `true`, логи дублируются в stdout (удобно в Docker)
- `CODE_LANGUAGES` (по умолчанию: `cs,js,ts,json,yaml,xml,html,css`)
- `HTTP_PORT` (по умолчанию: `3333`)
- `TOOLS_PREFIX` — если задана (непустая), инструменты будут иметь имена вида `${TOOLS_PREFIX}search_docs`, `${TOOLS_PREFIX}get_page`, ...

### Примеры кода

- Примеры сохраняются только для языков из `CODE_LANGUAGES`.
- Языки нормализуются: `c#`/`csharp` → `cs`, `javascript` → `js`, `typescript` → `ts`, `yml` → `yaml`.
- Если язык не разрешен — блок кода не сохраняется.

### Fetch on miss

`get_page` может автоматически догружать страницу, если ее нет в кэше.
Управляется флагом `FETCH_ON_MISS` (по умолчанию `true` если задан `DOCS_BASE_URL`).

## Подключение MCP в IDE на примере Cursor

### stdio-режим (локальный запуск)

1. Откройте настройки MCP в Cursor.
2. Добавьте новый сервер со следующими параметрами:
   - `name`: `custom-framework-mcp`
   - `command`: `node`
   - `args`: `["C:\\Projects\\custom-framework-mcp\\src\\index.js"]`
   - `cwd`: `C:\\Projects\\custom-framework-mcp`

Пример `~/.cursor/mcp.json`
```json
{
  "mcpServers": {
    "custom-framework-mcp": {
      "command": "node",
      "args": ["C:\\Projects\\custom-framework-mcp\\src\\index.js"],
      "cwd": "C:\\Projects\\custom-framework-mcp"
    }
  }
}
```

### stdio-режим (через Docker)

Если сервис запущен в Docker, можно использовать `docker exec`:

```json
{
  "mcpServers": {
    "custom-framework-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-service", "node", "/app/src/index.js"]
    }
  }
}
```

### HTTP-режим (SSE)

Если сервис запущен в HTTP-режиме (например, через `docker compose`), используйте SSE transport:

```json
{
  "mcpServers": {
    "custom-framework-mcp": {
      "url": "http://localhost:3333/sse"
    }
  }
}
```

**Примечание:** HTTP-режим требует, чтобы сервис был запущен с `npm run start:http` или через `docker compose` (который автоматически запускает HTTP-сервер).

3. Перезапустите MCP-сервер в Cursor.

Чтобы проверить в окне чата напишите
```
list tools
```

Запросите какую-либо документацию с источника

## Запуск через docker compose

```shell
git clone https://github.com/QuAzI/custom-framework-mcp.git
cd custom-framework-mcp
docker compose up -d
```

## Запуск через npx

Локально в репозитории:

- `npm install`
- `npx .` — запустит MCP-сервер (stdio) через `src/index.js`.

Чтобы запускать из любого каталога:

- `npm link`
- `npx --no-install custom-framework-mcp`

Запуск прямо из GitHub (без публикации в npm):

- `npx github:QuAzI/custom-framework-mcp`

Опции краулера:
- `npm run crawl` — по умолчанию скачивает только новые страницы.
- `npm run crawl -- --force` — перекачать все страницы.
- `npm run crawl -- --no-only-new` — отключить режим "только новые".

Примечание:
- `--no-only-new` делает полный обход с кешем (ETag/Last-Modified), а `--force` перекачивает все без учета кеша.

## GitLab CI/CD (внешний репозиторий документации → индекс → деплой на VM)

В репозитории есть пример пайплайна [`.gitlab-ci.yml`](./.gitlab-ci.yml) для сценария:

- скачать документацию из **внешнего git-репозитория**
- собрать индекс из markdown (`npm run reindex`, данные в `DATA_DIR/pages`)
- задеплоить на VM по SSH и перезапустить `docker compose`, чтобы HTTP-сервер поднялся с актуальными `pages.json/index.json`

### CI/CD variables (настраиваются в GitLab → Settings → CI/CD → Variables)

Переменные для скачивания документации:

- `DOCS_REPO_URL` — URL внешнего репозитория документации (SSH или HTTPS)
- `DOCS_REF` — ветка/тег (по умолчанию: `main`)
- `DOCS_SUBDIR` — подкаталог в репозитории документации с markdown-деревом (по умолчанию: `docs`)
- `DOCS_SSH_PRIVATE_KEY` — **опционально**, SSH ключ для доступа к docs repo (если `DOCS_REPO_URL` по SSH)
- `DOCS_HTTP_TOKEN` — **опционально**, токен для доступа по HTTPS (используется через `~/.netrc`)
- `DOCS_HTTP_USER` — **опционально**, логин для `~/.netrc` (по умолчанию: `oauth2`, удобно для GitLab)

Переменные для деплоя на VM:

- `DEPLOY_HOST` — хост VM (DNS/IP)
- `DEPLOY_USER` — пользователь на VM
- `DEPLOY_PATH` — каталог на VM, где лежит сервис
- `DEPLOY_SSH_PRIVATE_KEY` — SSH ключ для деплоя
- `DEPLOY_SSH_PORT` — **опционально**, порт SSH (по умолчанию: `22`)
- `DEPLOY_COMPOSE_SERVICE` — **опционально**, имя сервиса compose (по умолчанию: `mcp-service`)
- `DEPLOY_HEALTHCHECK_URL` — **опционально**, URL для проверки после деплоя (например `http://<host>:3333/health`)

### Ожидаемая структура на VM (`DEPLOY_PATH`)

Пайплайн предполагает, что на VM уже есть каталог сервиса с `docker-compose.yml` и исходниками (а CI обновляет только `data/`):

```
DEPLOY_PATH/
  docker-compose.yml
  package.json
  src/
  data/              # обновляется из CI (pages/, pages.json, index.json, assets/)
```

После доставки `data.tgz` CI выполняет:

- `docker compose up -d --remove-orphans`
- `docker compose restart mcp-service` (чтобы сервер перечитал индекс, т.к. он кэшируется в памяти процесса)

### Расписание (Schedule)

Чтобы документация/индекс обновлялись регулярно:

1. GitLab → **CI/CD → Schedules** → Create a new schedule
2. Выберите ветку `master`
3. Добавьте нужные variables (например `DOCS_REPO_URL`, `DOCS_REF`, `DOCS_SUBDIR`)

Job `deploy_vm` в `.gitlab-ci.yml` уже настроен так, чтобы запускаться только для `master` и `schedule` (и не запускаться в Merge Request pipeline).

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

- `search_docs(query, limit?)`
  - Ищет по индексу документации и возвращает список результатов с `title`, `url`, `excerpt`, `headings`.
  - `limit` ограничивает количество результатов (1–20, по умолчанию 5).
- `get_page(slug | url)`
  - Возвращает полный контент страницы (markdown-текст, headings, codeBlocks, links, breadcrumbs).
  - `slug` — короткая форма (например, `doc_recursive_helper`).
  - `url` — полный адрес страницы документации.
- `get_examples(topic, limit?)`
  - Ищет страницы по теме и извлекает фрагменты кода.
    - Делает search_docs(topic, limit) по индексу.
    - Берёт первые подходящие страницы и вытаскивает их codeBlocks.
    - Возвращает список примеров с slug, title, url, code.
  - `limit` ограничивает количество примеров (1–20, по умолчанию 5).
- `explain_concept(name)`
  - Возвращает краткое описание концепта и ссылку на наиболее релевантную страницу.
    - Делает search_docs(name, 3).
    - Берёт самый релевантный результат и возвращает:
      - summary — это excerpt из результата,
      - page — основная ссылка,
      - related — оставшиеся 1–2 страницы.
  - В `related` добавляет похожие разделы документации.

## stdio-режим

stdio — MCP-сервер общается с IDE через стандартные потоки ввода/вывода. Это нативный режим MCP: быстрее, проще в настройке, без сети и портов. Подходит для локального использования.

Транспорт и формат обмена:
- Общение по stdin/stdout.
- Формат: JSON-RPC 2.0, построчно или через Content-Length.
  - Построчно — каждое сообщение это одна JSON-строка, разделенная \n. Сервер читает строки и парсит каждую как отдельный JSON-RPC запрос.
  - Через Content-Length — перед сообщением идут заголовки (как в LSP). Сервер сначала читает длину, потом ровно столько байт JSON-тела.

Использовать можно не только из IDE, но и как локальную сервис-утилиту:
- CLI/скрипты: можно запускать сервер и слать ему JSON-RPC из скриптов (например, на CI или для массового прогрева кэша).
- Мост/прокси: stdio удобнее как backend для собственного HTTP-прокси — он проще, чем держать внутри сервера HTTP-слой.
- Интеграции: другой агент/процесс может общаться с MCP через pipe/stdin-stdout, без открытого порта.
- Безопасность: нет открытых портов, меньше требований к сетевой конфигурации.

### Примеры stdio-запросов

```json
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "search_docs",
        "arguments": {
            "query": "Performance Enhancement"
        }
    }
}
```

## HTTP-режим

http — режим, в котором MCP-сервер поднимает HTTP-endpoint и принимает запросы по сети. Удобно для внешних клиентов и инструментов (например, HTTPYac), но требует поднять отдельный процесс и порт.

- Сервер поднимается командой `npm run start:http` (порт `HTTP_PORT`, по умолчанию `3333`).
- Каждый инструмент доступен через `POST /tools/{toolName}` с JSON-телом аргументов.
- Для проверки доступен `GET /health`.

### Примеры HTTP-запросов

Подходят для инструментов типа HTTPYac, плагинов HTTP Request в IDE.

```http
POST http://localhost:3333/tools/search_docs
Content-Type: application/json

{
  "query": "Как работает модуль Performance Enhancement?",
  "limit": 5
}
```

```http
POST http://localhost:3333/tools/search_docs
Content-Type: application/json

{
  "query": "подключение к DevExpress XAF",
  "limit": 5
}
```

```http
POST http://localhost:3333/tools/get_page
Content-Type: application/json

{
  "slug": "doc_recursive_helper"
}
```

```http
POST http://localhost:3333/tools/get_page
Content-Type: application/json

{
  "url": "https://documentation.galaktika-soft.com/xafari/doc_recursive_helper"
}
```

```http
POST http://localhost:3333/tools/get_examples
Content-Type: application/json

{
  "topic": "Business Components",
  "limit": 5
}
```

```http
POST http://localhost:3333/tools/explain_concept
Content-Type: application/json

{
  "name": "Security System"
}
```

## Формат хранения

- Сырые страницы сохраняются в `data/pages/*.md` с метаданными в заголовке.
- `pages.json` формируется из markdown-файлов после завершения краулинга (по умолчанию это **NDJSON**: один JSON-объект на строку, чтобы файл можно было читать потоково даже при больших объёмах).
- При сохранении учитываются breadcrumbs: страницы попадают в поддиректории по темам.
- Ассеты (PDF/картинки) сохраняются в `data/assets`, ссылки в markdown остаются абсолютными.

## Ручное пополнение документации

1. Создайте `.md` в `data/pages` (подкаталоги = breadcrumbs).
2. Добавьте YAML-front-matter с минимумом полей:
   ```
   ---
   slug: my_custom_doc
   url: https://example.local/my_custom_doc
   title: Мой документ
   breadcrumbs:
     - Custom
     - Docs
   ---
   ```
3. Добавьте тело документа ниже фронт-маттера.
4. Пересоберите индекс без краулинга:
   - `npm run reindex`

## Логи

Структурированные логи пишутся в `data/logs/mcp.jsonl` (JSON Lines) при `DATA_DIR=./data` и дефолтном `LOG_FILE=logs/mcp.jsonl`.