@gudlab/gud-api-mcp 0.1.2

package/LICENSE

@@ -0,0 +1,31 @@
+Gud API - Proprietary License
+
+Copyright (c) 2024 GudLab. All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary property of GudLab. The Software is licensed, not sold.
+
+PERMITTED USE:
+You may install and use the Software as a VS Code / OpenVSX extension for
+personal or commercial development purposes, subject to the terms of the
+applicable free or paid plan.
+
+RESTRICTIONS:
+You may not, without prior written consent from GudLab:
+- Copy, modify, merge, or create derivative works of the Software
+- Distribute, sublicense, sell, or otherwise transfer the Software
+- Reverse engineer, decompile, or disassemble the Software
+- Remove or alter any proprietary notices or labels
+
+PAID FEATURES:
+Certain features require a valid license key. Use of paid features without
+a valid license is prohibited.
+
+DISCLAIMER:
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+GUDLAB BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM
+THE USE OF THE SOFTWARE.
+
+For licensing inquiries: hello@gudlab.org

package/README.md

@@ -0,0 +1,98 @@
+# @gudlab/gud-api-mcp — Gud API for AI agents
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that lets any
+MCP-capable AI agent — **Claude Code, Cursor, Windsurf, Codex, Cline, Zed**, and
+others — **create, run, and save API requests and collections** as real Gud API
+files your team can open in any VS Code-compatible editor.
+
+When an agent builds an endpoint, it registers the request, runs it, and captures
+the response as an example. The collection is written to your project's
+`.gud-api/` folder — the same files the [Gud API extension](https://marketplace.visualstudio.com/items?itemName=gudlab.gud-api)
+reads. Open your editor and every endpoint the agent built is in your sidebar,
+ready to click and re-run. It's git-committable, so it travels with the PR.
+
+Neither Postman nor Bruno occupies this lane: agent-written, editor-native,
+git-friendly, no cloud account.
+
+## Works with
+
+- **MCP clients** (this server): Claude Code, Cursor, Windsurf, Codex, Cline, Zed,
+  Continue — any tool that speaks the Model Context Protocol.
+- **Editors** (the companion Gud API extension that reads the files): VS Code, plus
+  any VS Code-compatible editor that installs from
+  [Open VSX](https://open-vsx.org/extension/gudlab/gud-api) — Cursor, Windsurf,
+  VSCodium, Antigravity, Trae, and more.
+
+The server itself is editor-agnostic — it just writes files. You don't need the
+extension to use it, but the extension is what makes the collections clickable.
+
+## Install
+
+The server runs via `npx` — no global install needed. It's the same config for
+every MCP client; only the file it lives in differs.
+
+Add this to your client's MCP config (`.mcp.json` for Claude Code, `~/.cursor/mcp.json`
+for Cursor, the Windsurf/Codex/Cline equivalent, etc.):
+
+```json
+{
+  "mcpServers": {
+    "gud-api": {
+      "command": "npx",
+      "args": ["-y", "@gudlab/gud-api-mcp", "--project", "."]
+    }
+  }
+}
+```
+
+`--project .` scopes all reads/writes to the current project's `.gud-api/`
+folder. Pass an absolute path to target a different project.
+
+## What the agent can do
+
+| Tool | Purpose |
+|------|---------|
+| `list_collections` | List collections with request counts and folders |
+| `get_collection` | Full contents of one collection (bodies + example summaries) |
+| `create_collection` | Create a collection in `.gud-api/collections` |
+| `upsert_request` | Create/update a request (matched by name), nest under a folder path |
+| `send_request` | Execute a request, resolve `{{variables}}`, run tests, optionally capture an example |
+| `delete_request` | Remove a saved request |
+| `upsert_environment` | Create/update a named variable set (base_url, tokens), optionally set active |
+| `get_active_environment` | Read active variables — secret-looking values are masked |
+
+## How it fits the Gud API format
+
+Files are written byte-compatible with the extension (v0.5.7+): slug filenames
+(`payments-api.json`), canonical key order, `schemaVersion`, trailing newline.
+The MCP server targets **workspace scope** — files live in your project and are
+never cloud-synced, so agent output stays local and reviewable.
+
+Captured responses are stored as `examples[]` on each request (max 5). The
+extension renders these read-only so you can see exactly what the API returned
+when the agent tested it.
+
+## Security notes
+
+- **`send_request` executes arbitrary HTTP** — no more than the `curl` access an
+  agent already has, but be aware of it.
+- **Secret masking**: `get_active_environment` masks values whose keys look like
+  secrets (`token`, `key`, `secret`, `password`, …). `send_request` still resolves
+  the real values server-side, so the agent can *use* a credential without
+  *reading* it into its context. This is heuristic, not a guarantee — don't put
+  production credentials in an agent-visible environment.
+- **Cookies are in-memory per session** — an agent never inherits your browser
+  session cookies.
+- **Writes are confined to `--project`** — collection/environment names are
+  slugified, so a name can't traverse out of the `.gud-api/` folder.
+
+## Links
+
+- Docs: <https://gudapi-docs.gudlab.org/guide/ai-agents>
+- Gud API extension: [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=gudlab.gud-api) · [Open VSX](https://open-vsx.org/extension/gudlab/gud-api)
+- Issues: <https://github.com/gudlab/gud-api/issues>
+
+## License
+
+Proprietary — see the LICENSE file. Free to install and use; redistribution and
+modification are restricted.

package/dist/server.js

@@ -0,0 +1,989 @@
+#!/usr/bin/env node
+import { createRequire as _cr } from 'module'; const require = _cr(import.meta.url);
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { randomUUID as randomUUID3 } from "crypto";
+import { z } from "zod";
+
+// src/store.ts
+import * as fs from "fs/promises";
+import * as path from "path";
+import { randomUUID } from "crypto";
+var COLLECTION_DIR = ".gud-api/collections";
+var ENV_DIR = ".gud-api/environments";
+var COLLECTION_KEY_ORDER = ["schemaVersion", "id", "name", "variables", "folders", "requests", "createdAt", "updatedAt"];
+var REQUEST_KEY_ORDER = ["id", "name", "method", "url", "headers", "body", "bodyType", "auth", "tests", "preRequest", "extractions", "examples"];
+var FOLDER_KEY_ORDER = ["id", "name", "requests", "folders"];
+var ENV_KEY_ORDER = ["schemaVersion", "id", "name", "variables", "createdAt", "updatedAt"];
+function orderKeys(obj, priority) {
+  const out = {};
+  for (const k of priority)
+    if (obj[k] !== void 0)
+      out[k] = obj[k];
+  for (const k of Object.keys(obj).sort())
+    if (!(k in out) && obj[k] !== void 0)
+      out[k] = obj[k];
+  return out;
+}
+function orderRequest(req) {
+  const { timingHistory: _t, ...rest } = req;
+  return orderKeys(rest, REQUEST_KEY_ORDER);
+}
+function orderFolder(folder) {
+  const ordered = orderKeys(folder, FOLDER_KEY_ORDER);
+  ordered.requests = folder.requests.map(orderRequest);
+  ordered.folders = folder.folders.map(orderFolder);
+  return ordered;
+}
+function serializeCollection(collection) {
+  const { source: _s, ownerId: _o, teamId: _tid, shared: _sh, permission: _p, ...persisted } = collection;
+  const ordered = orderKeys({ schemaVersion: 1, ...persisted }, COLLECTION_KEY_ORDER);
+  ordered.requests = collection.requests.map(orderRequest);
+  ordered.folders = collection.folders.map(orderFolder);
+  return JSON.stringify(ordered, null, 2) + "\n";
+}
+function serializeEnvironment(env) {
+  const ordered = orderKeys({ schemaVersion: 1, ...env }, ENV_KEY_ORDER);
+  return JSON.stringify(ordered, null, 2) + "\n";
+}
+function slugify(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "collection";
+}
+async function fileExists(p) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function normalizeFolders(folders) {
+  if (!folders)
+    return [];
+  for (const f of folders) {
+    if (!Array.isArray(f.folders))
+      f.folders = [];
+    if (!Array.isArray(f.requests))
+      f.requests = [];
+    normalizeFolders(f.folders);
+  }
+  return folders;
+}
+var GudApiStore = class {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+  }
+  /** id → on-disk filename, learned on read so saves land on the same file. */
+  collectionFiles = /* @__PURE__ */ new Map();
+  envFiles = /* @__PURE__ */ new Map();
+  gudApiDir() {
+    return path.join(this.projectRoot, ".gud-api");
+  }
+  colDir() {
+    return path.join(this.projectRoot, COLLECTION_DIR);
+  }
+  envDir() {
+    return path.join(this.projectRoot, ENV_DIR);
+  }
+  async loadCollections() {
+    let entries;
+    try {
+      entries = await fs.readdir(this.colDir());
+    } catch {
+      return [];
+    }
+    const out = [];
+    for (const name of entries) {
+      if (!name.endsWith(".json"))
+        continue;
+      try {
+        const text = await fs.readFile(path.join(this.colDir(), name), "utf-8");
+        const parsed = JSON.parse(text);
+        parsed.folders = normalizeFolders(parsed.folders);
+        if (!Array.isArray(parsed.requests))
+          parsed.requests = [];
+        if (!Array.isArray(parsed.variables))
+          parsed.variables = [];
+        parsed.source = "workspace";
+        this.collectionFiles.set(parsed.id, name);
+        out.push(parsed);
+      } catch {
+      }
+    }
+    return out;
+  }
+  async findCollection(nameOrId) {
+    const all = await this.loadCollections();
+    return all.find((c) => c.id === nameOrId) ?? all.find((c) => c.name === nameOrId);
+  }
+  async resolveCollectionFilename(c) {
+    const registered = this.collectionFiles.get(c.id);
+    if (registered)
+      return registered;
+    const legacy = `${c.id}.json`;
+    if (await fileExists(path.join(this.colDir(), legacy))) {
+      this.collectionFiles.set(c.id, legacy);
+      return legacy;
+    }
+    let candidate = `${slugify(c.name)}.json`;
+    if (await fileExists(path.join(this.colDir(), candidate))) {
+      candidate = `${slugify(c.name)}-${c.id.slice(0, 8)}.json`;
+    }
+    this.collectionFiles.set(c.id, candidate);
+    return candidate;
+  }
+  /**
+   * Write a `.gud-api/README.md` the first time we touch the folder. This is
+   * how a human who has NO Gud API extension installed learns that the files
+   * an agent just created aren't broken — they're collections, and here's how
+   * to view them. It's the durable, self-explanatory fallback: it shows in the
+   * file tree, in git, and any editor renders it. Only written if absent, so it
+   * never clobbers a customized one.
+   */
+  async ensureReadme() {
+    const readmePath = path.join(this.gudApiDir(), "README.md");
+    if (await fileExists(readmePath))
+      return;
+    await fs.mkdir(this.gudApiDir(), { recursive: true });
+    await fs.writeFile(readmePath, GUD_API_README, "utf-8");
+  }
+  async saveCollection(c) {
+    await fs.mkdir(this.colDir(), { recursive: true });
+    await this.ensureReadme();
+    c.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const filename = await this.resolveCollectionFilename(c);
+    await fs.writeFile(path.join(this.colDir(), filename), serializeCollection(c), "utf-8");
+  }
+  async createCollection(name, variables = []) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const c = {
+      schemaVersion: 1,
+      id: randomUUID(),
+      name,
+      folders: [],
+      requests: [],
+      variables,
+      createdAt: now,
+      updatedAt: now,
+      source: "workspace"
+    };
+    await this.saveCollection(c);
+    return c;
+  }
+  async loadEnvironments() {
+    let entries;
+    try {
+      entries = await fs.readdir(this.envDir());
+    } catch {
+      return [];
+    }
+    const out = [];
+    for (const name of entries) {
+      if (!name.endsWith(".json"))
+        continue;
+      try {
+        const text = await fs.readFile(path.join(this.envDir(), name), "utf-8");
+        const parsed = JSON.parse(text);
+        if (!Array.isArray(parsed.variables))
+          parsed.variables = [];
+        this.envFiles.set(parsed.id, name);
+        out.push(parsed);
+      } catch {
+      }
+    }
+    return out;
+  }
+  async resolveEnvFilename(e) {
+    const registered = this.envFiles.get(e.id);
+    if (registered)
+      return registered;
+    const legacy = `${e.id}.json`;
+    if (await fileExists(path.join(this.envDir(), legacy))) {
+      this.envFiles.set(e.id, legacy);
+      return legacy;
+    }
+    let candidate = `${slugify(e.name)}.json`;
+    if (await fileExists(path.join(this.envDir(), candidate))) {
+      candidate = `${slugify(e.name)}-${e.id.slice(0, 8)}.json`;
+    }
+    this.envFiles.set(e.id, candidate);
+    return candidate;
+  }
+  async saveEnvironment(e) {
+    await fs.mkdir(this.envDir(), { recursive: true });
+    await this.ensureReadme();
+    e.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const filename = await this.resolveEnvFilename(e);
+    await fs.writeFile(path.join(this.envDir(), filename), serializeEnvironment(e), "utf-8");
+  }
+  async upsertEnvironment(name, variables) {
+    const all = await this.loadEnvironments();
+    const existing = all.find((e) => e.name === name);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const env = existing ? { ...existing, variables } : { id: randomUUID(), name, variables, createdAt: now, updatedAt: now };
+    await this.saveEnvironment(env);
+    return env;
+  }
+};
+var GUD_API_README = `# Gud API collections
+
+These files were created by an AI agent through the **Gud API MCP server**
+(\`@gudlab/gud-api-mcp\`). They are standard Gud API collections \u2014 plain JSON, safe to
+read and to commit to git. **Nothing is broken** if you don't see a UI yet: you
+just need the Gud API extension to view and run them.
+
+## View & run them
+
+Install the **Gud API** extension in your editor, then open the Gud API view in
+the activity bar:
+
+- **VS Code** \u2014 https://marketplace.visualstudio.com/items?itemName=gudlab.gud-api
+- **Cursor, Windsurf, VSCodium, Antigravity, and other VS Code-compatible
+  editors** \u2014 https://open-vsx.org/extension/gudlab/gud-api (usually the default
+  extension source in those editors)
+
+Once installed, your collections appear in the **Gud API sidebar**. Click any
+request to open it and press **Send** to run it. Responses the agent captured
+show on the request's **Examples** tab.
+
+## Don't want the extension?
+
+These are readable JSON files under \`collections/\` and \`environments/\`. You can
+inspect them directly, or feed a request to any HTTP client \u2014 but the extension
+is what makes them clickable and runnable.
+
+## Learn more
+
+https://gudapi-docs.gudlab.org/guide/ai-agents
+
+_This file was generated automatically and is safe to delete or edit \u2014 it won't
+be recreated unless it's missing._
+`;
+
+// src/tree.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var MAX_EXAMPLES = 5;
+function ensureFolderPath(collection, folderPath) {
+  if (!folderPath || folderPath.length === 0)
+    return null;
+  let list = collection.folders;
+  let current = null;
+  for (const name of folderPath) {
+    let next = list.find((f) => f.name === name);
+    if (!next) {
+      next = { id: randomUUID2(), name, requests: [], folders: [] };
+      list.push(next);
+    }
+    current = next;
+    list = next.folders;
+  }
+  return current;
+}
+function findRequestDeep(collection, idOrName) {
+  const scan = (list) => {
+    const byId = list.find((r) => r.id === idOrName);
+    if (byId)
+      return { request: byId, container: list };
+    const byName = list.find((r) => r.name === idOrName);
+    if (byName)
+      return { request: byName, container: list };
+    return null;
+  };
+  const rootHit = scan(collection.requests);
+  if (rootHit)
+    return rootHit;
+  const walk = (folders) => {
+    for (const f of folders) {
+      const hit = scan(f.requests);
+      if (hit)
+        return hit;
+      const nested = walk(f.folders);
+      if (nested)
+        return nested;
+    }
+    return null;
+  };
+  return walk(collection.folders);
+}
+function upsertRequest(collection, folderPath, incoming) {
+  const folder = ensureFolderPath(collection, folderPath);
+  const container = folder ? folder.requests : collection.requests;
+  const existing = incoming.id && container.find((r) => r.id === incoming.id) || container.find((r) => r.name === incoming.name);
+  if (existing) {
+    const preservedExamples = existing.examples;
+    Object.assign(existing, incoming, { id: existing.id });
+    if (preservedExamples && !incoming.examples)
+      existing.examples = preservedExamples;
+    return { requestId: existing.id, created: false };
+  }
+  const req = { ...incoming, id: incoming.id ?? randomUUID2() };
+  container.push(req);
+  return { requestId: req.id, created: true };
+}
+function deleteRequest(collection, idOrName) {
+  const hit = findRequestDeep(collection, idOrName);
+  if (!hit)
+    return false;
+  const idx = hit.container.indexOf(hit.request);
+  if (idx >= 0) {
+    hit.container.splice(idx, 1);
+    return true;
+  }
+  return false;
+}
+function addExample(request, example) {
+  const list = request.examples ?? [];
+  list.push(example);
+  request.examples = list.slice(-MAX_EXAMPLES);
+}
+function countRequests(collection) {
+  let n = collection.requests.length;
+  const walk = (folders) => {
+    for (const f of folders) {
+      n += f.requests.length;
+      walk(f.folders);
+    }
+  };
+  walk(collection.folders);
+  return n;
+}
+function folderPaths(collection) {
+  const out = [];
+  const walk = (folders, prefix) => {
+    for (const f of folders) {
+      const p = [...prefix, f.name];
+      out.push(p.join(" / "));
+      walk(f.folders, p);
+    }
+  };
+  walk(collection.folders, []);
+  return out;
+}
+
+// src/util.ts
+var SECRET_RE = /(token|key|secret|password|passwd|pwd|auth|bearer|credential|api[-_]?key)/i;
+function isSecretKey(key) {
+  return SECRET_RE.test(key);
+}
+function maskSecrets(vars) {
+  return vars.map((v) => {
+    const masked = isSecretKey(v.key) && v.value.length > 0;
+    return {
+      key: v.key,
+      value: masked ? "\u2022\u2022\u2022\u2022 (set)" : v.value,
+      enabled: v.enabled,
+      masked
+    };
+  });
+}
+function truncateBody(body, cap) {
+  const fullLength = body.length;
+  if (fullLength <= cap)
+    return { body, truncated: false, fullLength };
+  return {
+    body: body.slice(0, cap) + `
+\u2026[truncated ${fullLength - cap} of ${fullLength} chars]`,
+    truncated: true,
+    fullLength
+  };
+}
+
+// src/core/services/httpClient.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+
+// src/core/services/variableResolver.ts
+var VAR_PATTERN = /\{\{([^}]+)\}\}/g;
+var MAX_PASSES = 5;
+function resolveRequest(url, headers, body, collectionVars, envVars, globalVars = []) {
+  const lookup = buildLookup(globalVars, collectionVars, envVars);
+  const replacer = (input) => multiPassResolve(input, lookup);
+  const resolvedHeaders = {};
+  for (const [k, v] of Object.entries(headers)) {
+    resolvedHeaders[replacer(k)] = replacer(v);
+  }
+  return {
+    url: replacer(url),
+    headers: resolvedHeaders,
+    body: replacer(body)
+  };
+}
+function multiPassResolve(input, lookup) {
+  let result = input;
+  for (let pass = 0; pass < MAX_PASSES; pass++) {
+    const next = result.replace(VAR_PATTERN, (match, key) => {
+      const trimmed = key.trim();
+      return lookup.has(trimmed) ? lookup.get(trimmed) : match;
+    });
+    if (next === result)
+      break;
+    result = next;
+  }
+  return result;
+}
+function buildLookup(globalVars, collectionVars, envVars) {
+  const map = /* @__PURE__ */ new Map();
+  for (const v of globalVars) {
+    if (v.enabled && v.key.trim()) {
+      map.set(v.key.trim(), v.value);
+    }
+  }
+  for (const v of collectionVars) {
+    if (v.enabled && v.key.trim()) {
+      map.set(v.key.trim(), v.value);
+    }
+  }
+  for (const v of envVars) {
+    if (v.enabled && v.key.trim()) {
+      map.set(v.key.trim(), v.value);
+    }
+  }
+  return map;
+}
+
+// src/core/services/cookieJar.ts
+var jar = /* @__PURE__ */ new Map();
+function extractDomain(urlStr) {
+  try {
+    return new URL(urlStr).hostname;
+  } catch {
+    return "";
+  }
+}
+function parseCookieString(setCookieStr, requestUrl) {
+  const parts = setCookieStr.split(";").map((s) => s.trim());
+  if (parts.length === 0)
+    return null;
+  const [nameValue, ...attrs] = parts;
+  const eqIdx = nameValue.indexOf("=");
+  if (eqIdx === -1)
+    return null;
+  const name = nameValue.slice(0, eqIdx).trim();
+  const value = nameValue.slice(eqIdx + 1).trim();
+  if (!name)
+    return null;
+  const cookie = {
+    name,
+    value,
+    domain: extractDomain(requestUrl),
+    path: "/",
+    httpOnly: false,
+    secure: false,
+    enabled: true
+  };
+  for (const attr of attrs) {
+    const lower = attr.toLowerCase();
+    if (lower.startsWith("domain=")) {
+      cookie.domain = attr.slice(7).trim().replace(/^\./, "");
+    } else if (lower.startsWith("path=")) {
+      cookie.path = attr.slice(5).trim();
+    } else if (lower.startsWith("expires=")) {
+      cookie.expires = attr.slice(8).trim();
+    } else if (lower === "httponly") {
+      cookie.httpOnly = true;
+    } else if (lower === "secure") {
+      cookie.secure = true;
+    }
+  }
+  return cookie;
+}
+function capture(rawSetCookies, requestUrl) {
+  for (const raw of rawSetCookies) {
+    const cookie = parseCookieString(raw, requestUrl);
+    if (!cookie)
+      continue;
+    const domain = cookie.domain;
+    const existing = jar.get(domain) ?? [];
+    const idx = existing.findIndex((c) => c.name === cookie.name && c.path === cookie.path);
+    if (idx >= 0) {
+      existing[idx] = cookie;
+    } else {
+      existing.push(cookie);
+    }
+    jar.set(domain, existing);
+  }
+}
+function getCookieHeader(requestUrl) {
+  const domain = extractDomain(requestUrl);
+  if (!domain)
+    return null;
+  const pairs = [];
+  for (const [cookieDomain, cookies] of jar) {
+    if (domain === cookieDomain || domain.endsWith("." + cookieDomain)) {
+      for (const c of cookies) {
+        if (!c.enabled)
+          continue;
+        if (c.expires && new Date(c.expires).getTime() < Date.now())
+          continue;
+        pairs.push(`${c.name}=${c.value}`);
+      }
+    }
+  }
+  return pairs.length > 0 ? pairs.join("; ") : null;
+}
+
+// src/core/services/httpClient.ts
+async function execute(request, collectionVars = [], envVars = [], multipartFields, globalVars = []) {
+  const resolved = resolveRequest(
+    request.url,
+    request.headers,
+    request.body,
+    collectionVars,
+    envVars,
+    globalVars
+  );
+  const init = {
+    method: request.method,
+    headers: { ...resolved.headers }
+  };
+  const cookieHeader = getCookieHeader(resolved.url);
+  if (cookieHeader) {
+    init.headers["Cookie"] = cookieHeader;
+  }
+  if (request.method !== "GET" && request.method !== "HEAD") {
+    if (multipartFields && multipartFields.length > 0) {
+      const formData = new FormData();
+      for (const field of multipartFields) {
+        if (!field.key.trim())
+          continue;
+        if (field.type === "file" && field.value) {
+          try {
+            const buffer = fs2.readFileSync(field.value);
+            const blob = new Blob([buffer]);
+            const fileName = field.fileName || path2.basename(field.value);
+            formData.append(field.key.trim(), blob, fileName);
+          } catch {
+          }
+        } else {
+          formData.append(field.key.trim(), field.value);
+        }
+      }
+      init.body = formData;
+      delete init.headers["Content-Type"];
+    } else if (resolved.body) {
+      init.body = resolved.body;
+    }
+  }
+  const start = performance.now();
+  try {
+    const res = await fetch(resolved.url, init);
+    const body = await res.text();
+    const timeMs = Math.round(performance.now() - start);
+    const headers = {};
+    res.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+    try {
+      const setCookies = res.headers.getSetCookie?.() ?? [];
+      if (setCookies.length > 0) {
+        capture(setCookies, resolved.url);
+      }
+    } catch {
+    }
+    return {
+      status: res.status,
+      statusText: res.statusText,
+      headers,
+      body,
+      timeMs,
+      size: new TextEncoder().encode(body).byteLength,
+      resolvedUrl: resolved.url
+    };
+  } catch (err) {
+    const timeMs = Math.round(performance.now() - start);
+    const message = err instanceof Error ? err.message : "Unknown error";
+    return {
+      status: 0,
+      statusText: "Error",
+      headers: {},
+      body: message,
+      timeMs,
+      size: 0,
+      resolvedUrl: resolved.url
+    };
+  }
+}
+
+// src/core/services/jsonPath.ts
+function evaluateJsonPath(body, path3) {
+  let obj;
+  try {
+    obj = JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+  const segments = [];
+  for (const part of path3.split(".")) {
+    const bracketMatch = part.match(/^([^[]+)(?:\[(\d+)\])?$/);
+    if (bracketMatch) {
+      if (bracketMatch[1])
+        segments.push(bracketMatch[1]);
+      if (bracketMatch[2] !== void 0)
+        segments.push(bracketMatch[2]);
+    } else {
+      segments.push(part);
+    }
+  }
+  let current = obj;
+  for (const seg of segments) {
+    if (current === null || current === void 0)
+      return void 0;
+    if (typeof current !== "object")
+      return void 0;
+    current = current[seg];
+  }
+  if (current === void 0 || current === null)
+    return void 0;
+  if (typeof current === "object")
+    return JSON.stringify(current);
+  return String(current);
+}
+
+// src/core/services/testRunner.ts
+function getActualValue(response, assertion) {
+  switch (assertion.source) {
+    case "status":
+      return response.status.toString();
+    case "time":
+      return response.timeMs.toString();
+    case "body":
+      return response.body;
+    case "header":
+      return assertion.property ? response.headers[assertion.property.toLowerCase()] : void 0;
+    case "jsonpath":
+      return assertion.property ? evaluateJsonPath(response.body, assertion.property) : void 0;
+    default:
+      return void 0;
+  }
+}
+function evaluateOperator(actual, operator, expected) {
+  if (operator === "exists") {
+    return actual !== void 0 && actual !== null && actual !== "";
+  }
+  if (actual === void 0 || actual === null)
+    return false;
+  switch (operator) {
+    case "eq":
+      return actual === expected;
+    case "neq":
+      return actual !== expected;
+    case "contains":
+      return actual.includes(expected);
+    case "not_contains":
+      return !actual.includes(expected);
+    case "gt": {
+      const a = parseFloat(actual);
+      const b = parseFloat(expected);
+      return !isNaN(a) && !isNaN(b) && a > b;
+    }
+    case "lt": {
+      const a = parseFloat(actual);
+      const b = parseFloat(expected);
+      return !isNaN(a) && !isNaN(b) && a < b;
+    }
+    default:
+      return false;
+  }
+}
+function describeResult(assertion, actual, passed) {
+  const source = assertion.source === "jsonpath" || assertion.source === "header" ? `${assertion.source}(${assertion.property})` : assertion.source;
+  if (assertion.operator === "exists") {
+    return passed ? `${source} exists` : `${source} does not exist`;
+  }
+  const truncated = actual !== void 0 && actual.length > 60 ? actual.slice(0, 60) + "..." : actual ?? "undefined";
+  return passed ? `${source} ${assertion.operator} "${assertion.expected}"` : `Expected ${source} ${assertion.operator} "${assertion.expected}", got "${truncated}"`;
+}
+function runAssertions(response, assertions) {
+  return assertions.map((assertion) => {
+    const actual = getActualValue(response, assertion);
+    const passed = evaluateOperator(actual, assertion.operator, assertion.expected);
+    return {
+      assertionId: assertion.id,
+      passed,
+      actual: actual ?? "",
+      message: describeResult(assertion, actual, passed)
+    };
+  });
+}
+
+// src/server.ts
+function argValue(flag, fallback) {
+  const i = process.argv.indexOf(flag);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+var PROJECT_ROOT = argValue("--project", process.cwd());
+var BODY_CAP = parseInt(argValue("--body-cap", "4096"), 10) || 4096;
+var store = new GudApiStore(PROJECT_ROOT);
+var activeEnvName = null;
+var requestShape = z.object({
+  name: z.string().describe("Human-readable request name; also the upsert match key within a collection."),
+  method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]),
+  url: z.string().describe("Request URL. May contain {{variable}} placeholders resolved from the environment and collection."),
+  headers: z.record(z.string()).optional(),
+  body: z.string().optional(),
+  bodyType: z.enum(["json", "form", "text", "graphql", "multipart", "none"]).optional(),
+  auth: z.object({
+    type: z.enum(["none", "bearer", "basic", "apikey"]),
+    bearer: z.object({ token: z.string() }).optional(),
+    basic: z.object({ username: z.string(), password: z.string() }).optional(),
+    apikey: z.object({ key: z.string(), value: z.string(), addTo: z.enum(["header", "query"]) }).optional()
+  }).optional(),
+  tests: z.array(
+    z.object({
+      id: z.string().optional(),
+      source: z.enum(["status", "time", "body", "header", "jsonpath"]),
+      property: z.string().optional(),
+      operator: z.enum(["eq", "neq", "contains", "not_contains", "gt", "lt", "exists"]),
+      expected: z.string()
+    })
+  ).optional().describe("Assertions run automatically after send_request.")
+});
+function toSavedRequest(input) {
+  return {
+    id: randomUUID3(),
+    name: input.name,
+    method: input.method,
+    url: input.url,
+    headers: input.headers ?? {},
+    body: input.body ?? "",
+    bodyType: input.bodyType ?? "none",
+    auth: input.auth ?? { type: "none" },
+    tests: input.tests?.map((t) => ({ ...t, id: t.id ?? randomUUID3() }))
+  };
+}
+function ok(obj) {
+  return { content: [{ type: "text", text: JSON.stringify(obj, null, 2) }] };
+}
+function fail(message) {
+  return { content: [{ type: "text", text: JSON.stringify({ error: message }, null, 2) }], isError: true };
+}
+var VERSION = true ? "0.1.2" : "0.0.0-dev";
+var server = new McpServer({ name: "gud-api", version: VERSION });
+server.tool(
+  "list_collections",
+  "List all Gud API collections in the project's .gud-api folder, with request counts and folder names.",
+  {},
+  async () => {
+    const cols = await store.loadCollections();
+    return ok(
+      cols.map((c) => ({
+        id: c.id,
+        name: c.name,
+        requestCount: countRequests(c),
+        folders: folderPaths(c),
+        variables: c.variables.map((v) => v.key)
+      }))
+    );
+  }
+);
+server.tool(
+  "get_collection",
+  "Get the full contents of one collection: folders, requests (with method/url/headers/body), and variables. Example response bodies are summarized.",
+  { collection: z.string().describe("Collection id or name.") },
+  async ({ collection }) => {
+    const c = await store.findCollection(collection);
+    if (!c)
+      return fail(`Collection not found: ${collection}`);
+    const summarizeReq = (r) => ({
+      id: r.id,
+      name: r.name,
+      method: r.method,
+      url: r.url,
+      headers: r.headers,
+      bodyType: r.bodyType,
+      hasBody: !!r.body,
+      hasTests: !!r.tests?.length,
+      examples: (r.examples ?? []).map((e) => ({ label: e.label, status: e.status, capturedAt: e.capturedAt }))
+    });
+    const summarizeFolder = (f) => ({
+      name: f.name,
+      requests: f.requests.map(summarizeReq),
+      folders: f.folders.map(summarizeFolder)
+    });
+    return ok({
+      id: c.id,
+      name: c.name,
+      variables: c.variables,
+      requests: c.requests.map(summarizeReq),
+      folders: c.folders.map(summarizeFolder)
+    });
+  }
+);
+server.tool(
+  "create_collection",
+  "Create a new collection in the project (.gud-api/collections). Returns its id.",
+  {
+    name: z.string(),
+    variables: z.array(z.object({ key: z.string(), value: z.string(), enabled: z.boolean().optional() })).optional()
+  },
+  async ({ name, variables }) => {
+    const vars = (variables ?? []).map((v) => ({ key: v.key, value: v.value, enabled: v.enabled ?? true }));
+    const c = await store.createCollection(name, vars);
+    return ok({
+      id: c.id,
+      name: c.name,
+      path: `.gud-api/collections`,
+      // Surfaced so the agent can tell the human how to view the result — they
+      // may not have the Gud API extension yet and would otherwise think nothing
+      // happened. A .gud-api/README.md with the same guidance is also written.
+      viewHint: "To view and run this, install the Gud API extension (VS Code Marketplace, or Open VSX for Cursor/Windsurf/VSCodium). See .gud-api/README.md."
+    });
+  }
+);
+server.tool(
+  "upsert_request",
+  "Create or update a request inside a collection (matched by name). The collection is created if it doesn't exist. Optionally nest it under a folder path.",
+  {
+    collection: z.string().describe("Collection name or id. Created if missing."),
+    folderPath: z.array(z.string()).optional().describe('Folder path, e.g. ["Auth","JWT"]. Created as needed.'),
+    request: requestShape
+  },
+  async ({ collection, folderPath, request }) => {
+    let c = await store.findCollection(collection);
+    if (!c)
+      c = await store.createCollection(collection);
+    const { requestId, created } = upsertRequest(c, folderPath ?? [], toSavedRequest(request));
+    await store.saveCollection(c);
+    return ok({ requestId, created, collection: c.name });
+  }
+);
+server.tool(
+  "send_request",
+  "Execute a request and return status, timing, headers, and a (truncated) body. Resolves {{variables}} from the active environment and the request's collection. Optionally capture the response as a saved example.",
+  {
+    collection: z.string().optional().describe("Collection name/id when sending a saved request."),
+    requestName: z.string().optional().describe("Saved request name or id within the collection."),
+    request: requestShape.optional().describe("Inline request definition (alternative to collection+requestName)."),
+    saveExample: z.union([z.boolean(), z.string()]).optional().describe("When set, capture the response as an example on the saved request. Pass a string to label it.")
+  },
+  async ({ collection, requestName, request, saveExample }) => {
+    let def;
+    let col;
+    let saved;
+    if (request) {
+      def = toSavedRequest(request);
+    } else if (collection && requestName) {
+      col = await store.findCollection(collection);
+      if (!col)
+        return fail(`Collection not found: ${collection}`);
+      const hit = findRequestDeep(col, requestName);
+      if (!hit)
+        return fail(`Request not found in ${collection}: ${requestName}`);
+      def = hit.request;
+      saved = hit.request;
+    } else {
+      return fail("Provide either `request`, or `collection` + `requestName`.");
+    }
+    const collectionVars = col?.variables ?? [];
+    const envs = await store.loadEnvironments();
+    const activeEnv = activeEnvName ? envs.find((e) => e.name === activeEnvName) : void 0;
+    const envVars = activeEnv?.variables ?? [];
+    let multipart;
+    if (def.bodyType === "multipart" && def.body) {
+      try {
+        multipart = JSON.parse(def.body);
+      } catch {
+      }
+    }
+    let response;
+    try {
+      response = await execute(def, collectionVars, envVars, multipart, []);
+    } catch (err) {
+      return fail(`Request failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const testResults = def.tests?.length ? runAssertions(response, def.tests) : void 0;
+    const { body, truncated, fullLength } = truncateBody(response.body, BODY_CAP);
+    if (saveExample && saved && col) {
+      addExample(saved, {
+        label: typeof saveExample === "string" ? saveExample : `${response.status} ${response.statusText}`.trim(),
+        status: response.status,
+        headers: response.headers,
+        body: response.body.slice(0, 16 * 1024),
+        timeMs: response.timeMs,
+        capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      await store.saveCollection(col);
+    }
+    return ok({
+      status: response.status,
+      statusText: response.statusText,
+      timeMs: response.timeMs,
+      size: response.size,
+      resolvedUrl: response.resolvedUrl,
+      headers: response.headers,
+      body,
+      bodyTruncated: truncated,
+      bodyFullLength: fullLength,
+      testResults: testResults?.map((t) => ({ passed: t.passed, message: t.message })),
+      exampleSaved: !!(saveExample && saved)
+    });
+  }
+);
+server.tool(
+  "delete_request",
+  "Delete a saved request from a collection by id or name.",
+  { collection: z.string(), request: z.string().describe("Request id or name.") },
+  async ({ collection, request }) => {
+    const c = await store.findCollection(collection);
+    if (!c)
+      return fail(`Collection not found: ${collection}`);
+    const removed = deleteRequest(c, request);
+    if (!removed)
+      return fail(`Request not found: ${request}`);
+    await store.saveCollection(c);
+    return ok({ deleted: true });
+  }
+);
+server.tool(
+  "upsert_environment",
+  "Create or update an environment (a named set of variables, e.g. base_url and tokens). Matched by name. Optionally set it active for subsequent send_request calls.",
+  {
+    name: z.string(),
+    variables: z.array(z.object({ key: z.string(), value: z.string(), enabled: z.boolean().optional() })),
+    setActive: z.boolean().optional()
+  },
+  async ({ name, variables, setActive }) => {
+    const vars = variables.map((v) => ({ key: v.key, value: v.value, enabled: v.enabled ?? true }));
+    const env = await store.upsertEnvironment(name, vars);
+    if (setActive)
+      activeEnvName = env.name;
+    return ok({ id: env.id, name: env.name, active: activeEnvName === env.name, variableCount: vars.length });
+  }
+);
+server.tool(
+  "get_active_environment",
+  "Return the active environment's variables. Secret-looking values (token/key/secret/password/\u2026) are masked \u2014 send_request still resolves the real values server-side.",
+  {},
+  async () => {
+    if (!activeEnvName)
+      return ok({ active: null, note: "No active environment. Use upsert_environment with setActive: true." });
+    const envs = await store.loadEnvironments();
+    const env = envs.find((e) => e.name === activeEnvName);
+    if (!env)
+      return ok({ active: null, note: `Active environment '${activeEnvName}' no longer exists.` });
+    return ok({ active: env.name, variables: maskSecrets(env.variables) });
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write(`[gud-api mcp] ready \u2014 project: ${PROJECT_ROOT}
+`);
+  if (process.stdin.isTTY) {
+    process.stderr.write(
+      `[gud-api mcp] This is a Model Context Protocol server, not an interactive CLI.
+[gud-api mcp] It is now waiting for an MCP client to talk to it over stdin \u2014 nothing is broken.
+[gud-api mcp] Configure it in Claude Code / Cursor / Windsurf instead of running it by hand:
+[gud-api mcp]   { "mcpServers": { "gud-api": { "command": "npx", "args": ["-y", "@gudlab/gud-api-mcp", "--project", "."] } } }
+[gud-api mcp] Docs: https://gudapi-docs.gudlab.org/guide/ai-agents  \xB7  Press Ctrl+C to exit.
+`
+    );
+  }
+}
+main().catch((err) => {
+  process.stderr.write(`[gud-api mcp] fatal: ${err instanceof Error ? err.stack : String(err)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@gudlab/gud-api-mcp",
+  "version": "0.1.2",
+  "mcpName": "io.github.gudlab/gud-api-mcp",
+  "description": "Model Context Protocol server for Gud API — let AI coding agents (Claude Code, Cursor, Windsurf, Codex, Cline…) create, run, and save API requests and collections your team can open in any VS Code-compatible editor.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "publisher": "gudlab",
+  "keywords": ["mcp", "model-context-protocol", "api", "rest", "graphql", "api-client", "gud-api", "ai-agent", "claude-code", "cursor", "windsurf", "codex", "cline"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gudlab/gud-api"
+  },
+  "bin": {
+    "gud-api-mcp": "./dist/server.js"
+  },
+  "files": ["dist"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "start": "node dist/server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "esbuild": "^0.20.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.3"
+  }
+}