@oneentry/mcp-server 1.1.5 → 1.1.7

package/README.md

@@ -1,64 +1,132 @@
 # OneEntry MCP Server
 
-MCP server for OneEntry SDK — serves rules and skills to Claude Code automatically from a remote server.
+MCP server for OneEntry SDK — gives AI assistants (Claude Code, Cursor, Windsurf) the rules, skills and SDK documentation needed to build OneEntry projects correctly.
 
-Users don't need to copy any files. Connect once — always get the latest rules.
-
-## How it works
+---
 
-| MCP concept | What it serves |
-|-------------|----------------|
-| **Resources** | Rules (`oneentry://rules/*`) + `CLAUDE.md` — readable context documents |
-| **Prompts** | Skills (`create-page`, `inspect-api`, etc.) — invocable by the user |
+## Two ways to connect
 
-Content is fetched from GitHub (configurable) and cached for 5 minutes.
+|              | npm package                          | Remote server                                |
+| ------------ | ------------------------------------ | -------------------------------------------- |
+| **Install**  | `npx -y @oneentry/mcp-server@latest` | No install — just a URL                      |
+| **Works in** | Claude Code only                     | Claude Code, Cursor, Windsurf                |
+| **Requires** | Nothing                              | OneEntry project token + URL                 |
+| **Provides** | Rules + Skills (context docs)        | Rules + Skills + **SDK documentation tools** |
+| **Best for** | Quick local setup                    | Full AI-assisted development                 |
 
 ---
 
-## Quick start for users
+## Option A — Remote server (recommended)
+
+No installation. Works in Claude Code, Cursor, and Windsurf.
 
-### Option 1 — npx (no install needed)
+Provides everything the npm package does, plus **8 SDK documentation tools** that the AI calls automatically to get module docs, code examples, and TypeScript types.
 
-Add to `~/.claude/claude_desktop_config.json` or `.mcp.json` in your project:
+You will need:
+
+- **`YOUR_TOKEN`** — API token from your OneEntry admin panel
+- **`yourproject.oneentry.cloud`** — your OneEntry project domain
+
+### Claude Code — `.mcp.json` in project root
 
 ```json
 {
   "mcpServers": {
     "oneentry": {
-      "command": "npx",
-      "args": ["-y", "@oneentry/mcp-server@latest"]
+      "type": "streamable-http",
+      "url": "https://mcp-sdk-js.oneentry.cloud/mcp",
+      "headers": {
+        "X-OneEntry-Token": "YOUR_TOKEN",
+        "X-OneEntry-URL": "https://yourproject.oneentry.cloud"
+      }
     }
   }
 }
 ```
 
-### Option 2 — global install
-
-```bash
-npm install -g @oneentry/mcp-server
-```
+### Cursor — `~/.cursor/mcp.json`
 
 ```json
 {
   "mcpServers": {
     "oneentry": {
-      "command": "oneentry-mcp"
+      "url": "https://mcp-sdk-js.oneentry.cloud/mcp",
+      "headers": {
+        "X-OneEntry-Token": "YOUR_TOKEN",
+        "X-OneEntry-URL": "https://yourproject.oneentry.cloud"
+      }
     }
   }
 }
 ```
 
+### Windsurf
+
+Add via **Settings → MCP Servers**:
+
+```text
+URL:            https://mcp-sdk-js.oneentry.cloud/mcp?token=YOUR_TOKEN&url=https://yourproject.oneentry.cloud
+Authentication: None
+```
+
+### Alternative — custom headers (instead of query params)
+
+```text
+URL:              https://mcp-sdk-js.oneentry.cloud/mcp
+X-OneEntry-Token: YOUR_TOKEN
+X-OneEntry-URL:   https://yourproject.oneentry.cloud
+```
+
 ---
 
-## ⚠️ Required: add to your project's CLAUDE.md
+## Option B — npm package (Claude Code only)
+
+Serves rules and skills as readable context documents. No token required.
+
+**npx — no install:**
+
+```json
+{
+    "mcpServers": {
+        "oneentry": {
+            "command": "npx",
+            "args": ["-y", "@oneentry/mcp-server@latest"]
+        }
+    }
+}
+```
+
+**Local install (per project):**
 
-After connecting the MCP server, create or edit `CLAUDE.md` in the root of your project and add:
+```bash
+npm install --save-dev @oneentry/mcp-server
+```
 
+```json
+{
+    "mcpServers": {
+        "oneentry": {
+            "command": "./node_modules/.bin/oneentry-mcp"
+        }
+    }
+}
 ```
-This project uses OneEntry CMS. Before doing any work, call the `load-context` tool from the oneentry MCP server.
+
+**Global install:**
+
+```bash
+npm install -g @oneentry/mcp-server
 ```
 
-> **Without this, Claude Code will not automatically load OneEntry SDK rules and may produce incorrect code.**
+```json
+{
+    "mcpServers": {
+        "oneentry": {
+            "command": "oneentry-mcp"
+        }
+    }
+}
+```
 
 ---
 
@@ -66,50 +134,48 @@ This project uses OneEntry CMS. Before doing any work, call the `load-context` t
 
 Read them in Claude Code by typing `@oneentry://rules/<name>`:
 
