gitflic-cli-mcp 0.3.1 → 0.4.0

package/README.md

@@ -153,7 +153,22 @@ 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`, чтобы в каждом репозитории грузились свои группы.
 
-## Все 76 тулзов
+## Сжатие ответов (экономия токенов)
+
+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/мутация.
 
@@ -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` (требует подтверждения хоста)
 
-Итого: **39 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.1",
+  "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

@@ -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 =====================
   {
@@ -1604,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);