gitflic-cli-mcp 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # gitflic-cli MCP-сервер
 
-[Model Context Protocol](https://modelcontextprotocol.io/) сервер, оборачивающий CLI `gitflic` и отдающий **77 типизированных тулзов** поверх команд GitFlic REST для AI-агентов (Claude Code, Cursor и т.п.).
+[Model Context Protocol](https://modelcontextprotocol.io/) сервер, оборачивающий CLI `gitflic` и отдающий **76 типизированных тулзов** поверх команд GitFlic REST для AI-агентов (Claude Code, Cursor и т.п.).
 
 ## Что внутри
 
@@ -66,7 +66,7 @@ claude mcp add gitflic --env GITFLIC_TOKEN=xxxxxxxx -- npx -y gitflic-cli-mcp
 
 ## Ограничение набора тулзов (экономия контекста)
 
-Все 77 тулзов уходят хосту по `tools/list` ещё до первого вызова — это ~6K токенов «налога» на контекст модели. Если агенту нужны не все, набор можно сузить через **env-переменные** — прописываются в том же `env`-блоке конфига, где `GITFLIC_TOKEN` (своего конфиг-файла у сервера нет, он читает `process.env` при старте).
+Все 76 тулзов уходят хосту по `tools/list` ещё до первого вызова — это ~6K токенов «налога» на контекст модели. Если агенту нужны не все, набор можно сузить через **env-переменные** — прописываются в том же `env`-блоке конфига, где `GITFLIC_TOKEN` (своего конфиг-файла у сервера нет, он читает `process.env` при старте).
 
 | Переменная | Значение | Что делает |
 |---|---|---|
@@ -76,7 +76,7 @@ claude mcp add gitflic --env GITFLIC_TOKEN=xxxxxxxx -- npx -y gitflic-cli-mcp
 | `GITFLIC_MCP_TOOLS` | список имён тулзов | явный allowlist (имеет приоритет над `GROUPS`) |
 | `GITFLIC_MCP_EXCLUDE` | список имён тулзов | убрать конкретные тулзы (применяется последним) |
 
-Все — опциональные. Без них регистрируются все 77 (как и раньше). Неизвестные группы/имена не валят сервер — он пишет `WARN` в stderr и игнорирует их.
+Все — опциональные. Без них регистрируются все 76 (как и раньше). Неизвестные группы/имена не валят сервер — он пишет `WARN` в stderr и игнорирует их.
 
 **Порядок применения (precedence):**
 
@@ -92,7 +92,7 @@ claude mcp add gitflic --env GITFLIC_TOKEN=xxxxxxxx -- npx -y gitflic-cli-mcp
 | Группа | Тулзов | Read / Write |
 |---|---|---|
 | `auth` | 8 | 3 read / 5 write |
-| `blob` | 3 | 3 read / 0 write |
+| `blob` | 2 | 2 read / 0 write |
 | `branch` | 10 | 5 read / 5 write |
 | `commit` | 4 | 4 read / 0 write |
 | `issue` | 12 | 4 read / 8 write |
@@ -118,14 +118,14 @@ claude mcp add gitflic --env GITFLIC_TOKEN=xxxxxxxx -- npx -y gitflic-cli-mcp
 **Примеры:**
 
 ```bash
-# Только MR и issue (~27 тулзов вместо 77)
+# Только MR и issue (~27 тулзов вместо 76)
 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
 
-# Может всё, кроме удаления (70 тулзов: создаёт/правит/мёрджит — но не удаляет)
+# Может всё, кроме удаления (69 тулзов: создаёт/правит/мёрджит — но не удаляет)
 GITFLIC_MCP_NO_DESTRUCTIVE=1 npx -y gitflic-cli-mcp
 
 # Точный набор из четырёх тулзов
@@ -153,6 +153,21 @@ GITFLIC_MCP_TOOLS="gitflic_mr_list,gitflic_mr_view,gitflic_mr_diff,gitflic_mr_cr
 
 > Можно поднять один и тот же сервер дважды под разными именами — напр. `gitflic` (полный) и `gitflic-ro` (`GITFLIC_MCP_READONLY=1`) — и держать оба подключёнными. Либо класть конфиг в проектный `.mcp.json` / `.cursor/mcp.json`, чтобы в каждом репозитории грузились свои группы.
 
+## Сжатие ответов (экономия токенов)
+
+GitFlic REST API отдаёт «сырой» JSON с кучей бесполезного для LLM шума: URL аватаров/обложек, `hexColor` лейблов, `status` из 9 полей, вложенные объекты юзеров целиком, HAL-обёртки `_embedded`/`_links`. По умолчанию MCP **сжимает** ответы перед отдачей модели: разворачивает list-обёртку в `{ items, total, matched, returned }`, проецирует каждую сущность до нужных полей и схлопывает мусор. На реальных данных — **≈70% меньше токенов** (на коммитах/ветках до 84%). CLI `--format json` при этом остаётся «сырым» — сжатие живёт только в MCP-слое.
+
+| Переменная / аргумент | Значения | Эффект |
+| --- | --- | --- |
+| `GITFLIC_MCP_OUTPUT` | `slim` (по умолч.) / `full` (=`raw`) | глобальный режим: `full` = старый сырой ответ один-в-один |
+| `GITFLIC_MCP_RAW` | `1`/`true`/`yes`/`on` | то же, что `OUTPUT=full` (булев алиас, побеждает при конфликте) |
+| аргумент `raw: true` | на **любом** тулзе | вернуть полный несжатый ответ для **одного** вызова — если модели не хватило поля в slim-виде |
+| аргумент `fields: [...]` | на read/list тулзах | вернуть только указанные поля (+ id-ключи) |
+
+**Фильтрация списков на стороне MCP.** У GitFlic почти нет серверных фильтров для списков, поэтому list-тулзы принимают аргументы фильтра/сортировки (`label`, `q`, `assignee`, `status`, `author`, `name`, `sort`, `limit`, …). При их наличии хендлер автоматически дотягивает `--all` (полный набор), фильтрует и возвращает только совпадения + `matched`/`total`. Напр. «найди открытые issue с лейблом Security» вернёт 3 совпадения вместо всех 60.
+
+**Секреты вебхуков.** В slim-режиме `secret` маскируется в `secretSet: true|false` — сырой ответ его раньше **утекал** в модель. Прочитать реальное значение можно тулзом `gitflic_webhook_reveal_secret` — он помечен деструктивным, поэтому MCP-хост спросит подтверждение перед выдачей.
+
 ## Все 77 тулзов
 
 Полный список по группам. **R** = read-only (`readOnlyHint: true`, не меняет состояние — попадает в `GITFLIC_MCP_READONLY=1`); **W** = write/мутация.
@@ -160,8 +175,8 @@ GITFLIC_MCP_TOOLS="gitflic_mr_list,gitflic_mr_view,gitflic_mr_diff,gitflic_mr_cr
 ### `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`
+### `blob` (2)
+`R` `gitflic_blob_get` · `R` `gitflic_blob_files`
 
 ### `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`
@@ -187,10 +202,10 @@ GITFLIC_MCP_TOOLS="gitflic_mr_list,gitflic_mr_view,gitflic_mr_diff,gitflic_mr_cr
 ### `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`
+### `webhook` (5)
+`R` `gitflic_webhook_list` · `R` `gitflic_webhook_get` · `W` `gitflic_webhook_create` · `W` `gitflic_webhook_delete` · `W` `gitflic_webhook_reveal_secret` (требует подтверждения хоста)
 
-Итого: **40 read / 37 write**. Каждый тул маппится 1-в-1 на подкоманду CLI (`gitflic …`).
+Итого: **39 read / 38 write**. Каждый тул маппится 1-в-1 на подкоманду CLI (`gitflic …`).
 
 ## Как это работает
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitflic-cli-mcp",
-  "version": "0.3.0",
+  "version": "0.4.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": {
@@ -11,6 +11,7 @@
     "runner.mjs",
     "tools.mjs",
     "filter.mjs",
+    "slim.mjs",
     "project-resolver.mjs",
     "README.md"
   ],
@@ -45,7 +46,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "gitflic-cli": "^0.3.0",
+    "gitflic-cli": "^0.3.3",
     "zod": "^3.25.76"
   }
 }

package/server.mjs

@@ -23,6 +23,7 @@ import { runGitflic, runGitflicJson, GitflicError } from "./runner.mjs";
 import { TOOLS } from "./tools.mjs";
 import { selectTools } from "./filter.mjs";
 import { resolveProjectArg } from "./project-resolver.mjs";
+import { slimResult } from "./slim.mjs";
 
 const server = new McpServer(
   {
@@ -113,8 +114,12 @@ for (const tool of selected) {
           }
           throw e;
         }
+        // Shape the response for the LLM (issue #1): flatten HAL envelopes,
+        // project per entity, drop noise, mask secrets. Opt out per-call with
+        // `raw:true` or globally with GITFLIC_MCP_RAW=1 / GITFLIC_MCP_OUTPUT=full.
+        const shaped = slimResult(tool.name, result, resolvedArgs, process.env);
         return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+          content: [{ type: "text", text: JSON.stringify(shaped, null, 2) }],
         };
       } catch (err) {
         return {

package/slim.mjs

@@ -0,0 +1,298 @@
+// Token-slimming layer for MCP responses (GitFlic issue #1).
+//
+// The MCP used to return the raw GitFlic API JSON verbatim (server.mjs did
+// JSON.stringify(result)). That dumps LLM-useless noise — avatar/cover URLs,
+// label hexColors, 9-field status sub-objects, full nested user objects, HAL
+// `_embedded`/`_links` envelopes — costing the model a lot of tokens.
+//
+// This module shapes the response at the single MCP boundary. The CLI's own
+// `--format json` stays byte-for-byte raw (humans/scripts depend on it) — all
+// shaping lives here. Three controls, in precedence order:
+//   1. per-call  `raw: true`            -> return the full, un-slimmed response
+//   2. global    GITFLIC_MCP_RAW=1      -> same, for every call
+//      or        GITFLIC_MCP_OUTPUT=full
+//   3. default (slim): flatten envelope + project per entity + drop noise.
+// Plus a per-call `fields: [...]` to narrow the projection further.
+//
+// Pure + testable: every function takes explicit input; only outputMode reads env.
+
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+const truthy = (v) => v != null && TRUTHY.has(String(v).trim().toLowerCase());
+
+// Resolve the output mode from env. RAW wins over OUTPUT if both are set.
+export function outputMode(env = {}) {
+  if (truthy(env.GITFLIC_MCP_RAW)) return "full";
+  const o = String(env.GITFLIC_MCP_OUTPUT || "").trim().toLowerCase();
+  if (o === "full" || o === "raw") return "full";
+  return "slim";
+}
+
+// ---- collapse helpers --------------------------------------------------------
+const userName = (u) =>
+  u && typeof u === "object" ? (u.username || u.fullName || u.name || null) : u;
+// status sub-object -> its machine enum scalar (OPEN / OPENED / MERGED / ...).
+// Prefer .id (the stable token an LLM filters/acts on) over .title (display).
+const statusId = (s) => (s && typeof s === "object" ? (s.id ?? s.title ?? null) : s);
+const labelTitles = (ls) =>
+  Array.isArray(ls)
+    ? ls.map((l) => (l && typeof l === "object" ? (l.title ?? l.name ?? null) : l)).filter((x) => x != null)
+    : ls;
+
+// ---- generic denylist: provably-cosmetic keys, stripped at any depth ---------
+// Deliberately NARROW. Addressing/meaningful keys (hash, alias, mode, isBinary)
+// are NOT here — they are only collapsed inside the per-entity projectors.
+const DENY = new Set([
+  "avatar", "cover", "hexColor", "color", "icon",
+  "_links", "_embedded", "_pagination", "avatarRadius", "createdLogo", "logoUrl",
+]);
+export function deny(node) {
+  if (Array.isArray(node)) return node.map(deny);
+  if (node && typeof node === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(node)) {
+      if (DENY.has(k)) continue;
+      if (k === "secret") { out.secretSet = !!(v && v !== "no-secret"); continue; } // never leak
+      out[k] = deny(v);
+    }
+    return out;
+  }
+  return node;
+}
+
+// ---- per-entity projectors (keep-sets derived from lib/cmd/*.mjs printXxx) ---
+const slimCommit = (c, { full = false } = {}) => ({
+  hash: c.hash,
+  shortMessage: c.shortMessage ?? (c.message ? c.message.split("\n")[0] : undefined),
+  ...(full && c.message ? { message: c.message } : {}), // full body only on `commit get`
+  author: userName(c.user) || c.authorIdent?.name,
+  authorEmail: c.authorIdent?.emailAddress,
+  createdAt: c.createdAt,
+  verified: !!c.verificationResult?.verified,
+  ...((c.parentCommitIds || []).length > 1 ? { parents: c.parentCommitIds } : {}),
+});
+const slimLastCommit = (c) =>
+  c ? { hash: c.hash, shortMessage: c.shortMessage, author: userName(c.user) || c.authorIdent?.name, date: c.authorIdent?.when ?? c.createdAt } : undefined;
+
+const P = {
+  issue: (i) => ({
+    localId: i.localId, id: i.id, title: i.title,
+    status: statusId(i.status),
+    labels: labelTitles(i.labels) ?? [],
+    assignedUsers: (i.assignedUsers || []).map(userName).filter(Boolean),
+    author: i.userAlias ?? userName(i.createdBy),
+    ...(i.updatedBy ? { updatedBy: userName(i.updatedBy) } : {}),
+    createdAt: i.createdAt, updatedAt: i.updatedAt,
+    ...(i.description != null ? { description: i.description } : {}),
+  }),
+  note: (n) => ({
+    uuid: n.uuid, message: n.message, author: userName(n.author),
+    createdAt: n.createdAt, ...(n.updatedAt ? { updatedAt: n.updatedAt } : {}),
+  }),
+  mr: (m) => ({
+    localId: m.localId, id: m.id, title: m.title,
+    status: statusId(m.status),
+    author: userName(m.createdBy) || userName(m.author),
+    sourceBranch: m.sourceBranch?.alias || m.sourceBranch?.id || m.sourceBranch,
+    targetBranch: m.targetBranch?.alias || m.targetBranch?.id || m.targetBranch,
+    ...(m.canMerge !== undefined ? { canMerge: m.canMerge } : {}),
+    ...(m.hasConflicts !== undefined ? { hasConflicts: m.hasConflicts } : {}),
+    createdAt: m.createdAt, ...(m.updatedAt ? { updatedAt: m.updatedAt } : {}),
+    ...(m.projectAlias ? { projectAlias: m.projectAlias } : {}),
+    ...(m.description != null ? { description: m.description } : {}),
+  }),
+  discussion: (d) => ({
+    uuid: d.rootNote?.uuid ?? d.uuid,
+    resolved: d.rootNote?.resolved ?? d.resolved,
+    author: userName(d.rootNote?.author ?? d.author),
+    message: d.rootNote?.message ?? d.message,
+    createdAt: d.rootNote?.createdAt ?? d.createdAt,
+    ...(Array.isArray(d.replies)
+      ? { replies: d.replies.map((r) => ({ uuid: r.uuid, author: userName(r.author), message: r.message })) }
+      : {}),
+  }),
+  commit: (c) => slimCommit(c, { full: false }),
+  commitFull: (c) => slimCommit(c, { full: true }),
+  release: (r) => ({
+    id: r.id, tagName: r.tagName, title: r.title,
+    commitId: r.commitId, preRelease: r.preRelease,
+    createdAt: r.createdAt, updatedAt: r.updatedAt,
+    filesCount: (r.attachmentFiles || []).length,
+    ...(r.description != null ? { description: r.description } : {}),
+  }),
+  branch: (b) => ({ name: b.name, default: b.default, work: b.work, merged: b.merged, lastCommit: slimLastCommit(b.lastCommit) }),
+  tag: (t) => ({
+    name: t.name, lightWeight: t.lightWeight, commitId: t.commitId, shortMessage: t.shortMessage,
+    tagger: t.personIdent ? `${t.personIdent.name} <${t.personIdent.emailAddress}>` : undefined,
+    date: t.personIdent?.when,
+  }),
+  user: (u) => ({ id: u.id, username: u.username, fullName: u.fullName, ...(u.email ? { email: u.email } : {}) }),
+  project: (p) => ({
+    id: p.id, alias: p.alias, title: p.title,
+    owner: p.owner?.alias || userName(p.owner) || p.owner,
+    ...(p.defaultBranch ? { defaultBranch: p.defaultBranch } : {}),
+    private: p.private,
+    ...(p.language ? { language: p.language } : {}),
+    ...(p.description ? { description: String(p.description).split("\n")[0] } : {}),
+    ...(p.httpTransportUrl ? { httpTransportUrl: p.httpTransportUrl } : {}),
+  }),
+  member: (m) => ({ user: userName(m.user) ?? m.userAlias, role: m.role }),
+  webhook: (w) => ({
+    id: w.id, url: w.url || w.targetUrl,
+    events: Object.entries(w.events || {}).filter(([, on]) => on).map(([n]) => n),
+    secretSet: !!(w.secret && w.secret !== "no-secret"),
+    createdAt: w.createdAt,
+  }),
+};
+
+// tool name -> { list?: projector } for *_list/*_search, { single?: projector } otherwise.
+// Tools absent here (diff/blob/compare, auth, deletes) fall through to deny() only —
+// diff/blob bodies ARE the answer, so they must be light-stripped, never projected.
+export const SHAPE = {
+  gitflic_issue_list: { list: P.issue }, gitflic_issue_view: { single: P.issue },
+  gitflic_issue_create: { single: P.issue }, gitflic_issue_edit: { single: P.issue },
+  gitflic_issue_close: { single: P.issue }, gitflic_issue_reopen: { single: P.issue },
+  gitflic_issue_comments_list: { list: P.note },
+  gitflic_mr_list: { list: P.mr }, gitflic_mr_by_commit: { list: P.mr },
+  gitflic_mr_view: { single: P.mr }, gitflic_mr_create: { single: P.mr },
+  gitflic_mr_edit: { single: P.mr }, gitflic_mr_approve: { single: P.mr },
+  gitflic_mr_merge: { single: P.mr }, gitflic_mr_close: { single: P.mr }, gitflic_mr_cancel: { single: P.mr },
+  gitflic_mr_discuss_list: { list: P.discussion },
+  gitflic_commit_list: { list: P.commit }, gitflic_commit_get: { single: P.commitFull },
+  gitflic_release_list: { list: P.release }, gitflic_release_get: { single: P.release },
+  gitflic_release_latest: { single: P.release }, gitflic_release_create: { single: P.release }, gitflic_release_edit: { single: P.release },
+  gitflic_branch_list: { list: P.branch }, gitflic_branch_get: { single: P.branch }, gitflic_branch_default: { single: P.branch },
+  gitflic_tag_list: { list: P.tag }, gitflic_tag_get: { single: P.tag },
+  gitflic_user_search: { list: P.user }, gitflic_user_followers: { list: P.user },
+  gitflic_user_me: { single: P.user }, gitflic_auth: { single: P.user }, gitflic_user_get: { single: P.user },
+  gitflic_user_projects: { list: P.project },
+  gitflic_project_list_my: { list: P.project },
+  gitflic_project_get: { single: P.project }, gitflic_project_create: { single: P.project }, gitflic_project_edit: { single: P.project },
+  gitflic_project_member_list: { list: P.member },
+  gitflic_webhook_list: { list: P.webhook }, gitflic_webhook_get: { single: P.webhook }, gitflic_webhook_create: { single: P.webhook },
+};
+
+// ---- `fields` projection override -------------------------------------------
+const ID_KEYS = ["id", "localId", "uuid", "hash", "commitId", "name", "alias"];
+function pickFields(item, fields) {
+  if (!item || typeof item !== "object") return item;
+  const out = {};
+  for (const k of new Set([...fields, ...ID_KEYS])) if (k in item) out[k] = item[k];
+  return out;
+}
+
+// ---- HAL envelope flatten ----------------------------------------------------
+function listOf(data) {
+  const emb = data && data._embedded;
+  if (!emb || typeof emb !== "object") return null;
+  const key = Object.keys(emb).find((k) => Array.isArray(emb[k]));
+  if (!key) return null;
+  return { items: emb[key], total: data.page?.totalElements };
+}
+
+// ---- client-side list filters (run on RAW items, BEFORE projection) ----------
+// GitFlic exposes almost no server-side list filters, so the slim layer filters
+// the (auto-paginated) full set. Must read RAW items so labels[].title /
+// assignedUsers[].username / branch.alias are still present to match on.
+const ci = (s) => String(s ?? "").toLowerCase();
+const globToRe = (g) =>
+  new RegExp("^" + String(g).split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$", "i");
+const branchName = (b) => (b && typeof b === "object" ? (b.alias || b.id) : b);
+
+export const FILTER_KEYS = [
+  "label", "assignee", "author", "status", "q", "name", "tag", "event",
+  "targetBranch", "sourceBranch", "language", "merged", "preRelease", "private", "lightWeight", "sort", "limit",
+];
+export const hasFilter = (args = {}) =>
+  FILTER_KEYS.some((k) => args[k] !== undefined && args[k] !== "" && args[k] !== null);
+
+export function applyListFilters(items, args = {}) {
+  let out = items;
+  if (args.label) out = out.filter((i) => (labelTitles(i.labels) || []).some((t) => ci(t).includes(ci(args.label))));
+  if (args.assignee) out = out.filter((i) => (i.assignedUsers || []).some((u) => ci(userName(u)) === ci(args.assignee)));
+  if (args.author) out = out.filter((i) => ci(userName(i.createdBy) || userName(i.user) || i.userAlias || i.authorIdent?.name).includes(ci(args.author)));
+  if (args.status) out = out.filter((i) => ci(statusId(i.status)) === ci(args.status));
+  if (args.targetBranch) out = out.filter((i) => ci(branchName(i.targetBranch)).includes(ci(args.targetBranch)));
+  if (args.sourceBranch) out = out.filter((i) => ci(branchName(i.sourceBranch)).includes(ci(args.sourceBranch)));
+  if (args.tag) out = out.filter((i) => ci(i.tagName).includes(ci(args.tag)));
+  if (args.language) out = out.filter((i) => ci(i.language) === ci(args.language));
+  if (args.event) out = out.filter((i) => i.events && i.events[String(args.event).toUpperCase()] === true);
+  if (args.merged !== undefined) out = out.filter((i) => !!i.merged === !!args.merged);
+  if (args.preRelease !== undefined) out = out.filter((i) => !!i.preRelease === !!args.preRelease);
+  if (args.private !== undefined) out = out.filter((i) => !!i.private === !!args.private);
+  if (args.lightWeight !== undefined) out = out.filter((i) => !!i.lightWeight === !!args.lightWeight);
+  if (args.name) { const re = globToRe(args.name); out = out.filter((i) => re.test(i.name ?? "") || ci(i.name).includes(ci(args.name))); }
+  if (args.q) {
+    const q = ci(args.q);
+    out = out.filter((i) => `${i.title ?? ""} ${i.description ?? ""} ${i.shortMessage ?? ""} ${i.message ?? ""}`.toLowerCase().includes(q));
+  }
+  if (args.sort) {
+    const desc = String(args.sort)[0] === "-";
+    const k = String(args.sort).replace(/^-/, "");
+    out = [...out].sort((a, b) => { const av = a[k], bv = b[k]; return (av > bv ? 1 : av < bv ? -1 : 0) * (desc ? -1 : 1); });
+  }
+  if (args.limit !== undefined) { const n = Number(args.limit); if (Number.isFinite(n) && n >= 0) out = out.slice(0, n); }
+  return out;
+}
+
+// Mask every `secret` key (-> secretSet:bool) at any depth, preserving the rest
+// byte-for-byte. Returns the SAME reference when no secret is present, so the
+// raw/full path stays a true identity passthrough for secret-free payloads.
+// This is the guard that keeps `raw:true` / GITFLIC_MCP_RAW from becoming an
+// unprompted secret-exfiltration path — the approval-gated reveal tool is the
+// ONLY exit for a real secret value.
+export function maskSecrets(node) {
+  if (Array.isArray(node)) {
+    let changed = false;
+    const out = node.map((v) => { const m = maskSecrets(v); if (m !== v) changed = true; return m; });
+    return changed ? out : node;
+  }
+  if (node && typeof node === "object") {
+    let changed = false;
+    const out = {};
+    for (const [k, v] of Object.entries(node)) {
+      if (k === "secret") { out.secretSet = !!(v && v !== "no-secret"); changed = true; continue; }
+      const m = maskSecrets(v);
+      if (m !== v) changed = true;
+      out[k] = m;
+    }
+    return changed ? out : node;
+  }
+  return node;
+}
+
+// ---- entry point -------------------------------------------------------------
+export function slimResult(toolName, result, args = {}, env = process.env) {
+  // The approval-gated reveal tool is the ONLY path to a real secret value.
+  if (toolName === "gitflic_webhook_reveal_secret") {
+    if (result == null || typeof result !== "object") return result;
+    return { id: result.id, url: result.url || result.targetUrl, secret: result.secret ?? null };
+  }
+  // Escape hatches: full fidelity for the LLM — EXCEPT secrets stay masked, so
+  // raw/full never becomes an unprompted secret leak (per-call raw, or global
+  // GITFLIC_MCP_RAW=1 / GITFLIC_MCP_OUTPUT=full).
+  if ((args && args.raw === true) || outputMode(env) === "full") return maskSecrets(result);
+  if (result == null || typeof result !== "object") return result;
+  if (result.raw != null && Object.keys(result).length === 1) return result; // {raw:text}
+
+  const fields = Array.isArray(args.fields) && args.fields.length ? args.fields : null;
+  const shape = SHAPE[toolName] || {};
+  // Treat known list tools as lists even when GitFlic omits `_embedded` on a
+  // zero-result response, so the {items,total,returned} contract is consistent.
+  let lst = listOf(result);
+  if (!lst && shape.list && result.page) lst = { items: [], total: result.page.totalElements };
+
+  if (lst) {
+    let items = Array.isArray(lst.items) ? lst.items : [];
+    if (hasFilter(args)) items = applyListFilters(items, args);
+    const matched = items.length;
+    const project = fields ? (it) => pickFields(it, fields) : (shape.list || ((x) => x));
+    const slimmed = items.map((it) => deny(project(it))); // deny() = final cosmetic+secret sweep
+    const res = { items: slimmed, ...(lst.total != null ? { total: lst.total } : {}), returned: slimmed.length };
+    if (lst.total != null && matched !== lst.total) res.matched = matched;
+    return res;
+  }
+
+  if (fields) return deny(pickFields(result, fields));
+  if (shape.single) return deny(shape.single(result));
+  return deny(result); // unmapped single entity -> light strip only
+}

package/tools.mjs

@@ -242,10 +242,10 @@ export const TOOLS = [
   {
     name: "gitflic_mr_create",
     description:
-      "Create a new merge request. If --from is omitted, uses current git branch. If --to is omitted, uses project default branch.",
+      "Create a new merge request. `description` is required (GitFlic rejects empty MR descriptions). If `from` is omitted, uses current git branch; if `to` is omitted, uses project default branch.",
     inputSchema: {
       type: "object",
-      required: ["project", "title"],
+      required: ["project", "title", "description"],
       properties: {
         project: { type: "string" },
         title: { type: "string" },
@@ -1376,6 +1376,24 @@ export const TOOLS = [
       openWorldHint: true,
     },
   },
+  {
+    name: "gitflic_webhook_reveal_secret",
+    description:
+      "Reveal the raw signing secret of a webhook. SENSITIVE: by default the MCP masks secrets (returns secretSet:true/false). This tool returns the actual secret value and is marked destructive so the MCP host prompts for approval before it runs. Use only when the user explicitly needs the secret value.",
+    inputSchema: {
+      type: "object",
+      required: ["project", "uuid"],
+      properties: { project: { type: "string" }, uuid: { type: "string" } },
+    },
+    handler: (a) => ["webhook", "get", a.uuid, "--project", a.project, "--format", "json"],
+    annotations: {
+      title: "Webhook Reveal Secret",
+      readOnlyHint: false, // not read-only on purpose: triggers the host approval prompt
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
 
   // ===== Project: get / create / edit / member list =====================
   {
@@ -1430,7 +1448,7 @@ export const TOOLS = [
   },
   {
     name: "gitflic_project_edit",
-    description: "Edit project metadata (title, description, default branch, visibility).",
+    description: "Edit project title, description, or language (via change-setting). Visibility and default branch are not editable over the REST API.",
     inputSchema: {
       type: "object",
       required: ["project"],
@@ -1438,18 +1456,14 @@ export const TOOLS = [
         project: { type: "string" },
         title: { type: "string" },
         description: { type: "string" },
-        isPrivate: { type: "boolean" },
         language: { type: "string" },
-        defaultBranch: { type: "string" },
       },
     },
     handler: (a) => {
       const args = ["project", "edit", a.project, "--format", "json"];
       if (a.title) args.push("--title", a.title);
       if (a.description !== undefined) args.push("--description", a.description);
-      if (a.isPrivate !== undefined) args.push(a.isPrivate ? "--private" : "--public");
       if (a.language) args.push("--language", a.language);
-      if (a.defaultBranch) args.push("--default-branch", a.defaultBranch);
       return args;
     },
     annotations: {
@@ -1540,8 +1554,8 @@ export const TOOLS = [
       },
     },
     handler: (a) => {
-      const args = ["blob", "files", "--project", a.project, "--format", "json"];
-      if (a.path) args.push("--path", a.path);
+      const args = ["blob", "recursive", "--project", a.project, "--format", "json"];
+      if (a.path) args.push("--directory", a.path);
       if (a.branch) args.push("--branch", a.branch);
       return args;
     },
@@ -1553,23 +1567,6 @@ export const TOOLS = [
       openWorldHint: true,
     },
   },
-  {
-    name: "gitflic_blob_archive",
-    description: "Download a repo archive (tarball). Returns JSON metadata; use shell to stream the body.",
-    inputSchema: {
-      type: "object",
-      required: ["project", "branch"],
-      properties: { project: { type: "string" }, branch: { type: "string" } },
-    },
-    handler: (a) => ["blob", "archive", a.branch, "--project", a.project, "--format", "json"],
-    annotations: {
-      title: "Blob Archive",
-      readOnlyHint: true,
-      destructiveHint: false,
-      idempotentHint: false,
-      openWorldHint: true,
-    },
-  },
 
   // ===== User: get / projects / followers =================================
   {
@@ -1625,5 +1622,119 @@ export const TOOLS = [
   },
 ];
 
+// ===== issue #1: token-slimming support (applied uniformly, post-definition) =
+// Kept here (not inline on every tool) so the surface is one DRY block.
+//
+//  - `raw`    : per-call escape hatch on EVERY tool — returns the full,
+//               un-slimmed GitFlic response for that call (the slim layer in
+//               slim.mjs honors it). Complements GITFLIC_MCP_RAW (global).
+//  - `fields` : on read/list tools — narrow the response to the named
+//               top-level fields (plus id keys).
+//  - filter/sort/limit args on list tools — consumed client-side by slim.mjs
+//               (GitFlic has almost no server-side list filters). When any is
+//               present, the handler also appends `--all` so the filter sees
+//               the whole set, not just page 0.
+const STR = (description) => ({ type: "string", description });
+const NUM = (description) => ({ type: "number", description });
+const BOOL = (description) => ({ type: "boolean", description });
+
+// Per-list-tool filter args (name -> JSON-schema prop).
+const FILTER_PROPS = {
+  gitflic_issue_list: {
+    label: STR("Keep only issues with a label whose title contains this (case-insensitive)."),
+    assignee: STR("Keep only issues assigned to this username."),
+    q: STR("Free-text filter over title + description."),
+    sort: STR("Sort by a field; prefix '-' for descending (e.g. '-createdAt')."),
+    limit: NUM("Return at most N issues after filtering/sorting."),
+  },
+  gitflic_mr_list: {
+    status: STR("Filter by status (OPENED|MERGED|CLOSED|CANCELED|FAILED)."),
+    author: STR("Keep only MRs by this author username."),
+    targetBranch: STR("Keep only MRs targeting a branch matching this."),
+    sourceBranch: STR("Keep only MRs from a source branch matching this."),
+    q: STR("Free-text filter over title + description."),
+    sort: STR("Sort field; prefix '-' for descending."),
+    limit: NUM("Return at most N."),
+  },
+  gitflic_commit_list: {
+    author: STR("Keep only commits by this author."),
+    q: STR("Free-text filter over the commit message."),
+    sort: STR("Sort field; prefix '-' for descending."),
+    limit: NUM("Return at most N (e.g. last 10 commits)."),
+  },
+  gitflic_release_list: {
+    preRelease: BOOL("true = only pre-releases, false = only stable."),
+    tag: STR("Keep only releases whose tagName contains this."),
+    q: STR("Free-text filter over title + description."),
+    sort: STR("Sort field; prefix '-' for descending."),
+    limit: NUM("Return at most N (e.g. last 3 releases)."),
+  },
+  gitflic_branch_list: {
+    name: STR("Glob/substring filter on branch name (e.g. 'release/*')."),
+    merged: BOOL("true = only merged branches, false = only unmerged."),
+    sort: STR("Sort field; prefix '-' for descending."),
+    limit: NUM("Return at most N."),
+  },
+  gitflic_tag_list: {
+    name: STR("Glob/substring filter on tag name (e.g. 'v1.*')."),
+    lightWeight: BOOL("true = only lightweight tags, false = only annotated."),
+    sort: STR("Sort field; prefix '-' for descending."),
+    limit: NUM("Return at most N."),
+  },
+  gitflic_webhook_list: {
+    event: STR("Keep only webhooks subscribed to this event (e.g. MERGE)."),
+    limit: NUM("Return at most N."),
+  },
+  gitflic_project_list_my: {
+    q: STR("Name/text filter (forwarded to GitFlic server-side, plus client match)."),
+    language: STR("Keep only projects in this language."),
+    private: BOOL("true = only private, false = only public."),
+    sort: STR("Sort field; prefix '-' for descending."),
+    limit: NUM("Return at most N."),
+  },
+  gitflic_user_projects: {
+    language: STR("Keep only projects in this language."),
+    private: BOOL("true = only private, false = only public."),
+    q: STR("Name/text filter."),
+    sort: STR("Sort field; prefix '-' for descending."),
+    limit: NUM("Return at most N."),
+  },
+  gitflic_user_followers: {
+    q: STR("Username substring filter."),
+    limit: NUM("Return at most N."),
+  },
+};
+const LIST_TOOLS = new Set(Object.keys(FILTER_PROPS));
+// Args whose presence means "fetch everything, then filter client-side".
+const ALL_TRIGGER = [
+  "label", "assignee", "author", "status", "targetBranch", "sourceBranch", "q",
+  "name", "tag", "event", "language", "merged", "preRelease", "private", "lightWeight", "sort", "limit",
+];
+const needsAll = (a = {}) => ALL_TRIGGER.some((k) => a[k] !== undefined && a[k] !== "" && a[k] !== null);
+
+for (const t of TOOLS) {
+  const props = t.inputSchema.properties || (t.inputSchema.properties = {});
+  if (!props.raw) {
+    props.raw = BOOL(
+      "Return the full, un-slimmed GitFlic response for THIS call (no token compression). Use when the default slim view dropped a field you need.",
+    );
+  }
+  if ((t.annotations?.readOnlyHint || LIST_TOOLS.has(t.name)) && !props.fields) {
+    props.fields = { type: "array", description: "Return only these top-level fields (plus id keys), narrowing the response further." };
+  }
+  const fp = FILTER_PROPS[t.name];
+  if (fp) {
+    for (const [k, schema] of Object.entries(fp)) if (!props[k]) props[k] = schema;
+    const orig = t.handler;
+    t.handler = (a = {}) => {
+      const argv = orig(a);
+      // project_list_my: GitFlic supports server-side ?q= for project listings.
+      if (t.name === "gitflic_project_list_my" && a.q && !argv.includes("--q")) argv.push("--q", String(a.q));
+      if (needsAll(a) && !argv.includes("--all")) argv.push("--all");
+      return argv;
+    };
+  }
+}
+
 // Build the JSON Schema for ListTools request, just to help debugging.
 export const TOOL_NAMES = TOOLS.map((t) => t.name);