-| URI | Description |
-|-----|-------------|
-| `oneentry://claude-md` | Full CLAUDE.md — main SDK instructions |
-| `oneentry://rules/linting` | Linting rules |
-| `oneentry://rules/typescript` | TypeScript rules |
-| `oneentry://rules/nextjs-pages` | Next.js pages, params as Promise |
-| `oneentry://rules/attribute-values` | attributeValues access by type |
-| `oneentry://rules/attribute-sets` | AttributeSets — schema vs values |
-| `oneentry://rules/auth-provider` | AuthProvider — auth/signUp rules |
-| `oneentry://rules/tokens` | Tokens & makeUserApi rules |
-| `oneentry://rules/server-actions` | Server Actions rules |
-| `oneentry://rules/forms` | Forms & FormsData rules |
-| `oneentry://rules/orders` | Orders & Payments rules |
-| `oneentry://rules/localization` | Localization, locale from params |
-| `oneentry://rules/product-statuses` | Product statuses rules |
+| URI                                 | Description                            |
+| ----------------------------------- | -------------------------------------- |
+| `oneentry://claude-md`              | Full CLAUDE.md — main SDK instructions |
+| `oneentry://rules/linting`          | Linting rules                          |
+| `oneentry://rules/typescript`       | TypeScript rules                       |
+| `oneentry://rules/nextjs-pages`     | Next.js pages, params as Promise       |
+| `oneentry://rules/attribute-values` | attributeValues access by type         |
+| `oneentry://rules/attribute-sets`   | AttributeSets — schema vs values       |
+| `oneentry://rules/auth-provider`    | AuthProvider — auth/signUp rules       |
+| `oneentry://rules/tokens`           | Tokens & makeUserApi rules             |
+| `oneentry://rules/server-actions`   | Server Actions rules                   |
+| `oneentry://rules/forms`            | Forms & FormsData rules                |
+| `oneentry://rules/orders`           | Orders & Payments rules                |
+| `oneentry://rules/localization`     | Localization, locale from params       |
+| `oneentry://rules/product-statuses` | Product statuses rules                 |
 
 ## Available prompts (skills)
 
-Invoke in Claude Code with `/skill-name`:
-
-| Prompt | Description |
-|--------|-------------|
-| `oneentry-context` | Load full SDK context at session start |
-| `setup-nextjs` | Initialize Next.js project |
-| `setup-oneentry` | Initialize SDK in a Next.js project |
-| `inspect-api` | Inspect real API markers and structure |
-| `create-page` | Create Next.js page with CMS content |
-| `create-auth` | Auth/registration form |
-| `create-product-list` | Product catalog with filters and pagination |
-| `create-product-card` | Single product card |
-| `create-product-page` | Single product page with gallery and related products |
-| `create-cart-manager` | Cart — Redux + persist |
-| `create-favorites` | Favorites — Redux + persist |
-| `create-filter-panel` | Filter panel with FilterContext |
-| `create-checkout` | Checkout form + payment |
-| `create-orders-list` | User orders list |
-| `create-profile` | User profile page |
-| `create-form` | Dynamic form from Forms API |
-| `create-reviews` | Reviews with hierarchy |
-| `create-menu` | Navigation menu with submenus |
-| `create-search` | Search bar with debounce |
-| `create-locale-switcher` | Locale switcher |
-| `create-server-action` | Next.js Server Action |
-| `create-subscription-events` | Price/availability subscription |
-| `setup-playwright` | Setup Playwright testing framework |
-
-
+Invoke in Claude Code with `/mcp__oneentry__<name>`:
+
+| Prompt                       | Description                                           |
+| ---------------------------- | ----------------------------------------------------- |
+| `oneentry-context`           | Reload full SDK context manually                      |
+| `setup-nextjs`               | Initialize Next.js project                            |
+| `setup-oneentry`             | Initialize SDK in a Next.js project                   |
+| `inspect-api`                | Inspect real API markers and structure                |
+| `create-page`                | Create Next.js page with CMS content                  |
+| `create-auth`                | Auth/registration form                                |
+| `create-product-list`        | Product catalog with filters and pagination           |
+| `create-product-card`        | Single product card                                   |
+| `create-product-page`        | Single product page with gallery and related products |
+| `create-cart-manager`        | Cart — Redux + persist                                |
+| `create-favorites`           | Favorites — Redux + persist                           |
+| `create-filter-panel`        | Filter panel with FilterContext                       |
+| `create-checkout`            | Checkout form + payment                               |
+| `create-orders-list`         | User orders list                                      |
+| `create-profile`             | User profile page                                     |
+| `create-form`                | Dynamic form from Forms API                           |
+| `create-reviews`             | Reviews with hierarchy                                |
+| `create-menu`                | Navigation menu with submenus                         |
+| `create-search`              | Search bar with debounce                              |
+| `create-locale-switcher`     | Locale switcher                                       |
+| `create-server-action`       | Next.js Server Action                                 |
+| `create-subscription-events` | Price/availability subscription                       |
+| `setup-playwright`           | Setup Playwright testing framework                    |

package/dist/index.js

