gitflic-cli-mcp 0.1.0 → 0.2.0

package/README.md

@@ -64,30 +64,118 @@ claude mcp add gitflic --env GITFLIC_TOKEN=xxxxxxxx -- npx -y gitflic-cli-mcp
 
 Та же структура. Перезапустите хост. (Из исходников: `"command": "node", "args": ["/absolute/path/to/gitflic-cli/mcp-server/server.mjs"]`.)
 
-## Тулзы (77) — основные
-
-Ниже — выборка; полный список из 77 тулзов хост получает по `tools/list`.
-
-| Тулз | Маппится на |
-|---|---|
-| `gitflic_auth` | `gitflic auth` |
-| `gitflic_project_resolve` | `gitflic project get` |
-| `gitflic_mr_list` / `view` / `diff` | `gitflic mr list/view/diff` |
-| `gitflic_mr_create` | `gitflic mr create` (авто from→to) |
-| `gitflic_mr_approve` / `merge` / `close` | `gitflic mr approve/merge/close` |
-| `gitflic_mr_comment` (общий + инлайн-якорный) | `gitflic mr comment` |
-| `gitflic_mr_discuss_list` / `reply` / `resolve` | `gitflic mr discuss …` |
-| `gitflic_issue_list` / `view` / `create` / `close` / `comment` | `gitflic issue …` |
-| `gitflic_branch_list` / `create` / `delete` | `gitflic branch …` |
-| `gitflic_tag_list` / `create` | `gitflic tag …` |
-| `gitflic_release_list` / `create` | `gitflic release …` |
-| `gitflic_commit_list` | `gitflic commit list` |
-| `gitflic_user_me` / `gitflic_user_search` | `gitflic user …` |
-| `gitflic_project_list_my` | `gitflic project list --scope my` |
-| `gitflic_webhook_list` | `gitflic webhook list` |
-| `gitflic_branch_protection_list` | `gitflic branch protection list` |
-
-Эта таблица — лишь самые ходовые тулзы. Всего их 77 (каждая команда CLI имеет свой тул); что не попало в таблицу — всё равно доступно как MCP-тул или через `gitflic …` напрямую.
+## Ограничение набора тулзов (экономия контекста)
+
+Все 77 тулзов уходят хосту по `tools/list` ещё до первого вызова — это ~6K токенов «налога» на контекст модели. Если агенту нужны не все, набор можно сузить через **env-переменные** — прописываются в том же `env`-блоке конфига, где `GITFLIC_TOKEN` (своего конфиг-файла у сервера нет, он читает `process.env` при старте).
+
+| Переменная | Значение | Что делает |
+|---|---|---|
+| `GITFLIC_MCP_GROUPS` | список групп через запятую/пробел | оставить только тулзы указанных групп |
+| `GITFLIC_MCP_READONLY` | `1` / `true` / `yes` / `on` | оставить только read-only тулзы (без мутаций) |
+| `GITFLIC_MCP_TOOLS` | список имён тулзов | явный allowlist (имеет приоритет над `GROUPS`) |
+| `GITFLIC_MCP_EXCLUDE` | список имён тулзов | убрать конкретные тулзы (применяется последним) |
+
+Все — опциональные. Без них регистрируются все 77 (как и раньше). Неизвестные группы/имена не валят сервер — он пишет `WARN` в stderr и игнорирует их.
+
+**Порядок применения (precedence):**
+
+1. Базовый набор: `GITFLIC_MCP_TOOLS`, если задан; иначе `GITFLIC_MCP_GROUPS`, если задан; иначе — все тулзы.
+2. `GITFLIC_MCP_READONLY` — пересечение с read-only (накладывается поверх **в т.ч. на `GITFLIC_MCP_TOOLS`** — write-тул, явно указанный в allowlist, всё равно будет отсеян; так read-only режим гарантированно не пропускает мутации).
+3. `GITFLIC_MCP_EXCLUDE` — вычитается в самом конце (всегда побеждает).
+
+Значения списков — через запятую или пробел; регистр не важен ни для групп, ни для имён тулзов (имена всегда в нижнем регистре).
+
+**Допустимые значения `GITFLIC_MCP_GROUPS`** (группа = первый сегмент имени после `gitflic_`):
+
+| Группа | Тулзов | Read / Write |
+|---|---|---|
+| `auth` | 8 | 3 read / 5 write |
+| `blob` | 3 | 3 read / 0 write |
+| `branch` | 10 | 5 read / 5 write |
+| `commit` | 4 | 4 read / 0 write |
+| `issue` | 12 | 4 read / 8 write |
+| `mr` | 15 | 5 read / 10 write |
+| `project` | 7 | 4 read / 3 write |
+| `release` | 6 | 3 read / 3 write |
+| `tag` | 3 | 2 read / 1 write |
+| `user` | 5 | 5 read / 0 write |
+| `webhook` | 4 | 2 read / 2 write |
+
+> ⚠️ Группа `auth` включает **мутирующие** тулзы (`gitflic_auth_login`, `_logout`, `_switch`, `_bind`, `_unbind`) — они меняют локальный keychain/конфиг, а не сервер, но это всё равно запись. Если нужны только проверки личности — добавь `GITFLIC_MCP_READONLY=1` (останутся `gitflic_auth`, `_list`, `_bindings`) или используй `GITFLIC_MCP_TOOLS` с точным набором.
+
+**Примеры:**
+
+```bash
+# Только MR и issue (~27 тулзов вместо 77)
+claude mcp add gitflic --env GITFLIC_TOKEN=xxxx \
+  --env GITFLIC_MCP_GROUPS=mr,issue -- npx -y gitflic-cli-mcp
+
+# Read-only агент для код-ревью (только тулзы без мутаций)
+GITFLIC_MCP_READONLY=1 npx -y gitflic-cli-mcp
+
+# Точный набор из четырёх тулзов
+GITFLIC_MCP_TOOLS="gitflic_mr_list,gitflic_mr_view,gitflic_mr_diff,gitflic_mr_create" \
+  npx -y gitflic-cli-mcp
+```
+
+В JSON-конфиге это тот же `env`-блок:
+
+```json
+{
+  "mcpServers": {
+    "gitflic": {
+      "command": "npx",
+      "args": ["-y", "gitflic-cli-mcp"],
+      "env": {
+        "GITFLIC_TOKEN": "xxxx",
+        "GITFLIC_MCP_GROUPS": "mr,issue",
+        "GITFLIC_MCP_READONLY": "1"
+      }
+    }
+  }
+}
+```
+
+> Можно поднять один и тот же сервер дважды под разными именами — напр. `gitflic` (полный) и `gitflic-ro` (`GITFLIC_MCP_READONLY=1`) — и держать оба подключёнными. Либо класть конфиг в проектный `.mcp.json` / `.cursor/mcp.json`, чтобы в каждом репозитории грузились свои группы.
+
+## Все 77 тулзов
+
+Полный список по группам. **R** = read-only (`readOnlyHint: true`, не меняет состояние — попадает в `GITFLIC_MCP_READONLY=1`); **W** = write/мутация.
+
+### `auth` (8)
+`R` `gitflic_auth` · `W` `gitflic_auth_login` · `W` `gitflic_auth_logout` · `R` `gitflic_auth_list` · `W` `gitflic_auth_switch` · `W` `gitflic_auth_bind` · `W` `gitflic_auth_unbind` · `R` `gitflic_auth_bindings`
+
+### `blob` (3)
+`R` `gitflic_blob_get` · `R` `gitflic_blob_files` · `R` `gitflic_blob_archive`
+
+### `branch` (10)
+`R` `gitflic_branch_list` · `W` `gitflic_branch_create` · `W` `gitflic_branch_delete` · `R` `gitflic_branch_get` · `R` `gitflic_branch_default` · `R` `gitflic_branch_protection_list` · `R` `gitflic_branch_protection_get` · `W` `gitflic_branch_protection_create` · `W` `gitflic_branch_protection_edit` · `W` `gitflic_branch_protection_delete`
+
+### `commit` (4)
+`R` `gitflic_commit_list` · `R` `gitflic_commit_get` · `R` `gitflic_commit_files` · `R` `gitflic_commit_compare`
+
+### `issue` (12)
+`R` `gitflic_issue_list` · `R` `gitflic_issue_view` · `W` `gitflic_issue_create` · `W` `gitflic_issue_close` · `W` `gitflic_issue_comment` · `W` `gitflic_issue_edit` · `W` `gitflic_issue_reopen` · `W` `gitflic_issue_delete` · `R` `gitflic_issue_comments_list` · `W` `gitflic_issue_comments_edit` · `W` `gitflic_issue_comments_delete` · `R` `gitflic_issue_relations_list`
+
+### `mr` (15)
+`R` `gitflic_mr_list` · `R` `gitflic_mr_view` · `R` `gitflic_mr_diff` · `R` `gitflic_mr_by_commit` · `R` `gitflic_mr_discuss_list` · `W` `gitflic_mr_create` · `W` `gitflic_mr_approve` · `W` `gitflic_mr_merge` · `W` `gitflic_mr_close` · `W` `gitflic_mr_cancel` · `W` `gitflic_mr_edit` · `W` `gitflic_mr_comment` · `W` `gitflic_mr_discuss_reply` · `W` `gitflic_mr_discuss_resolve` · `W` `gitflic_mr_discuss_delete`
+
+### `project` (7)
+`R` `gitflic_project_resolve` · `R` `gitflic_project_get` · `R` `gitflic_project_list_my` · `R` `gitflic_project_member_list` · `W` `gitflic_project_create` · `W` `gitflic_project_edit` · `W` `gitflic_project_member_invite`
+
+### `release` (6)
+`R` `gitflic_release_list` · `R` `gitflic_release_get` · `R` `gitflic_release_latest` · `W` `gitflic_release_create` · `W` `gitflic_release_edit` · `W` `gitflic_release_delete`
+
+### `tag` (3)
+`R` `gitflic_tag_list` · `R` `gitflic_tag_get` · `W` `gitflic_tag_create`
+
+### `user` (5)
+`R` `gitflic_user_me` · `R` `gitflic_user_search` · `R` `gitflic_user_get` · `R` `gitflic_user_projects` · `R` `gitflic_user_followers`
+
+### `webhook` (4)
+`R` `gitflic_webhook_list` · `R` `gitflic_webhook_get` · `W` `gitflic_webhook_create` · `W` `gitflic_webhook_delete`
+
+Итого: **40 read / 37 write**. Каждый тул маппится 1-в-1 на подкоманду CLI (`gitflic …`).
 
 ## Как это работает
 

