MCP-сервер

О MCP-серверах

Model Context Protocol (MCP) — это открытый протокол, который создаёт стандартизированные связи между AI-приложениями и внешними сервисами, например документацией.

Документация КсаиЛаб включает встроенный MCP-сервер: к ней может подключиться любой MCP-клиент — Claude, Codex, Cursor, VS Code и другие.

Как работают MCP-серверы

Когда MCP-сервер подключён к AI-инструменту, LLM может решить использовать ваши инструменты документации во время генерации ответа:

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

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

Подключение к вашему MCP-серверу

Ваш MCP-сервер автоматически доступен по пути /mcp на URL вашей документации.

Отключение MCP-сервера

Если вы хотите отключить MCP-сервер, это можно сделать в nuxt.config.ts:

export default defineNuxtConfig({
  mcp: {
    enabled: false,
  },
})

Встроенные инструменты

MCP-сервер KsaiLab Docs предоставляет 12 инструментов.

Правила чтения корпуса

• get-doc-policy — какой документ является каноническим по каждой теме, как трактовать статус страницы и какие ловушки есть в корпусе. Вызывать первым перед содержательными вопросами про архитектуру, авторизацию, API или грант.

Общая навигация и поиск

• get-navigation — дерево навигации по документации.
• list-pages — полный список страниц с title, path, description.
• search-pages(query, limit) — поиск по заголовкам, путям и содержимому.
• resolve-page(query, limit) — поиск лучшего path, если агент знает только примерное название страницы.

Работа со страницами

• get-page(path) — полное markdown-содержимое страницы.
• get-page-headings(path, minDepth, maxDepth) — только структура заголовков и anchor-ов.
• get-page-summary(path) — краткая структурированная выжимка по странице.
• list-page-links(path) — все внутренние и внешние ссылки из страницы.
• get-related-pages(path) — parent, siblings, children, breadcrumbs, previous и next.

Специализированные инструменты KsaiLab

• get-fact-by-id(id) — lookup факта F-* из facts base раздела startup-analysis.
• get-permission-by-key(key, limit) — lookup capability из permission-catalog.md.

Рекомендуемый агентный поток

1. get-doc-policy — до всего остального: какой источник канонический по теме вопроса.
2. resolve-page — если пользователь назвал документ приблизительно.
3. search-pages — если известна тема, но неизвестен точный путь.
4. get-page-summary или get-page-headings — если сначала нужно быстро оценить релевантность страницы.
5. get-page — когда уже нужен полный текст.
6. get-related-pages и list-page-links — если агент продолжает чтение по соседним или связанным материалам.
7. get-fact-by-id и get-permission-by-key — если вопрос уже ссылается на конкретный факт или capability.
8. list-pages — только если нужен полный обзор всего корпуса документации.

Метаданные страниц

Корпус писался в разное время и содержит страницы, описывающие разные состояния системы. Чтобы агент не принимал устаревшее за текущее, каждая страница несёт фронтматтер:

Как это используется:

• list-pages, search-pages, resolve-page и get-navigation не возвращают страницы с mcp: false — так из выдачи уходят шаблонные материалы Nuxt UI, не относящиеся к КсаиЛаб;
• search-pages и resolve-page понижают в ранжировании legacy и superseded, чтобы канонические страницы были выше;
• get-page возвращает поле notice с человекочитаемым предупреждением, если страница не current.

При добавлении новой страницы заполняйте title и description обязательно: без них страница попадает в выдачу без внятного описания, и агенту приходится грузить полный текст, чтобы понять релевантность.

Настройка

MCP-сервер использует HTTP-транспорт и может быть установлен в разных AI-инструментах.

Codex

Добавьте сервер через Codex CLI:

codex mcp add ksailabDocs --url https://docs.ksailab.fxserver.ru/mcp
codex mcp list

Claude Code

Добавьте сервер через команду CLI:

claude mcp add --transport http my-docs https://docs.ksailab.fxserver.ru/mcp

Cursor

Либо вручную создайте/обновите файл .cursor/mcp.json в корне проекта:

{
  "mcpServers": {
    "my-docs": {
      "type": "http",
      "url": "https://docs.ksailab.fxserver.ru/mcp"
    }
  }
}

Visual Studio Code

Убедитесь, что установлены расширения GitHub Copilot и GitHub Copilot Chat.

Либо вручную создайте/обновите файл .vscode/mcp.json:

{
  "servers": {
    "my-docs": {
      "type": "http",
      "url": "https://docs.ksailab.fxserver.ru/mcp"
    }
  }
}

Windsurf

1. Откройте Windsurf и перейдите в Settings > Windsurf Settings > Cascade
2. Нажмите кнопку Manage MCPs, затем выберите опцию View raw config
3. Добавьте следующую конфигурацию:

