@hubex/mcp 0.3.0 → 0.4.0

package/dist/guides/loader.js

@@ -26,7 +26,11 @@ export function loadGuide(topic, dir = GUIDES_DIR) {
     if (!existsSync(file)) {
         throw new Error(`Гайд "${topic}" не найден.`);
     }
-    const text = readFileSync(file, "utf8");
+    // Фронтматтер (`sources`, `content_hash`) нужен скрипту сверки с вики, а не
+    // модели: ~250 лишних символов на каждое чтение, а у start — в системном промпте.
+    const text = readFileSync(file, "utf8")
+        .replace(/^---\n[\s\S]*?\n---\n/, "")
+        .trim();
     guideCache.set(topic, text);
     return text;
 }

package/dist/server.js

@@ -11,7 +11,22 @@ import { HubexClient } from "./http.js";
 import { EndpointIndex, loadIndexFile } from "./index/store.js";
 import { SchemaProvider } from "./schema/describe.js";
 import { buildRegistry } from "./tools/registry.js";
+import { topicIndex } from "./tools/guides.js";
+import { loadGuide } from "./guides/loader.js";
 import { PACKAGE_ROOT, indexFileFor, swaggerDirFor } from "./paths.js";
+/**
+ * Уезжает клиенту при `initialize` — единственный канал, который доходит до
+ * модели до любого вызова инструмента: у клиентов с ленивой подгрузкой схем
+ * до первого вызова видно только имя инструмента, без описания.
+ *
+ * Поэтому здесь не просьба прочитать гайд, а сам стартовый гайд — порядок
+ * работы, протокол и подводные камни — и список топиков, который иначе
+ * доступен только из описания `hubex_get_guide`. Текст берётся из
+ * docs/guides/start.md, чтобы instructions и сам гайд не разъезжались.
+ */
+export function serverInstructions() {
+    return `${loadGuide("start")}\n\n## Гайды по областям\n\n${topicIndex()}.`;
+}
 /** Версия сервера = версия пакета: одна точка правды при релизе. */
 function packageVersion() {
     const pkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
@@ -32,7 +47,7 @@ export function createServer(config) {
         index,
         schemas,
     });
-    const server = new Server({ name: "hubex-mcp", version: packageVersion() }, { capabilities: { tools: {} } });
+    const server = new Server({ name: "hubex-mcp", version: packageVersion() }, { capabilities: { tools: {} }, instructions: serverInstructions() });
     // Провайдер создаётся раньше сервера, поэтому способ ввода вносится сюда, а не в конструктор.
     if (config.authMode === "token")
         auth.setPrompter(createElicitPrompter(server));

package/dist/tools/guides.js

@@ -45,6 +45,14 @@ const TOPIC_GROUPS = [
     },
 ];
 export const GUIDE_TOPICS = TOPIC_GROUPS.flatMap((g) => Object.keys(g.topics));
+/**
+ * Топики по областям, без описаний — для `instructions` сервера. Полный каталог
+ * с описаниями живёт в описании инструмента, но у клиентов с ленивой подгрузкой
+ * схем оно до первого вызова не видно, поэтому названия дублируем сюда.
+ */
+export function topicIndex() {
+    return TOPIC_GROUPS.map((g) => `${g.title.toLowerCase()} — ${Object.keys(g.topics).join(", ")}`).join("; ");
+}
 function guideTool() {
     const topicList = TOPIC_GROUPS.map((g) => `${g.title}: ` +
         Object.entries(g.topics)

package/docs/guides/start.md

@@ -40,19 +40,23 @@ HubEx REST API организован по сервисам: у каждого
 
 ## Порядок работы с этим сервером
 
-1. `hubex_list_scopes` — узнать, какие сервисы и предметные области доступны.
-2. `hubex_search_*_endpoints` (например поиск по сервису или ключевому
-   слову) — найти нужный эндпоинт, не читая весь swagger вручную.
+1. `hubex_get_guide` с топиком нужной области (заявки, объекты, компании,
+   пользователи, материалы, настройки тенанта) — короткий порядок вызовов,
+   обязательные поля и типичные ошибки из бизнес-документации HubEx.
+   **Это первый шаг, а не факультативный**: гайд называет нужные эндпоинты
+   сам, поэтому шаг 2 после него обычно не нужен, а без него шаги 2–3
+   превращаются в перебор похожих по названию эндпоинтов.
+2. `hubex_search_*_endpoints` — найти эндпоинт, если гайд его не назвал или
+   подходящей области не нашлось. Запрос можно писать по-русски.
 3. `hubex_describe_endpoint` — получить полную JSON Schema тела и параметров
    найденного эндпоинта, уже с аннотациями бизнес-полей (описание,
    обязательность, справочник-подсказка, если поле есть в оверлее).
 4. `hubex_request_*` — выполнить сам HTTP-запрос к HubEx с телом, собранным
    по схеме из шага 3.
 
-Перед первой работой с конкретной предметной областью (заявки, объекты,
-компании, пользователи) стоит сначала прочитать соответствующий гайд
-(`hubex_get_guide`) — там короткий порядок вызовов, обязательные поля и
-типичные ошибки, собранные из бизнес-документации HubEx.
+`hubex_list_scopes` — вспомогательный инструмент: показывает сервисы и ресурсы
+внутри них, когда неизвестна даже область. В обычном сценарии он не нужен,
+шаг 1 отвечает на тот же вопрос точнее.
 
 ## Подводные камни
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubex/mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "MCP server for managing HubEx test data (tasks, assets, companies, users) via the HubEx REST API",
   "author": "HubEx Team",