@@ -5,127 +5,214 @@ import { z } from "zod";
 import { fetchContent } from "./content.js";
 import { RULES, SKILLS } from "./registry.js";
 import { CLAUDE_MD_PATH, SERVER_NAME, VERSION } from "./config.js";
-// ---------------------------------------------------------------------------
-// Server
-// ---------------------------------------------------------------------------
-const server = new McpServer({ name: SERVER_NAME, version: VERSION });
-// ---------------------------------------------------------------------------
-// Resources — rules + CLAUDE.md
-// ---------------------------------------------------------------------------
-server.registerResource("OneEntry SDK — Main Instructions (CLAUDE.md)", "oneentry://claude-md", {
-    description: "Full system prompt with OneEntry SDK rules, patterns, anti-hallucination guidelines and module reference",
-    mimeType: "text/markdown",
-}, async (uri) => {
-    const text = await fetchContent(CLAUDE_MD_PATH);
-    return { contents: [{ uri: uri.toString(), mimeType: "text/markdown", text }] };
-});
-for (const rule of RULES) {
-    server.registerResource(rule.displayName, `oneentry://rules/${rule.name}`, { description: rule.description, mimeType: "text/markdown" }, async (uri) => {
-        const text = await fetchContent(rule.path);
+/**
+ * Точка входа MCP-сервера OneEntry SDK.
+ *
+ * ## Архитектура
+ *
+ * MCP (Model Context Protocol) — протокол, по которому AI-клиент (Claude Code,
+ * Cursor, Windsurf) общается с внешним сервером контекста. Сервер предоставляет
+ * три типа объектов:
+ *
+ * - **Resources** — документы, которые AI может прочитать по URI (`@oneentry://...`).
+ *   Аналог файловой системы: клиент сам решает, когда читать.
+ *
+ * - **Prompts** — готовые шаблоны сообщений (скиллы). AI-клиент подставляет их
+ *   в чат по команде пользователя (`/mcp__oneentry__<name>`).
+ *
+ * - **Tools** — функции, которые AI вызывает автоматически по ситуации.
+ *   Возвращают текст прямо в контекст разговора.
+ *
+ * ## Как загружается CLAUDE.md
+ *
+ * При подключении MCP-сервер отвечает на `initialize`-запрос клиента и
+ * включает в ответ поле `instructions`. Claude Code читает это поле и
+ * автоматически добавляет его в системный контекст сессии — без каких-либо
+ * дополнительных действий от пользователя.
+ *
+ * Поэтому CLAUDE.md загружается **первым делом**, до регистрации всего
+ * остального, и передаётся в конструктор `McpServer` через `{ instructions }`.
+ */
+async function main() {
+    // ---------------------------------------------------------------------------
+    // Загрузка CLAUDE.md и создание сервера
+    // ---------------------------------------------------------------------------
+    /**
+     * Загружаем CLAUDE.md с GitHub до создания сервера — нам нужно передать
+     * содержимое в конструктор как `instructions`.
+     *
+     * `instructions` — стандартное поле MCP InitializeResult. Клиент получает
+     * его в ответ на первый `initialize`-запрос и автоматически включает в
+     * системный промпт сессии. Именно так другие MCP-серверы "работают сразу"
+     * без дополнительной настройки CLAUDE.md в проекте.
+     */
+    const instructions = await fetchContent(CLAUDE_MD_PATH);
+    const server = new McpServer({ name: SERVER_NAME, version: VERSION }, { instructions });
+    // ---------------------------------------------------------------------------
+    // Resources — документы для явного чтения по URI
+    // ---------------------------------------------------------------------------
+    /**
+     * Главный ресурс: полный CLAUDE.md как документ.
+     * Доступен в Claude Code по `@oneentry://claude-md`.
+     * Полезен если нужно явно переподгрузить контекст или вставить его в чат.
+     */
+    server.registerResource("OneEntry SDK — Main Instructions (CLAUDE.md)", "oneentry://claude-md", {
+        description: "Full system prompt with OneEntry SDK rules, patterns, anti-hallucination guidelines and module reference",
+        mimeType: "text/markdown",
+    }, async (uri) => {
+        const text = await fetchContent(CLAUDE_MD_PATH);
         return { contents: [{ uri: uri.toString(), mimeType: "text/markdown", text }] };
     });
-}
-// ---------------------------------------------------------------------------
-// Prompts — skills
-// ---------------------------------------------------------------------------
-// Special prompt: load full context from CLAUDE.md
-server.registerPrompt("oneentry-context", {
-    description: "Load full OneEntry SDK context — system instructions, rules and anti-hallucination guidelines. Use this at the start of a session.",
-}, async () => {
-    const text = await fetchContent(CLAUDE_MD_PATH);
-    return {
-        description: "OneEntry SDK — full system context loaded",
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: `The following are the complete instructions and rules for working with OneEntry SDK. Apply them to all subsequent code generation:\n\n${text}`,
-                },
-            },
-        ],
-    };
-});
-// Skills
-for (const skill of SKILLS) {
-    if (skill.hasArguments) {
-        server.registerPrompt(skill.name, {
-            description: skill.description,
-            argsSchema: {
-                arguments: z
-                    .string()
-                    .optional()
-                    .describe(skill.argumentDescription ?? "Optional arguments"),
-            },
-        }, async (args) => {
-            let text = await fetchContent(skill.path);
-            // Replace $ARGUMENTS placeholder (used in inspect-api and create-page skills)
-            if (args.arguments) {
-                text = text.replace(/\$ARGUMENTS/g, args.arguments);
-            }
-            return {
-                description: skill.description,
-                messages: [{ role: "user", content: { type: "text", text } }],
-            };
+    /**
+     * Отдельные правила из registry.ts — каждое доступно по своему URI:
+     * `@oneentry://rules/linting`, `@oneentry://rules/tokens`, и т.д.
+     *
+     * Ресурсы удобны когда нужно прочитать только одно конкретное правило,
+     * не загружая весь CLAUDE.md целиком.
+     */
+    for (const rule of RULES) {
+        server.registerResource(rule.displayName, `oneentry://rules/${rule.name}`, { description: rule.description, mimeType: "text/markdown" }, async (uri) => {
+            const text = await fetchContent(rule.path);
+            return { contents: [{ uri: uri.toString(), mimeType: "text/markdown", text }] };
         });
     }
-    else {
-        server.registerPrompt(skill.name, { description: skill.description }, async () => {
-            const text = await fetchContent(skill.path);
-            return {
+    // ---------------------------------------------------------------------------
+    // Prompts (скиллы) — шаблоны сообщений для вставки в чат
+    // ---------------------------------------------------------------------------
+    /**
+     * Специальный промпт для ручной перезагрузки контекста.
+     * Вызывается командой `/mcp__oneentry__oneentry-context`.
+     *
+     * Возвращает CLAUDE.md завёрнутым в сообщение с ролью `user` — это
+     * стандартный способ подачи контекста через MCP Prompts API.
+     * Клиент вставляет это сообщение в историю чата.
+     */
+    server.registerPrompt("oneentry-context", {
+        description: "Load full OneEntry SDK context — system instructions, rules and anti-hallucination guidelines. Use this at the start of a session.",
+    }, async () => {
+        const text = await fetchContent(CLAUDE_MD_PATH);
+        return {
+            description: "OneEntry SDK — full system context loaded",
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `The following are the complete instructions and rules for working with OneEntry SDK. Apply them to all subsequent code generation:\n\n${text}`,
+                    },
+                },
+            ],
+        };
+    });
+    /**
+     * Регистрируем все скиллы из registry.ts как MCP Prompts.
+     * Каждый скилл — это markdown-инструкция для выполнения конкретной задачи
+     * (создание страницы, формы, корзины и т.д.).
+     *
+     * Скиллы делятся на два типа:
+     * - `hasArguments: true` — принимают аргумент (например, маркер страницы),
+     *   который подставляется вместо плейсхолдера `$ARGUMENTS` в тексте скилла.
+     * - без аргументов — возвращают текст как есть.
+     */
+    for (const skill of SKILLS) {
+        if (skill.hasArguments) {
+            server.registerPrompt(skill.name, {
                 description: skill.description,
-                messages: [{ role: "user", content: { type: "text", text } }],
-            };
-        });
-    }
-}
-// ---------------------------------------------------------------------------
-// Tools
-// ---------------------------------------------------------------------------
-server.registerTool("load-context", {
-    description: "IMPORTANT: Call this tool automatically at the start of EVERY session when working on a project that uses OneEntry CMS or OneEntry SDK. " +
-        "This loads the full OneEntry SDK instructions, rules, and anti-hallucination guidelines into the context. " +
-        "Do not skip this — without it you will make mistakes working with OneEntry API.",
-    inputSchema: {},
-}, async () => {
-    const text = await fetchContent(CLAUDE_MD_PATH);
-    return { content: [{ type: "text", text }] };
-});
-server.registerTool("get-rule", {
-    description: "Fetch the content of a specific OneEntry SDK rule by name",
-    inputSchema: { name: z.string().describe(`Rule name. Available: ${RULES.map((r) => r.name).join(", ")}`) },
-}, async ({ name }) => {
-    const rule = RULES.find((r) => r.name === name);
-    if (!rule) {
-        return { content: [{ type: "text", text: `Unknown rule: ${name}. Available: ${RULES.map((r) => r.name).join(", ")}` }], isError: true };
-    }
-    const text = await fetchContent(rule.path);
-    return { content: [{ type: "text", text }] };
-});
-server.registerTool("get-skill", {
-    description: "Fetch the content of a specific OneEntry skill/slash-command by name",
-    inputSchema: {
-        name: z.string().describe(`Skill name. Available: ${SKILLS.map((s) => s.name).join(", ")}`),
-        arguments: z.string().optional().describe("Optional arguments passed to the skill (replaces $ARGUMENTS placeholder)"),
-    },
-}, async (args) => {
-    const skill = SKILLS.find((s) => s.name === args.name);
-    if (!skill) {
-        return { content: [{ type: "text", text: `Unknown skill: ${args.name}. Available: ${SKILLS.map((s) => s.name).join(", ")}` }], isError: true };
-    }
-    let text = await fetchContent(skill.path);
-    if (args.arguments) {
-        text = text.replace(/\$ARGUMENTS/g, args.arguments);
+                argsSchema: {
+                    arguments: z
+                        .string()
+                        .optional()
+                        .describe(skill.argumentDescription ?? "Optional arguments"),
+                },
+            }, async (args) => {
+                let text = await fetchContent(skill.path);
+                // Подставляем аргумент вместо плейсхолдера $ARGUMENTS в тексте скилла.
+                // Используется, например, в inspect-api (тип данных) и create-page (маркер страницы).
+                if (args.arguments) {
+                    text = text.replace(/\$ARGUMENTS/g, args.arguments);
+                }
+                return {
+                    description: skill.description,
+                    messages: [{ role: "user", content: { type: "text", text } }],
+                };
+            });
+        }
+        else {
+            server.registerPrompt(skill.name, { description: skill.description }, async () => {
+                const text = await fetchContent(skill.path);
+                return {
+                    description: skill.description,
+                    messages: [{ role: "user", content: { type: "text", text } }],
+                };
+            });
+        }
     }
-    return { content: [{ type: "text", text }] };
-});
-// ---------------------------------------------------------------------------
-// Start
-// ---------------------------------------------------------------------------
-async function main() {
+    // ---------------------------------------------------------------------------
+    // Tools — функции, вызываемые AI автоматически по ситуации
+    // ---------------------------------------------------------------------------
+    /**
+     * Инструмент для ручной перезагрузки CLAUDE.md в контекст разговора.
+     * В отличие от `instructions` (которые загружаются один раз при коннекте),
+     * этот tool позволяет получить свежую версию документа прямо в чат —
+     * например, если кэш устарел или контекст был сброшен.
+     */
+    server.registerTool("load-context", {
+        description: "Reload the full OneEntry SDK instructions, rules, and anti-hallucination guidelines into the context. " +
+            "Call this if you need a fresh copy of the SDK documentation.",
+        inputSchema: {},
+    }, async () => {
+        const text = await fetchContent(CLAUDE_MD_PATH);
+        return { content: [{ type: "text", text }] };
+    });
+    /**
+     * Инструмент для загрузки отдельного правила по имени.
+     * AI может вызвать его когда нужно уточнить конкретный аспект SDK
+     * (например, правила работы с токенами или формами) без загрузки всего CLAUDE.md.
+     */
+    server.registerTool("get-rule", {
+        description: "Fetch the content of a specific OneEntry SDK rule by name",
+        inputSchema: { name: z.string().describe(`Rule name. Available: ${RULES.map((r) => r.name).join(", ")}`) },
+    }, async ({ name }) => {
+        const rule = RULES.find((r) => r.name === name);
+        if (!rule) {
+            return { content: [{ type: "text", text: `Unknown rule: ${name}. Available: ${RULES.map((r) => r.name).join(", ")}` }], isError: true };
+        }
+        const text = await fetchContent(rule.path);
+        return { content: [{ type: "text", text }] };
+    });
+    /**
+     * Инструмент для загрузки конкретного скилла по имени.
+     * Аналог вызова промпта, но через tool API — удобно когда AI сам
+     * определяет что нужен тот или иной скилл в процессе работы.
+     * Поддерживает аргументы: подставляет их вместо `$ARGUMENTS` в тексте.
+     */
+    server.registerTool("get-skill", {
+        description: "Fetch the content of a specific OneEntry skill/slash-command by name",
+        inputSchema: {
+            name: z.string().describe(`Skill name. Available: ${SKILLS.map((s) => s.name).join(", ")}`),
+            arguments: z.string().optional().describe("Optional arguments passed to the skill (replaces $ARGUMENTS placeholder)"),
+        },
+    }, async (args) => {
+        const skill = SKILLS.find((s) => s.name === args.name);
+        if (!skill) {
+            return { content: [{ type: "text", text: `Unknown skill: ${args.name}. Available: ${SKILLS.map((s) => s.name).join(", ")}` }], isError: true };
+        }
+        let text = await fetchContent(skill.path);
+        if (args.arguments) {
+            text = text.replace(/\$ARGUMENTS/g, args.arguments);
+        }
+        return { content: [{ type: "text", text }] };
+    });
+    // ---------------------------------------------------------------------------
+    // Запуск транспорта
+    // ---------------------------------------------------------------------------
+    /**
+     * StdioServerTransport — транспорт на основе stdin/stdout.
+     * MCP-клиент запускает этот процесс и общается с ним через стандартные потоки.
+     * Все логи пишем в stderr чтобы не засорять MCP-протокол в stdout.
+     */
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    // Log to stderr so it doesn't interfere with MCP stdio protocol
     process.stderr.write("OneEntry MCP server running\n");
 }
 main().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneentry/mcp-server",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "MCP server for OneEntry SDK — rules and skills for Claude Code",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -6,176 +6,263 @@ import { fetchContent } from "./content.js";
 import { RULES, SKILLS } from "./registry.js";
 import { CLAUDE_MD_PATH, SERVER_NAME, VERSION } from "./config.js";
 
-// ---------------------------------------------------------------------------
-// Server
-// ---------------------------------------------------------------------------
-
-const server = new McpServer({ name: SERVER_NAME, version: VERSION });
+/**
+ * Точка входа MCP-сервера OneEntry SDK.
+ *
+ * ## Архитектура
+ *
+ * MCP (Model Context Protocol) — протокол, по которому AI-клиент (Claude Code,
+ * Cursor, Windsurf) общается с внешним сервером контекста. Сервер предоставляет
+ * три типа объектов:
+ *
+ * - **Resources** — документы, которые AI может прочитать по URI (`@oneentry://...`).
+ *   Аналог файловой системы: клиент сам решает, когда читать.
+ *
+ * - **Prompts** — готовые шаблоны сообщений (скиллы). AI-клиент подставляет их
+ *   в чат по команде пользователя (`/mcp__oneentry__<name>`).
+ *
+ * - **Tools** — функции, которые AI вызывает автоматически по ситуации.
+ *   Возвращают текст прямо в контекст разговора.
+ *
+ * ## Как загружается CLAUDE.md
+ *
+ * При подключении MCP-сервер отвечает на `initialize`-запрос клиента и
+ * включает в ответ поле `instructions`. Claude Code читает это поле и
+ * автоматически добавляет его в системный контекст сессии — без каких-либо
+ * дополнительных действий от пользователя.
+ *
+ * Поэтому CLAUDE.md загружается **первым делом**, до регистрации всего
+ * остального, и передаётся в конструктор `McpServer` через `{ instructions }`.
+ */
+async function main() {
+  // ---------------------------------------------------------------------------
+  // Загрузка CLAUDE.md и создание сервера
+  // ---------------------------------------------------------------------------
 
-// ---------------------------------------------------------------------------
-// Resources — rules + CLAUDE.md
-// ---------------------------------------------------------------------------
+  /**
+   * Загружаем CLAUDE.md с GitHub до создания сервера — нам нужно передать
+   * содержимое в конструктор как `instructions`.
+   *
+   * `instructions` — стандартное поле MCP InitializeResult. Клиент получает
+   * его в ответ на первый `initialize`-запрос и автоматически включает в
+   * системный промпт сессии. Именно так другие MCP-серверы "работают сразу"
+   * без дополнительной настройки CLAUDE.md в проекте.
+   */
+  const instructions = await fetchContent(CLAUDE_MD_PATH);
+  const server = new McpServer({ name: SERVER_NAME, version: VERSION }, { instructions });
 
-server.registerResource(
-  "OneEntry SDK — Main Instructions (CLAUDE.md)",
-  "oneentry://claude-md",
-  {
-    description:
-      "Full system prompt with OneEntry SDK rules, patterns, anti-hallucination guidelines and module reference",
-    mimeType: "text/markdown",
-  },
-  async (uri) => {
-    const text = await fetchContent(CLAUDE_MD_PATH);
-    return { contents: [{ uri: uri.toString(), mimeType: "text/markdown", text }] };
-  }
-);
+  // ---------------------------------------------------------------------------
+  // Resources — документы для явного чтения по URI
+  // ---------------------------------------------------------------------------
 
-for (const rule of RULES) {
+  /**
+   * Главный ресурс: полный CLAUDE.md как документ.
+   * Доступен в Claude Code по `@oneentry://claude-md`.
+   * Полезен если нужно явно переподгрузить контекст или вставить его в чат.
+   */
   server.registerResource(
-    rule.displayName,
-    `oneentry://rules/${rule.name}`,
-    { description: rule.description, mimeType: "text/markdown" },
+    "OneEntry SDK — Main Instructions (CLAUDE.md)",
+    "oneentry://claude-md",
+    {
+      description:
+        "Full system prompt with OneEntry SDK rules, patterns, anti-hallucination guidelines and module reference",
+      mimeType: "text/markdown",
+    },
     async (uri) => {
-      const text = await fetchContent(rule.path);
+      const text = await fetchContent(CLAUDE_MD_PATH);
       return { contents: [{ uri: uri.toString(), mimeType: "text/markdown", text }] };
     }
   );
-}
 
-// ---------------------------------------------------------------------------
-// Prompts — skills
-// ---------------------------------------------------------------------------
+  /**
+   * Отдельные правила из registry.ts — каждое доступно по своему URI:
+   * `@oneentry://rules/linting`, `@oneentry://rules/tokens`, и т.д.
+   *
+   * Ресурсы удобны когда нужно прочитать только одно конкретное правило,
+   * не загружая весь CLAUDE.md целиком.
+   */
+  for (const rule of RULES) {
+    server.registerResource(
+      rule.displayName,
+      `oneentry://rules/${rule.name}`,
+      { description: rule.description, mimeType: "text/markdown" },
+      async (uri) => {
+        const text = await fetchContent(rule.path);
+        return { contents: [{ uri: uri.toString(), mimeType: "text/markdown", text }] };
+      }
+    );
+  }
 
-// Special prompt: load full context from CLAUDE.md
-server.registerPrompt(
-  "oneentry-context",
-  {
-    description:
-      "Load full OneEntry SDK context — system instructions, rules and anti-hallucination guidelines. Use this at the start of a session.",
-  },
-  async () => {
-    const text = await fetchContent(CLAUDE_MD_PATH);
-    return {
-      description: "OneEntry SDK — full system context loaded",
-      messages: [
-        {
-          role: "user" as const,
-          content: {
-            type: "text" as const,
-            text: `The following are the complete instructions and rules for working with OneEntry SDK. Apply them to all subsequent code generation:\n\n${text}`,
+  // ---------------------------------------------------------------------------
+  // Prompts (скиллы) — шаблоны сообщений для вставки в чат
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Специальный промпт для ручной перезагрузки контекста.
+   * Вызывается командой `/mcp__oneentry__oneentry-context`.
+   *
+   * Возвращает CLAUDE.md завёрнутым в сообщение с ролью `user` — это
+   * стандартный способ подачи контекста через MCP Prompts API.
+   * Клиент вставляет это сообщение в историю чата.
+   */
+  server.registerPrompt(
+    "oneentry-context",
+    {
+      description:
+        "Load full OneEntry SDK context — system instructions, rules and anti-hallucination guidelines. Use this at the start of a session.",
+    },
+    async () => {
+      const text = await fetchContent(CLAUDE_MD_PATH);
+      return {
+        description: "OneEntry SDK — full system context loaded",
+        messages: [
+          {
+            role: "user" as const,
+            content: {
+              type: "text" as const,
+              text: `The following are the complete instructions and rules for working with OneEntry SDK. Apply them to all subsequent code generation:\n\n${text}`,
+            },
           },
-        },
-      ],
-    };
-  }
-);
+        ],
+      };
+    }
+  );
 
-// Skills
-for (const skill of SKILLS) {
-  if (skill.hasArguments) {
-    server.registerPrompt(
-      skill.name,
-      {
-        description: skill.description,
-        argsSchema: {
-          arguments: z
-            .string()
-            .optional()
-            .describe(skill.argumentDescription ?? "Optional arguments"),
+  /**
+   * Регистрируем все скиллы из registry.ts как MCP Prompts.
+   * Каждый скилл — это markdown-инструкция для выполнения конкретной задачи
+   * (создание страницы, формы, корзины и т.д.).
+   *
+   * Скиллы делятся на два типа:
+   * - `hasArguments: true` — принимают аргумент (например, маркер страницы),
+   *   который подставляется вместо плейсхолдера `$ARGUMENTS` в тексте скилла.
+   * - без аргументов — возвращают текст как есть.
+   */
+  for (const skill of SKILLS) {
+    if (skill.hasArguments) {
+      server.registerPrompt(
+        skill.name,
+        {
+          description: skill.description,
+          argsSchema: {
+            arguments: z
+              .string()
+              .optional()
+              .describe(skill.argumentDescription ?? "Optional arguments"),
+          },
         },
-      },
-      async (args) => {
-        let text = await fetchContent(skill.path);
-        // Replace $ARGUMENTS placeholder (used in inspect-api and create-page skills)
-        if (args.arguments) {
-          text = text.replace(/\$ARGUMENTS/g, args.arguments);
+        async (args) => {
+          let text = await fetchContent(skill.path);
+          // Подставляем аргумент вместо плейсхолдера $ARGUMENTS в тексте скилла.
+          // Используется, например, в inspect-api (тип данных) и create-page (маркер страницы).
+          if (args.arguments) {
+            text = text.replace(/\$ARGUMENTS/g, args.arguments);
+          }
+          return {
+            description: skill.description,
+            messages: [{ role: "user" as const, content: { type: "text" as const, text } }],
+          };
         }
-        return {
-          description: skill.description,
-          messages: [{ role: "user" as const, content: { type: "text" as const, text } }],
-        };
-      }
-    );
-  } else {
-    server.registerPrompt(
-      skill.name,
-      { description: skill.description },
-      async () => {
-        const text = await fetchContent(skill.path);
-        return {
-          description: skill.description,
-          messages: [{ role: "user" as const, content: { type: "text" as const, text } }],
-        };
-      }
-    );
+      );
+    } else {
+      server.registerPrompt(
+        skill.name,
+        { description: skill.description },
+        async () => {
+          const text = await fetchContent(skill.path);
+          return {
+            description: skill.description,
+            messages: [{ role: "user" as const, content: { type: "text" as const, text } }],
+          };
+        }
+      );
+    }
   }
-}
 
-// ---------------------------------------------------------------------------
-// Tools
-// ---------------------------------------------------------------------------
+  // ---------------------------------------------------------------------------
+  // Tools — функции, вызываемые AI автоматически по ситуации
+  // ---------------------------------------------------------------------------
 
-server.registerTool(
-  "load-context",
-  {
-    description:
-      "IMPORTANT: Call this tool automatically at the start of EVERY session when working on a project that uses OneEntry CMS or OneEntry SDK. " +
-      "This loads the full OneEntry SDK instructions, rules, and anti-hallucination guidelines into the context. " +
-      "Do not skip this — without it you will make mistakes working with OneEntry API.",
-    inputSchema: {},
-  },
-  async () => {
-    const text = await fetchContent(CLAUDE_MD_PATH);
-    return { content: [{ type: "text" as const, text }] };
-  }
-);
-
-server.registerTool(
-  "get-rule",
-  {
-    description: "Fetch the content of a specific OneEntry SDK rule by name",
-    inputSchema: { name: z.string().describe(`Rule name. Available: ${RULES.map((r) => r.name).join(", ")}`) },
-  },
-  async ({ name }) => {
-    const rule = RULES.find((r) => r.name === name);
-    if (!rule) {
-      return { content: [{ type: "text" as const, text: `Unknown rule: ${name}. Available: ${RULES.map((r) => r.name).join(", ")}` }], isError: true };
+  /**
+   * Инструмент для ручной перезагрузки CLAUDE.md в контекст разговора.
+   * В отличие от `instructions` (которые загружаются один раз при коннекте),
+   * этот tool позволяет получить свежую версию документа прямо в чат —
+   * например, если кэш устарел или контекст был сброшен.
+   */
+  server.registerTool(
+    "load-context",
+    {
+      description:
+        "Reload the full OneEntry SDK instructions, rules, and anti-hallucination guidelines into the context. " +
+        "Call this if you need a fresh copy of the SDK documentation.",
+      inputSchema: {},
+    },
+    async () => {
+      const text = await fetchContent(CLAUDE_MD_PATH);
+      return { content: [{ type: "text" as const, text }] };
     }
-    const text = await fetchContent(rule.path);
-    return { content: [{ type: "text" as const, text }] };
-  }
-);
+  );
 
-server.registerTool(
-  "get-skill",
-  {
-    description: "Fetch the content of a specific OneEntry skill/slash-command by name",
-    inputSchema: {
-      name: z.string().describe(`Skill name. Available: ${SKILLS.map((s) => s.name).join(", ")}`),
-      arguments: z.string().optional().describe("Optional arguments passed to the skill (replaces $ARGUMENTS placeholder)"),
+  /**
+   * Инструмент для загрузки отдельного правила по имени.
+   * AI может вызвать его когда нужно уточнить конкретный аспект SDK
+   * (например, правила работы с токенами или формами) без загрузки всего CLAUDE.md.
+   */
+  server.registerTool(
+    "get-rule",
+    {
+      description: "Fetch the content of a specific OneEntry SDK rule by name",
+      inputSchema: { name: z.string().describe(`Rule name. Available: ${RULES.map((r) => r.name).join(", ")}`) },
     },
-  },
-  async (args) => {
-    const skill = SKILLS.find((s) => s.name === args.name);
-    if (!skill) {
-      return { content: [{ type: "text" as const, text: `Unknown skill: ${args.name}. Available: ${SKILLS.map((s) => s.name).join(", ")}` }], isError: true };
+    async ({ name }) => {
+      const rule = RULES.find((r) => r.name === name);
+      if (!rule) {
+        return { content: [{ type: "text" as const, text: `Unknown rule: ${name}. Available: ${RULES.map((r) => r.name).join(", ")}` }], isError: true };
+      }
+      const text = await fetchContent(rule.path);
+      return { content: [{ type: "text" as const, text }] };
     }
-    let text = await fetchContent(skill.path);
-    if (args.arguments) {
-      text = text.replace(/\$ARGUMENTS/g, args.arguments);
+  );
+
+  /**
+   * Инструмент для загрузки конкретного скилла по имени.
+   * Аналог вызова промпта, но через tool API — удобно когда AI сам
+   * определяет что нужен тот или иной скилл в процессе работы.
+   * Поддерживает аргументы: подставляет их вместо `$ARGUMENTS` в тексте.
+   */
+  server.registerTool(
+    "get-skill",
+    {
+      description: "Fetch the content of a specific OneEntry skill/slash-command by name",
+      inputSchema: {
+        name: z.string().describe(`Skill name. Available: ${SKILLS.map((s) => s.name).join(", ")}`),
+        arguments: z.string().optional().describe("Optional arguments passed to the skill (replaces $ARGUMENTS placeholder)"),
+      },
+    },
+    async (args) => {
+      const skill = SKILLS.find((s) => s.name === args.name);
+      if (!skill) {
+        return { content: [{ type: "text" as const, text: `Unknown skill: ${args.name}. Available: ${SKILLS.map((s) => s.name).join(", ")}` }], isError: true };
+      }
+      let text = await fetchContent(skill.path);
+      if (args.arguments) {
+        text = text.replace(/\$ARGUMENTS/g, args.arguments);
+      }
+      return { content: [{ type: "text" as const, text }] };
     }
-    return { content: [{ type: "text" as const, text }] };
-  }
-);
+  );
 
-// ---------------------------------------------------------------------------
-// Start
-// ---------------------------------------------------------------------------
+  // ---------------------------------------------------------------------------
+  // Запуск транспорта
+  // ---------------------------------------------------------------------------
 
-async function main() {
+  /**
+   * StdioServerTransport — транспорт на основе stdin/stdout.
+   * MCP-клиент запускает этот процесс и общается с ним через стандартные потоки.
+   * Все логи пишем в stderr чтобы не засорять MCP-протокол в stdout.
+   */
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  // Log to stderr so it doesn't interfere with MCP stdio protocol
   process.stderr.write("OneEntry MCP server running\n");
 }