gitflic-cli-mcp 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# gitflic-cli MCP-сервер
+
+[Model Context Protocol](https://modelcontextprotocol.io/) сервер, оборачивающий CLI `gitflic` и отдающий **77 типизированных тулзов** поверх команд GitFlic REST для AI-агентов (Claude Code, Cursor и т.п.).
+
+## Что внутри
+
+- `server.mjs` — MCP-сервер на stdio, регистрирует все тулзы, диспетчеризует в CLI.
+- `tools.mjs` — описания тулзов (имя, описание, JSON-схема, билдер аргументов CLI).
+- `runner.mjs` — обёртка над `child_process`, запускает `gitflic` CLI (`node …/lib/gitflic.mjs`) и парсит JSON.
+- зависимости: `@modelcontextprotocol/sdk`, `zod` и сам `gitflic-cli` (CLI).
+
+MCP-сервер — это **тонкая прослойка**: каждая тулза маппится 1-в-1 на подкоманду CLI. Всё, что можно сделать через `gitflic …`, доступно и из MCP-хоста.
+
+## Установка
+
+Ставить ничего не нужно — запуск через `npx`:
+
+```bash
+GITFLIC_TOKEN="xxxx" npx -y gitflic-cli-mcp
+```
+
+`npx` подтянет пакет, его зависимости и сам CLI `gitflic-cli`. Из исходников — вручную:
+
+```bash
+cd mcp-server && npm install
+GITFLIC_TOKEN="xxxx" node server.mjs
+```
+
+Требуется Node 18+.
+
+## Настройка токена
+
+Сервер читает `GITFLIC_TOKEN` из окружения родительского процесса — ровно так же, как CLI:
+
+```bash
+export GITFLIC_TOKEN="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+```
+
+Для self-hosted GitFlic дополнительно: `export GITFLIC_API_BASE=https://git.example.com`.
+
+## Регистрация в MCP-хосте
+
+### Claude Code
+
+```bash
+claude mcp add gitflic --env GITFLIC_TOKEN=xxxxxxxx -- npx -y gitflic-cli-mcp
+```
+
+Или вручную в `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "gitflic": {
+      "command": "npx",
+      "args": ["-y", "gitflic-cli-mcp"],
+      "env": { "GITFLIC_TOKEN": "xxxxxxxx" }
+    }
+  }
+}
+```
+
+### Cursor (`~/.cursor/mcp.json`)
+
+Та же структура. Перезапустите хост. (Из исходников: `"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 …` напрямую.
+
+## Как это работает
+
+```
+[Claude Code / Cursor]
+        │   JSON-RPC по stdio
+        ▼
+  mcp-server/server.mjs
+        │   тулз-вызов после zod-валидации
+        ▼
+  mcp-server/runner.mjs   ── spawn ──►  node …/gitflic-cli/lib/gitflic.mjs mr create --title "…" --format json
+        │
+        ▼
+  распарсенный JSON-ответ
+```
+
+Каждый хендлер тулза возвращает `["gitflic", "subcommand", "--flag", "value", …, "--format", "json"]`. Runner форсит добавление `--format json` в конец, парсит и возвращает структурированные данные.
+
+При ненулевом коде выхода (HTTP 422, 403, 404) тулз возвращает `isError: true` с текстом ошибки от gitflic — агент видит сбой и может восстановиться.
+
+## Расширение
+
+Добавьте тулз, дописав в `TOOLS` в `tools.mjs`:
+
+```js
+{
+  name: "gitflic_release_delete",
+  description: "Delete a release by uuid.",
+  inputSchema: {
+    type: "object",
+    required: ["project", "uuid"],
+    properties: { project: { type: "string" }, uuid: { type: "string" } },
+  },
+  handler: (a) => ["release", "delete", a.uuid, "--project", a.project, "--format", "json"],
+}
+```
+
+Отдельного кода регистрации нет — цикл в `server.mjs` подхватит тулз автоматически.
+
+## Лицензия
+
+MIT (как у родительского проекта).

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "gitflic-cli-mcp",
+  "version": "0.1.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": {
+    "gitflic-mcp": "server.mjs"
+  },
+  "files": [
+    "server.mjs",
+    "runner.mjs",
+    "tools.mjs",
+    "project-resolver.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node server.mjs"
+  },
+  "keywords": [
+    "gitflic",
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "claude",
+    "cursor",
+    "rest-api"
+  ],
+  "homepage": "https://cli-gitflic.ru/mcp-server.html",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitflic.ru/tikhon/gitflic-cli.git",
+    "directory": "mcp-server"
+  },
+  "bugs": {
+    "url": "https://cli-gitflic.ru/known-issues.html"
+  },
+  "author": "Tikhon Ustinov",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "gitflic-cli": "^0.3.0",
+    "zod": "^3.25.76"
+  }
+}