package/filter.mjs

@@ -0,0 +1,140 @@
+// Tool selection for the MCP server.
+//
+// Lets users scope WHICH of the tools get registered, to keep the model's
+// context small (the full catalog costs ~6K tokens before the first call).
+// All config is via environment variables — see README "Ограничение набора
+// тулзов (экономия контекста)".
+//
+// Env vars (all optional; default = register everything):
+//   GITFLIC_MCP_GROUPS    comma/space list of groups, e.g. "mr,issue"
+//   GITFLIC_MCP_READONLY  "1"/"true"/"yes"/"on" → only read-only tools
+//   GITFLIC_MCP_TOOLS     comma/space list of exact tool names (allowlist)
+//   GITFLIC_MCP_EXCLUDE   comma/space list of exact tool names to drop
+//
+// Pure + testable: selectTools() takes an explicit env object, so tests never
+// touch process.env.
+
+// Derive the group of a tool from its name: gitflic_<group>_<action>.
+// e.g. gitflic_mr_create → "mr", gitflic_branch_protection_list → "branch".
+export function toolGroup(name) {
+  return name.replace(/^gitflic_/, "").split("_")[0];
+}
+
+// All distinct groups present in the catalog, sorted.
+export function groupsOf(tools) {
+  return [...new Set(tools.map((t) => toolGroup(t.name)))].sort();
+}
+
+// A tool is read-only iff its annotations say so.
+export function isReadOnly(tool) {
+  return Boolean(tool.annotations && tool.annotations.readOnlyHint === true);
+}
+
+// Parse a comma/space-separated env value into a clean array.
+function parseList(value, { lower = false } = {}) {
+  if (!value) return [];
+  return value
+    .split(/[,\s]+/)
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((s) => (lower ? s.toLowerCase() : s));
+}
+
+const TRUTHY = ["1", "true", "yes", "on"];
+const FALSEY = ["0", "false", "no", "off", ""];
+
+// Truthy env flag: "1", "true", "yes", "on" (case-insensitive). Anything
+// else (including "0", "false", "", undefined) is falsey.
+function isTruthy(value) {
+  if (value == null) return false;
+  return TRUTHY.includes(String(value).trim().toLowerCase());
+}
+
+// Select which tools to register based on env config.
+//
+// Precedence:
+//   1. Base set:
+//        - GITFLIC_MCP_TOOLS (explicit allowlist), if set; else
+//        - GITFLIC_MCP_GROUPS (by group), if set; else
+//        - all tools.
+//   2. GITFLIC_MCP_READONLY truthy → keep only read-only tools (overlay).
+//   3. GITFLIC_MCP_EXCLUDE → drop named tools (applied last, always wins).
+//
+// Returns { selected, warnings } — warnings are human-readable strings the
+// caller prints to stderr. Unknown names/groups are warned about, not fatal.
+export function selectTools(tools, env = {}) {
+  const warnings = [];
+  const allGroups = groupsOf(tools);
+  const byName = new Map(tools.map((t) => [t.name, t]));
+
+  // Tool names are all lowercase, so match TOOLS/EXCLUDE case-insensitively
+  // too (consistent with GROUPS). Otherwise a mis-cased EXCLUDE of a write
+  // tool would silently keep it registered.
+  const wantTools = parseList(env.GITFLIC_MCP_TOOLS, { lower: true });
+  const wantGroups = parseList(env.GITFLIC_MCP_GROUPS, { lower: true });
+  const exclude = parseList(env.GITFLIC_MCP_EXCLUDE, { lower: true });
+
+  const readonlyRaw = env.GITFLIC_MCP_READONLY;
+  const readonly = isTruthy(readonlyRaw);
+  if (readonlyRaw != null) {
+    const v = String(readonlyRaw).trim().toLowerCase();
+    if (v !== "" && !TRUTHY.includes(v) && !FALSEY.includes(v)) {
+      warnings.push(
+        `GITFLIC_MCP_READONLY="${readonlyRaw}" is not a recognized boolean (use 1/true/yes/on); treating as off.`,
+      );
+    }
+  }
+
+  let base;
+  if (wantTools.length) {
+    if (wantGroups.length) {
+      warnings.push(
+        "GITFLIC_MCP_TOOLS is set, so GITFLIC_MCP_GROUPS is ignored (explicit tool list wins).",
+      );
+    }
+    for (const n of wantTools) {
+      if (!byName.has(n)) {
+        warnings.push(`GITFLIC_MCP_TOOLS: unknown tool "${n}" (ignored).`);
+      }
+    }
+    base = tools.filter((t) => wantTools.includes(t.name));
+  } else if (wantGroups.length) {
+    for (const g of wantGroups) {
+      if (!allGroups.includes(g)) {
+        warnings.push(
+          `GITFLIC_MCP_GROUPS: unknown group "${g}" (ignored). Valid groups: ${allGroups.join(", ")}.`,
+        );
+      }
+    }
+    base = tools.filter((t) => wantGroups.includes(toolGroup(t.name)));
+  } else {
+    base = tools.slice();
+  }
+
+  if (readonly) {
+    const before = base.length;
+    base = base.filter(isReadOnly);
+    if (before > 0 && base.length === 0) {
+      warnings.push(
+        "GITFLIC_MCP_READONLY removed every selected tool (the selection contained only write tools).",
+      );
+    }
+  }
+
+  if (exclude.length) {
+    for (const n of exclude) {
+      if (!byName.has(n)) {
+        warnings.push(`GITFLIC_MCP_EXCLUDE: unknown tool "${n}" (ignored).`);
+      }
+    }
+    base = base.filter((t) => !exclude.includes(t.name));
+  }
+
+  if (base.length === 0) {
+    warnings.push(
+      "Tool filter matched 0 tools — the server will start with no tools registered. Check your GITFLIC_MCP_* settings.",
+    );
+  }
+
+  return { selected: base, warnings };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitflic-cli-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server wrapping the gitflic CLI — exposes the GitFlic REST API as typed tools for AI agents (Claude Code, Cursor, etc.)",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "server.mjs",
     "runner.mjs",
     "tools.mjs",
+    "filter.mjs",
     "project-resolver.mjs",
     "README.md"
   ],

