@fractalizer/mcp-cli 0.3.18 → 1.0.1

package/dist/connectors/claude-code/claude-code.connector.d.ts

@@ -1,41 +1,191 @@
 /**
- * Коннектор для Claude Code
+ * Коннектор для Claude Code CLI.
+ *
+ * Использует команды `claude mcp add/remove/list/get` вместо записи в файл.
+ *
+ * Управление scope (`local` / `user` / `project`):
+ *   - claude mcp использует разные хранилища для разных scope: local —
+ *     `~/.claude.json` → `projects["<cwd>"].mcpServers` (приватно к проекту),
+ *     user — корень `~/.claude.json` (доступен везде), project — `.mcp.json`
+ *     в корне проекта (видим команде через git).
+ *   - `claude mcp add` без `--scope` дефолтит в `local` и НЕ блокирует, если
+ *     запись уже есть в другом scope (молча создаёт дубликат).
+ *   - `claude mcp remove` без `--scope` сам ищет запись, но падает с
+ *     "exists in multiple scopes", если запись в нескольких.
+ *
+ * Поведение этого коннектора (фикс баг-а с дубликатами):
+ *   - connect → принудительно `--scope user` (стабильный default; доступен
+ *     из любой директории). Если запись уже существует (в любом scope) —
+ *     `connect` бросает осмысленную ошибку с подсказкой про `disconnect`.
+ *   - disconnect → итеративно `claude mcp get` + `claude mcp remove -s <scope>`
+ *     пока запись существует (умеет вычищать дубликаты, появившиеся ранее).
+ *   - getStatus → читает scope из `claude mcp get` и кладёт его в `details.scope`.
+ *
+ * Discovery (на момент написания, Claude Code CLI 2.x):
+ *   - `claude mcp list` НЕ поддерживает `--json` (только `-h/--help`).
+ *     Вывод парсится как текст по строкам формата:
+ *       `<server-name>: <command-summary> - <status-icon> <status-text>`
+ *     где status-icon — один из `✓ Connected`, `✗ Failed to connect`,
+ *     `! Needs authentication`. Имя сервера может содержать пробелы.
+ *   - `claude mcp get <name>` даёт структурированный многострочный вывод:
+ *       ```
+ *       <name>:
+ *         Scope: Local config (private to you in this project)
+ *         Status: ...
+ *         Type: stdio
+ *         Command: node
+ *         Args: /abs/script.cjs [...]
+ *         Environment:
+ *           KEY1=value1
+ *           KEY2=value2
+ *       ```
+ *     Каждая переменная окружения — отдельная строка с отступом.
+ *   - `claude mcp add` НЕ поддерживает флаги `--cwd` или `--disabled`.
+ *     При наличии в spec этих полей мы пишем предупреждение в Logger и
+ *     игнорируем их (соответствующие поля недоступны в claude-code).
+ *
+ * Ограничения парсинга:
+ *   - Args парсится по whitespace. Если путь в args содержит пробелы,
+ *     парсер их некорректно разобьёт. Это ограничение `claude mcp get`,
+ *     который выводит args одной сырой строкой без кавычек.
  */
 import { BaseConnector } from '../base/base-connector.js';
-import type { BaseMCPServerConfig, MCPClientInfo, ConnectionStatus } from '../../types.js';
+import type { ConnectionStatus, MCPClientInfo } from '../../types/client.types.js';
+import type { ServerLaunchSpec } from '../../types/launch.types.js';
 /**
- * Коннектор для Claude Code CLI
- * Использует команды `claude mcp add/remove/list` для управления серверами
- *
- * @template TConfig - Тип конфигурации MCP сервера
+ * Возможные scope записи в `claude mcp`.
  */
