KsaiLabKsaiLab
ИИ

MCP-сервер

Подключите вашу документацию к AI-инструментам через нативный MCP-сервер.

О MCP-серверах

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

Этот шаблон документации включает встроенный MCP-сервер, подготавливая ваши материалы для более широкой AI-экосистемы: к вашей документации может подключиться любой MCP-клиент (например, Claude, Cursor, VS Code и другие).

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

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

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

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

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

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

Например, если ваша документация размещена по адресу https://docs.ksailab.fxserver.ru, то URL вашего MCP-сервера будет https://docs.ksailab.fxserver.ru/mcp.

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

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

nuxt.config.ts
export default defineNuxtConfig({
  mcp: {
    enabled: false,
  },
})

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

Сейчас MCP-сервер KsaiLab Docs предоставляет 11 инструментов. Этого уже достаточно для быстрого агентного потока без ручного перебора markdown-файлов.

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

  • 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.

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

Для AI-агентов быстрее всего работает такой порядок:

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

Настройка

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

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

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

Visual Studio Code

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

Установить в VS Code

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

.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. Добавьте следующую конфигурацию:
.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "my-docs": {
      "type": "http",
      "url": "https://docs.ksailab.fxserver.ru/mcp"
    }
  }
}

Zed

  1. Откройте Zed и перейдите в Settings > Open Settings
  2. Перейдите к файлу настроек JSON
  3. Добавьте следующую конфигурацию контекстного сервера:
.config/zed/settings.json
{
  "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/mcp/tools/search.ts
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:

server/mcp/resources/changelog.ts
export default defineMcpResource({
  file: 'CHANGELOG.md',
  metadata: {
    description: 'Project changelog',
  },
})

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

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

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

server/mcp/prompts/migration-help.ts
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-сервер для помощи при миграции
server/mcp/migration.ts
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, создав в проекте инструмент с тем же именем:

server/mcp/tools/list-pages.ts
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) }],
    }
  },
})
Ознакомьтесь с документацией MCP Toolkit, чтобы узнать больше об инструментах, ресурсах, промптах, обработчиках и расширенной конфигурации.

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

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

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 для быстрого трассирования аргументов в бизнес-разделе.

Реестр Источников

Интеграция LLM

Генерируйте файлы контента, готовые для AI, с помощью модуля Nuxt LLMs