package/server.mjs

@@ -21,6 +21,7 @@ import { z } from "zod";
 
 import { runGitflic, runGitflicJson, GitflicError } from "./runner.mjs";
 import { TOOLS } from "./tools.mjs";
+import { selectTools } from "./filter.mjs";
 import { resolveProjectArg } from "./project-resolver.mjs";
 
 const server = new McpServer(
@@ -66,8 +67,15 @@ function jsonSchemaToZod(schema) {
   return z.object(props);
 }
 
-// Register each tool from TOOLS.
-for (const tool of TOOLS) {
+// Optionally scope the tool set via env (GITFLIC_MCP_GROUPS / _READONLY /
+// _TOOLS / _EXCLUDE) to keep the model's context small. Default: all tools.
+const { selected, warnings } = selectTools(TOOLS, process.env);
+for (const w of warnings) {
+  process.stderr.write(`[gitflic-mcp] WARN: ${w}\n`);
+}
+
+// Register each selected tool.
+for (const tool of selected) {
   const zodInput = jsonSchemaToZod(tool.inputSchema);
   // Per MCP 2025-06-18 spec, server.tool() in @modelcontextprotocol/sdk@1.x
   // takes annotations as the 5th positional arg. Clients like Claude Code
@@ -124,5 +132,5 @@ await server.connect(transport);
 
 // Announce to stderr (stdout is reserved for JSON-RPC).
 process.stderr.write(
-  `[gitflic-mcp] started; registered ${TOOLS.length} tools. GITFLIC_TOKEN=${process.env.GITFLIC_TOKEN ? "set" : "MISSING"}\n`,
+  `[gitflic-mcp] started; registered ${selected.length}/${TOOLS.length} tools. GITFLIC_TOKEN=${process.env.GITFLIC_TOKEN ? "set" : "MISSING"}\n`,
 );

package/tools.mjs

@@ -420,8 +420,8 @@ export const TOOLS = [
     handler: (a) => ["mr", "discuss", "resolve", a.id, a.discussionUuid, "--project", a.project, "--format", "json"],
     annotations: {
       title: "Mr Discuss Resolve",
-      readOnlyHint: true,
-      destructiveHint: false,
+      readOnlyHint: false,
+      destructiveHint: true,
       idempotentHint: true,
       openWorldHint: true,
     },
@@ -751,8 +751,8 @@ export const TOOLS = [
     handler: () => ["project", "list", "--scope", "my"],
     annotations: {
       title: "Project List My",
-      readOnlyHint: false,
-      destructiveHint: true,
+      readOnlyHint: true,
+      destructiveHint: false,
       idempotentHint: false,
       openWorldHint: true,
     },
@@ -859,8 +859,8 @@ export const TOOLS = [
     },
     annotations: {
       title: "Mr By Commit",
-      readOnlyHint: false,
-      destructiveHint: true,
+      readOnlyHint: true,
+      destructiveHint: false,
       idempotentHint: false,
       openWorldHint: true,
     },