package/project-resolver.mjs

@@ -0,0 +1,56 @@
+// Helper: figure out which project (owner/alias) to use when an MCP tool
+// is called without an explicit `project` argument.
+//
+// Resolution order:
+//   1. process.env.GITFLIC_PROJECT     (e.g. "tikhon/wave")
+//   2. autodetect from `git remote get-url origin` in the current cwd
+//   3. return null — let the tool/CLI surface its own error
+//
+// This mirrors the auto-detect that the gitflic CLI does, so MCP tools
+// work without per-call boilerplate when the agent is in a clone.
+
+import { spawnSync } from "node:child_process";
+
+function runGit(args) {
+  try {
+    const r = spawnSync("git", args, { encoding: "utf8" });
+    if (r.status !== 0) return null;
+    const out = (r.stdout || "").trim();
+    return out.length ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+function detectFromRemote() {
+  const url = runGit(["config", "--get", "remote.origin.url"]);
+  if (!url) return null;
+  // Matches:
+  //   git@gitflic.ru:owner/alias[.git]
+  //   ssh://git@gitflic.ru[:port]/owner/alias[.git]
+  //   https://gitflic.ru/owner/alias[.git]
+  //   https://[subdomain.]gitflic.ru/owner/alias[.git]
+  const gitflicMatch = url.match(
+    /gitflic\.ru[:/]([^/]+)\/([^/\s]+?)(?:\.git)?\/?$/i,
+  );
+  if (gitflicMatch) return `${gitflicMatch[1]}/${gitflicMatch[2]}`;
+  // Self-hosted: any host with /owner/alias path.
+  const genericMatch = url.match(/\/([^/]+)\/([^/\s]+?)(?:\.git)?\/?$/);
+  if (genericMatch) return `${genericMatch[1]}/${genericMatch[2]}`;
+  return null;
+}
+
+export function resolveProjectArg(args) {
+  if (args && typeof args.project === "string" && args.project.length) {
+    return args;
+  }
+  const envProj = process.env.GITFLIC_PROJECT;
+  if (envProj && envProj.length) {
+    return { ...args, project: envProj };
+  }
+  const auto = detectFromRemote();
+  if (auto) {
+    return { ...args, project: auto };
+  }
+  return args;
+}

package/runner.mjs

@@ -0,0 +1,92 @@
+// Runner — thin wrapper that spawns the gitflic CLI and returns parsed JSON or text.
+
+import { spawn } from "node:child_process";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import process from "node:process";
+
+const require = createRequire(import.meta.url);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Resolve the gitflic CLI's Node entrypoint, then run it with `node`.
+// We deliberately avoid the bash shim (bin/gitflic) so this works on Windows
+// and when the MCP server is installed standalone via `npx gitflic-cli-mcp`:
+//   - installed from npm:  `gitflic-cli` is a dependency → resolves from node_modules
+//   - source checkout:     mcp-server/ sits inside the CLI repo → ../lib/gitflic.mjs
+// Fail fast with a clear message if neither is present, instead of a cryptic
+// ENOENT on the first tool call.
+function resolveCliEntry() {
+  try {
+    return require.resolve("gitflic-cli/lib/gitflic.mjs");
+  } catch {
+    const fallback = resolve(__dirname, "..", "lib", "gitflic.mjs");
+    if (!existsSync(fallback)) {
+      throw new Error(
+        "gitflic CLI not found: neither the 'gitflic-cli' package nor the " +
+          `source-checkout fallback (${fallback}) is available. Install ` +
+          "gitflic-cli (e.g. via `npx -y gitflic-cli-mcp`) or run from the repo.",
+      );
+    }
+    return fallback;
+  }
+}
+const CLI_ENTRY = resolveCliEntry();
+
+/**
+ * Run a gitflic command and return {stdout, stderr, code}.
+ */
+export function runGitflic(args, { env = {}, cwd, timeoutMs = 60_000 } = {}) {
+  return new Promise((resolveP, rejectP) => {
+    const proc = spawn(process.execPath, [CLI_ENTRY, ...args], {
+      env: { ...process.env, ...env },
+      cwd,
+      timeout: timeoutMs,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (d) => (stdout += d.toString()));
+    proc.stderr.on("data", (d) => (stderr += d.toString()));
+    proc.on("error", rejectP);
+    proc.on("close", (code) => resolveP({ stdout, stderr, code: code ?? 1 }));
+  });
+}
+
+/**
+ * Run a gitflic command and parse JSON. Falls back to {raw: text} if not JSON.
+ * Throws if exit code != 0.
+ */
+export async function runGitflicJson(args, opts = {}) {
+  const r = await runGitflic([...args, "--format", "json"], opts);
+  if (r.code !== 0) {
+    throw new GitflicError(r.stderr.trim() || r.stdout.trim(), r.code);
+  }
+  try {
+    return JSON.parse(r.stdout);
+  } catch {
+    return { raw: r.stdout };
+  }
+}
+
+/**
+ * Run a gitflic command expecting pretty text output. Returns trimmed stdout.
+ * Throws if exit code != 0.
+ */
+export async function runGitflicText(args, opts = {}) {
+  const r = await runGitflic([...args, "--format", "pretty"], opts);
+  if (r.code !== 0) {
+    throw new GitflicError(r.stderr.trim() || r.stdout.trim(), r.code);
+  }
+  return r.stdout;
+}
+
+export class GitflicError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "GitflicError";
+  }
+}

package/server.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// gitflic MCP server — exposes the gitflic CLI as typed MCP tools.
+// Stdio transport; no HTTP. For Claude Code / Cursor / any MCP host.
+//
+// Usage (no install — via npx):
+//   GITFLIC_TOKEN="..." npx -y gitflic-cli-mcp
+//
+// Or from a source checkout:
+//   cd mcp-server && npm install && GITFLIC_TOKEN="..." node server.mjs
+//
+// Then register with your MCP host, e.g. for Claude Code:
+//   claude mcp add gitflic --env GITFLIC_TOKEN=... -- npx -y gitflic-cli-mcp
+// or add to ~/.claude.json:
+//   { "mcpServers": { "gitflic": { "command": "npx",
+//                                   "args": ["-y", "gitflic-cli-mcp"],
+//                                   "env": { "GITFLIC_TOKEN": "..." } } } }
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { runGitflic, runGitflicJson, GitflicError } from "./runner.mjs";
+import { TOOLS } from "./tools.mjs";
+import { resolveProjectArg } from "./project-resolver.mjs";
+
+const server = new McpServer(
+  {
+    name: "gitflic-cli",
+    version: "0.1.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  },
+);
+
+// Helper: turn a JSON Schema (from our TOOLS list) into a Zod object schema.
+// MCP wants zod-style schemas. We support only the subset we use:
+//   { type: "object", required: [...], properties: { name: { type, description, enum? } } }
+function jsonSchemaToZod(schema) {
+  const props = {};
+  for (const [key, def] of Object.entries(schema.properties || {})) {
+    let zodType;
+    switch (def.type) {
+      case "string":
+        zodType = def.enum ? z.enum(def.enum) : z.string();
+        break;
+      case "number":
+      case "integer":
+        zodType = z.number();
+        break;
+      case "boolean":
+        zodType = z.boolean();
+        break;
+      case "array":
+        zodType = z.array(z.any());
+        break;
+      default:
+        zodType = z.any();
+    }
+    if (def.description) zodType = zodType.describe(def.description);
+    if (!schema.required || !schema.required.includes(key)) zodType = zodType.optional();
+    props[key] = zodType;
+  }
+  return z.object(props);
+}
+
+// Register each tool from TOOLS.
+for (const tool of TOOLS) {
+  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
+  // and Cursor prompt the user for confirmation when destructiveHint=true.
+  const ann = tool.annotations || {};
+  const annotations = {
+    title: ann.title || tool.name,
+    readOnlyHint: ann.readOnlyHint === true,
+    destructiveHint: ann.destructiveHint !== false,  // default true (may modify state)
+    idempotentHint: ann.idempotentHint === true,
+    openWorldHint: ann.openWorldHint !== false,      // default true (talks to GitFlic)
+  };
+  server.tool(
+    tool.name,
+    tool.description,
+    zodInput.shape,
+    annotations,
+    async (args) => {
+      try {
+        // Auto-resolve `project` from env or git remote if not provided.
+        const resolvedArgs = resolveProjectArg(args || {});
+        const cliArgs = tool.handler(resolvedArgs);
+        // All our handlers return either an array (--format json) or
+        // a list ending with --format pretty. We decide based on output
+        // content (JSON parse) or just always try JSON first.
+        let result;
+        try {
+          result = await runGitflicJson(cliArgs);
+        } catch (e) {
+          if (e instanceof GitflicError) {
+            return {
+              isError: true,
+              content: [{ type: "text", text: `gitflic error: ${e.message}` }],
+            };
+          }
+          throw e;
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: `unexpected error: ${err.message || err}` }],
+        };
+      }
+    },
+  );
+}
+
+// Boot.
+const transport = new StdioServerTransport();
+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`,
+);