{
  "mcpServers": {
    "my-docs": {
      "type": "http",
      "url": "https://docs.ksailab.fxserver.ru/mcp"
    }
  }
}

Zed

1. Откройте Zed и перейдите в Settings > Open Settings
2. Перейдите к файлу настроек JSON
3. Добавьте следующую конфигурацию контекстного сервера:

{
  "context_servers": {
    "my-docs": {
      "source": "custom",
      "command": "npx",
      "args": ["mcp-remote", "https://docs.ksailab.fxserver.ru/mcp"],
      "env": {}
    }
  }
}

Настройка

Так как этот шаблон использует модуль @nuxtjs/mcp-toolkit, вы можете расширять MCP-сервер: добавлять пользовательские инструменты, ресурсы, промпты и обработчики.

Добавление пользовательских инструментов

Инструменты живут в server/mcp/tools/. Общий слой чтения корпуса — server/utils/mcp-docs.ts: функция loadDocsIndex уже отбрасывает страницы с mcp: false и нормализует status, updated и раздел, поэтому новые инструменты стоит строить на ней, а не на прямом queryCollection.

import { z } from 'zod'

export default defineMcpTool({
  description: 'Search documentation by keyword',
  inputSchema: {
    query: z.string().describe('The search query'),
  },
  handler: async ({ query }) => {
    const results = await searchDocs(query)
    return {
      content: [{ type: 'text', text: JSON.stringify(results) }],
    }
  },
})

Добавление ресурсов

Предоставляйте файлы или источники данных как MCP-ресурсы в директории server/mcp/resources/. Самый простой способ — использовать свойство file:

export default defineMcpResource({
  file: 'CHANGELOG.md',
  metadata: {
    description: 'Project changelog',
  },
})

Это автоматически обрабатывает генерацию URI, определение MIME-типа и чтение файла.

Добавление промптов

Создавайте переиспользуемые промпты для AI-помощников в директории server/mcp/prompts/:

import { z } from 'zod'

export default defineMcpPrompt({
  description: 'Get help with migrating between versions',
  inputSchema: {
    fromVersion: z.string().describe('Current version'),
    toVersion: z.string().describe('Target version'),
  },
  handler: async ({ fromVersion, toVersion }) => {
    return {
      messages: [{
        role: 'user',
        content: {
          type: 'text',
          text: `Help me migrate from version ${fromVersion} to ${toVersion}. What are the breaking changes and steps I need to follow?`,
        },
      }],
    }
  },
})

Добавление пользовательских обработчиков

Обработчики позволяют создавать отдельные MCP-эндпоинты со своими инструментами, ресурсами и промптами. Это удобно, чтобы предоставлять разные возможности на разных маршрутах.

Например, у вас могут быть:

• /mcp - Основной MCP-сервер для документации
• /mcp/migration - Выделенный MCP-сервер для помощи при миграции

import { z } from 'zod'

const migrationTool = defineMcpTool({
  name: 'migrate-v3-to-v4',
  description: 'Migrate code from version 3 to version 4',
  inputSchema: {
    code: z.string().describe('The code to migrate'),
  },
  handler: async ({ code }) => {
    // Migration logic
    return {
      content: [{ type: 'text', text: migratedCode }],
    }
  },
})

export default defineMcpHandler({
  route: '/mcp/migration',
  name: 'Migration Assistant',
  version: '1.0.0',
  tools: [migrationTool],
})

Переопределение встроенных инструментов

Вы можете переопределить встроенные инструменты list-pages или get-page, создав в проекте инструмент с тем же именем:

import { z } from 'zod'

export default defineMcpTool({
  description: 'Custom list pages implementation',
  inputSchema: {
    locale: z.string().optional(),
    category: z.string().optional(),
  },
  handler: async ({ locale, category }) => {
    const pages = await getCustomPageList(locale, category)
    return {
      content: [{ type: 'text', text: JSON.stringify(pages) }],
    }
  },
})

Что ещё можно добавить позже

Текущего набора уже достаточно для большинства агентных сценариев. Если документация продолжит расти, следующими кандидатами будут:

search-pages-advanced

Поиск с фильтрацией по разделу, например только /platform-design или только /grant.

get-section

Возврат только одной секции страницы по path + heading, без загрузки всего документа.

get-changed-pages

Список страниц, изменившихся относительно git ref, ветки или даты. Полезно для review-агентов и changelog sync.

search-code-blocks

Поиск только по примерам команд, конфигов и code snippets.

get-source-by-id

Поиск источника INT-*, EXT-*, VID-* по source-registry.md для быстрого трассирования аргументов в бизнес-разделе.