-export declare class ClaudeCodeConnector<TConfig extends BaseMCPServerConfig = BaseMCPServerConfig> extends BaseConnector<TConfig> {
+export type ClaudeCodeScope = 'user' | 'project' | 'local';
+/**
+ * Коннектор для Claude Code CLI.
+ */
+export declare class ClaudeCodeConnector extends BaseConnector {
     private readonly serverName;
-    private readonly entryPoint;
-    /**
-     * @param serverName - Имя MCP сервера для записи в конфигурацию
-     * @param entryPoint - Относительный путь к точке входа сервера от projectPath
-     */
-    constructor(serverName: string, entryPoint: string);
     /**
-     * Получить информацию о клиенте
+     * @param serverName - Имя MCP сервера для управления через `claude mcp`
      */
+    constructor(serverName: string);
     getClientInfo(): MCPClientInfo;
-    /**
-     * Проверить, установлен ли клиент
-     */
     isInstalled(): Promise<boolean>;
     /**
-     * Получить статус подключения
+     * Получить статус подключения через парсинг `claude mcp list` + обогащение
+     * scope из `claude mcp get`.
+     *
+     * Состояния:
+     *  - `✓ Connected` → connected: true
+     *  - `✗ Failed to connect` → connected: false, error: 'Failed to connect'
+     *  - `! Needs authentication` → connected: false, error: 'Needs authentication'
+     *  - неизвестное → connected: false, error: `Unknown state: <raw>` (для диагностики)
+     *  - сервер отсутствует в выводе → connected: false
+     *  - таймаут → connected: false, error: 'Timeout: ...'
      */
     getStatus(): Promise<ConnectionStatus>;
     /**
-     * Подключить MCP сервер
+     * Подключить MCP сервер через `claude mcp add --scope user`.
+     *
+     * Формирует команду вида:
+     *   claude mcp add --scope user --transport stdio <name> [--env K=V ...] -- <command> [<args>...]
+     *
+     * Использование `--scope user` (вместо CLI default `local`) обеспечивает
+     * доступность сервера из любой директории и единое стабильное место хранения.
+     * Это сознательное отклонение от дефолта `claude mcp`.
+     *
+     * Перед `add` проверяет существование записи в любом scope через
+     * {@link getCurrentScope}. Если запись уже есть — бросает Error с подсказкой
+     * пользователю запустить `disconnect`, чтобы избежать дубликатов между scope
+     * (`claude mcp add` без проверки молча создаёт дубли).
+     *
+     * Поля {@link ServerLaunchSpec.cwd} и {@link ServerLaunchSpec.disabled}
+     * НЕ поддерживаются claude-code CLI — при их наличии пишется warning и они
+     * игнорируются.
      */
-    connect(serverConfig: TConfig): Promise<void>;
+    connect(spec: ServerLaunchSpec): Promise<void>;
     /**
-     * Отключить MCP сервер
+     * Отключить MCP сервер.
+     *
+     * Алгоритм: цикл `get` → `remove --scope <scope>` пока запись существует.
+     * Это позволяет корректно вычистить случай, когда запись присутствует в
+     * нескольких scope (исторический баг ранних версий коннектора, где `add`
+     * мог создать дубликаты между local и user).
+     *
+     * Если запись не найдена ни в одном scope — бросает Error.
      */
     disconnect(): Promise<void>;
+    /**
+     * Получить spec через `claude mcp get <name>`.
+     *
+     * Парсит структурированный вывод (multi-line):
+     *   Type: stdio
+     *   Command: node
+     *   Args: /abs/path.cjs
+     *   Environment:
+     *     KEY=value
+     *     OTHER=...
+     *
+     * @returns spec, если сервер есть и stdio; `null` если не найден, http/sse или
+     *          парсинг не удался.
+     */
+    getLaunchSpec(): Promise<ServerLaunchSpec | null>;
+    /**
+     * Выполнить `claude mcp get <name>` с таймаутом, проглотив ошибку.
+     *
+     * `claude mcp get` возвращает non-zero, когда сервер не существует ни в одном
+     * scope. В этом случае возвращаем `null` (а не пробрасываем) — вызывающий код
+     * различает «нет записи» (null) и «есть запись» (любая строка вывода).
+     */
+    private runGet;
+    /**
+     * Определить scope текущей записи через `claude mcp get`.
+     *
+     * Если запись существует в нескольких scope (исторический баг),
+     * `claude mcp get` показывает один — приоритетный (local > project > user).
+     * Этого достаточно для итеративного `disconnect`: одной итерации хватает,
+     * чтобы убрать запись из показанного scope, а следующая увидит следующий.
+     *
+     * @returns scope или `null`, если запись отсутствует / парсинг неудачен.
+     */
+    private getCurrentScope;
+    /**
+     * Извлечь scope из вывода `claude mcp get`.
+     *
+     * Формат строки: `  Scope: Local config (private to you in this project)`.
+     * Метки в выводе CLI 2.x:
+     *  - `Local config ...`   → `local`
+     *  - `User config ...`    → `user`
+     *  - `Project config ...` → `project`
+     */
+    private parseScopeFromGet;
+    /**
+     * Парсинг строк `claude mcp list`. Формат строки:
+     *   `<name>: <command-tail> - <status>`
+     * где `<name>` может содержать пробелы (например, `claude.ai Gmail`).
+     *
+     * Чтобы корректно распознать строку именно нашего сервера, проверяем префикс
+     * `<serverName>: ` (с обязательным пробелом после двоеточия — иначе
+     * `tracker: ...` поймает `tracker-dev: ...`).
+     */
+    private parseStatusFromList;
+    /**
+     * Парсинг вывода `claude mcp get <name>`. Возвращает `null`, если сервер не
+     * stdio или критичные поля не распознаны.
+     *
+     * Особенности формата:
+     *  - `Environment:` сам по себе обычно без значения, далее следуют строки
+     *    с отступом вида `  KEY=value` (по одной паре на строку).
+     *  - `Args:` — одна строка, разделители — пробелы. Пути с пробелами в
+     *    результате парсятся некорректно (ограничение `claude mcp get`).
+     */
+    private parseLaunchSpecFromGet;
+    /**
+     * Парсинг секции `Environment:` из вывода `claude mcp get`.
+     *
+     * Поддерживает 2 формата:
+     *  1. Многострочный (CLI 2.x): `Environment:` + последующие строки с отступом
+     *     вида `  KEY=value` (одна пара на строку, продолжается пока есть отступ).
+     *  2. Однострочный (legacy/fallback): `Environment: KEY=v1, OTHER=v2`.
+     *     Разделители — `,` между парами; разделитель ключ/значение — `=`.
+     *     Этот формат не выдерживает запятых в values; ограничение задокументировано.
+     */
+    private parseEnvSection;
 }
 //# sourceMappingURL=claude-code.connector.d.ts.map

package/dist/connectors/claude-code/claude-code.connector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-code.connector.d.ts","sourceRoot":"","sources":["../../../src/connectors/claude-code/claude-code.connector.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAU3F;;;;;GAKG;AACH,qBAAa,mBAAmB,CAC9B,OAAO,SAAS,mBAAmB,GAAG,mBAAmB,CACzD,SAAQ,aAAa,CAAC,OAAO,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC;;;OAGG;gBACS,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;IAMlD;;OAEG;IACH,aAAa,IAAI,aAAa;IAW9B;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAI/B;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAuBtC;;OAEG;IACG,OAAO,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBnD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}
+{"version":3,"file":"claude-code.connector.d.ts","sourceRoot":"","sources":["../../../src/connectors/claude-code/claude-code.connector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAG1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACnF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AASpE;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAkB3D;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,aAAa;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC;;OAEG;gBACS,UAAU,EAAE,MAAM;IAK9B,aAAa,IAAI,aAAa;IAW9B,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAI/B;;;;;;;;;;;OAWG;IACG,SAAS,IAAI,OAAO,CAAC,gBAAgB,CAAC;IA0B5C;;;;;;;;;;;;;;;;;;OAkBG;IACG,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuCpD;;;;;;;;;OASG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA2BjC;;;;;;;;;;;;;OAaG;IACH,aAAa,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAQjD;;;;;;OAMG;IACH,OAAO,CAAC,MAAM;IAUd;;;;;;;;;OASG;YACW,eAAe;IAM7B;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;IA8C3B;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IA2B9B;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;CAsCxB"}