claudepack-connector 0.4.1

package/README.md

@@ -0,0 +1,40 @@
+# ClaudePack MCP connector
+
+The desktop bridge that lets **Claude install ClaudePack skills for itself**. Connect it
+to Claude Code, then just ask in plain language:
+
+> "find a skill for writing commit messages and install it"
+
+Claude searches the catalog, picks the match, and writes the files into
+`~/.claude/skills/` — no manual file placing.
+
+## What it exposes (MCP tools)
+
+| Tool | What it does |
+|---|---|
+| `search_skills(query)` | Search the catalog by keyword (id/title/summary/tags). |
+| `install_skill(id)` | Copy a skill's files into `~/.claude/skills/<id>/`. |
+| `list_installed_skills()` | List what's already installed. |
+
+## Connect it to Claude Code
+
+Already wired for this project via `../.mcp.json`. To use it from **any** directory,
+register it globally:
+
+```
+claude mcp add claudepack -- node "C:\Users\SUMIT\Downloads\vs\claudepack-mcp\server.mjs"
+```
+
+Then in a new session: `"search the catalog for a code review skill and install it"`.
+After install, **start a new Claude Code session** so the skill loads.
+
+## How it works
+
+- Dependency-free Node MCP server (newline-delimited JSON-RPC 2.0 over stdio).
+- Catalog lives in `catalog/` — `catalog.json` (metadata) + `skills/<id>/` (the real files).
+- Installs are real file copies. Override the target with `CLAUDEPACK_SKILLS_DIR` (used by tests).
+
+## Roadmap (incremental realism)
+
+`local file catalog (now)` → `fetch from the ClaudePack registry` → `creator uploads + paid items`.
+The tool surface (`search` → `install`) stays the same as the backend gets real.

package/catalog/catalog.json

@@ -0,0 +1,8 @@
+[
+  { "id": "commit-message", "type": "skill", "version": "1.0.0", "title": "Commit Message Writer", "summary": "Writes clean Conventional Commits messages from a staged diff.", "description": "Generates a conventional commit message from your staged git changes, with an optional body explaining what changed and why.", "tags": ["git", "commits", "conventional-commits", "message", "workflow"], "files": ["SKILL.md"] },
+  { "id": "code-reviewer", "type": "skill", "version": "1.0.0", "title": "Code Reviewer", "summary": "Reviews a diff for correctness bugs, security issues and simplifications.", "description": "Reviews your code changes for logic bugs, security vulnerabilities, and simplifications, ranked by severity.", "tags": ["review", "quality", "security", "bugs", "git"], "files": ["SKILL.md"] },
+  { "id": "explain-error", "type": "skill", "version": "1.0.0", "title": "Error Explainer", "summary": "Explains a stack trace or error message and suggests concrete fixes.", "description": "Takes an error or stack trace and explains the root cause in plain language, then suggests the most likely fix.", "tags": ["debugging", "errors", "stacktrace", "fix", "exception"], "files": ["SKILL.md"] },
+  { "id": "pr-description", "type": "skill", "version": "1.0.0", "title": "PR Description Writer", "summary": "Drafts a clear pull request description from the branch diff.", "description": "Writes a pull request description (title, what & why, changes, testing) from your branch's diff and commit log.", "tags": ["git", "pull-request", "pr", "docs", "workflow"], "files": ["SKILL.md"] },
+  { "id": "test-writer", "type": "agent", "version": "1.0.0", "title": "Test Writer (subagent)", "summary": "A subagent that writes unit tests for a function, file or module.", "description": "A subagent that reads target code, detects your test framework, and writes focused unit tests covering happy paths, edge cases and errors.", "tags": ["testing", "unit-tests", "tdd", "subagent", "quality"], "files": ["test-writer.md"] },
+  { "id": "changelog", "type": "command", "version": "1.0.0", "title": "/changelog", "summary": "Slash command that turns recent commits into a changelog.", "description": "A slash command that reads recent git commits and writes a grouped, human-readable changelog entry.", "tags": ["git", "changelog", "release", "docs", "command"], "files": ["changelog.md"] }
+]

package/catalog/items/changelog/changelog.md

@@ -0,0 +1,10 @@
+---
+description: Summarize recent commits into a human-readable changelog entry.
+---
+
+Generate a changelog from recent git history.
+
+1. Run `git log --oneline -n 30`, or since the last tag: `git log $(git describe --tags --abbrev=0)..HEAD --oneline`.
+2. Group commits into **Added**, **Changed**, **Fixed**, **Removed**. Drop noise (merge commits, "wip", formatting-only churn).
+3. Rewrite each entry as a user-facing sentence, not the raw commit subject.
+4. Output markdown under a `## <version> — <date>` heading.

package/catalog/items/code-reviewer/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: code-reviewer
+description: Use when the user wants their changes reviewed. Reviews a diff for correctness bugs, security issues, and simplifications.
+---
+
+# Code Reviewer
+
+When asked to review code:
+
+1. Get the diff: `git diff` (or `git diff <base>...HEAD` for a whole branch).
+2. Review only the changed lines, in three passes:
+   - **Correctness** — logic errors, off-by-one, null/undefined, error handling, race conditions.
+   - **Security** — injection, missing authorization, leaked secrets, unsafe input, XSS.
+   - **Simplification** — duplication, dead code, clearer equivalents.
+3. Report findings as a list: `file:line — severity — what's wrong — suggested fix`.
+4. Lead with the highest-severity issues. If nothing is wrong, say so plainly — don't invent nits.
+
+Verify every claim against the actual code; never flag a line you haven't read.

package/catalog/items/commit-message/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: commit-message
+description: Use when the user wants a commit message for their changes. Generates a Conventional Commits message from the staged diff.
+---
+
+# Commit Message Writer
+
+When the user asks for a commit message:
+
+1. Run `git diff --staged` to read the staged changes. If nothing is staged, run `git diff` and note you are describing unstaged changes.
+2. Write a single Conventional Commits subject line: `<type>(<scope>): <description>`, ≤72 chars, imperative mood.
+   - types: feat, fix, docs, style, refactor, perf, test, build, ci, chore
+3. For a non-trivial change, add a body: a blank line, then 1–3 bullets on what changed and why (not how).
+4. Output ONLY the commit message in a code block — nothing else.
+
+Describe what the diff actually does; never invent changes that aren't there.

package/catalog/items/explain-error/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: explain-error
+description: Use when the user pastes an error message or stack trace. Explains the root cause in plain language and suggests concrete fixes.
+---
+
+# Error Explainer
+
+When given an error or stack trace:
+
+1. Identify the error type and the exact frame that triggered it — the first frame in the user's own code, not library internals.
+2. Explain the root cause in one or two plain sentences: what actually went wrong, not just a restatement of the message.
+3. Give the most likely fix as a concrete code change. If several causes are plausible, list them ranked by likelihood.
+4. If you need a file's contents to be sure, open it rather than guessing.
+
+Point at the real line. Don't theorize about what "should" work.

package/catalog/items/pr-description/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: pr-description
+description: Use when the user wants a pull request description. Drafts a clear PR summary from the branch diff.
+---
+
+# PR Description Writer
+
+When asked for a PR description:
+
+1. Get the branch diff vs the base: `git diff <base>...HEAD` and `git log <base>..HEAD --oneline`.
+2. Draft a description with:
+   - **Title** — one line, imperative.
+   - **What & why** — 2–4 sentences on the change and its motivation.
+   - **Changes** — a bullet list of the notable edits.
+   - **Testing** — how it was verified (or "not yet tested" if unknown).
+3. Output as markdown in a code block.
+
+Summarize what the diff actually contains — don't claim tests or behaviour you can't see.

package/catalog/items/test-writer/test-writer.md

@@ -0,0 +1,16 @@
+---
+name: test-writer
+description: Use to write unit tests for a function, module, or file. Reads the target code and produces focused tests covering main paths and edge cases.
+tools: Read, Grep, Glob, Edit, Bash
+---
+
+You are a focused test-writing subagent.
+
+When invoked:
+
+1. Read the target file(s) the user named. If they named a function, grep for it and read its definition plus a couple of call sites.
+2. Detect the test framework already in the project (jest / vitest / pytest / go test / …) from config and existing tests. Match it exactly — same imports, file naming, assertion style.
+3. Write tests covering: the happy path, boundary values, empty/null inputs, and error cases. Name each test descriptively for the behaviour it pins.
+4. Place tests where the project's convention puts them. If a test command exists, run the suite and report pass/fail.
+
+Never invent behaviour — test what the code actually does. If the code looks buggy, flag it; don't write a test that locks in the bug.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "claudepack-connector",
+  "version": "0.4.1",
+  "description": "Connect Claude to ClaudePack - search and install skills, subagents, commands and more by description. Catalog fetched live; no server, no cost.",
+  "type": "module",
+  "bin": {
+    "claudepack-connector": "server.mjs"
+  },
+  "files": [
+    "server.mjs",
+    "catalog"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "mcp",
+    "skills",
+    "marketplace"
+  ]
+}

package/server.mjs

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+// ClaudePack MCP connector. Claude searches the ClaudePack catalog by a natural-
+// language description and installs items (skills, subagents, commands, output-
+// styles, plugins) into ~/.claude/ for itself.
+//
+// AUTO-UPDATE + SCALE + ZERO COST. Three data modes, tried in order:
+//   1. API mode (CLAUDEPACK_API_URL): search hits /api/search and install hits
+//      /api/item/<id> - only results are transferred, so it scales to tens of
+//      thousands of items. Runs on free serverless (Vercel/Cloudflare free tier).
+//   2. Static mode (CLAUDEPACK_CATALOG_URL): fetch catalog.json + files from a
+//      free static host (GitHub raw / Pages). Fine up to a few thousand items.
+//   3. Bundled snapshot: offline fallback shipped with the package.
+// Files always live on static hosting; only search/lookup needs the API at scale.
+// Dependency-free: Node 18+ global fetch, JSON-RPC 2.0 over stdio.
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { writeFile, mkdir } from "node:fs/promises";
+import { join, dirname, basename, resolve, relative, isAbsolute, sep } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_DIR = join(HERE, "catalog");
+const SERVER = { name: "claudepack", version: "0.4.1" };
+const PROTOCOL_FALLBACK = "2025-06-18";
+
+// ── path-safety ────────────────────────────────────────────────────
+// The connector writes files to the user's disk based on data fetched from a
+// remote catalog. Treat every id and file path from the catalog as untrusted:
+// a malicious or compromised entry must never escape ~/.claude via "..",
+// absolute paths, or drive letters. These guards run before any read/write.
+const SAFE_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+function assertSafeId(id) {
+  if (typeof id !== "string" || !SAFE_ID.test(id) || id.includes("..")) {
+    throw new Error(`Unsafe item id: ${JSON.stringify(id)}`);
+  }
+  return id;
+}
+
+// Validate a catalog-relative file path (may contain forward-slash subdirs like
+// "references/x.md"). Reject absolute paths, backslashes, drive letters, and any
+// ".." segment. Returns the normalized forward-slash relative path.
+function assertSafeRel(rel) {
+  if (typeof rel !== "string" || rel.length === 0) {
+    throw new Error(`Unsafe file path: ${JSON.stringify(rel)}`);
+  }
+  if (rel.includes("\\") || isAbsolute(rel) || /^[a-zA-Z]:/.test(rel)) {
+    throw new Error(`Unsafe file path (absolute/backslash): ${JSON.stringify(rel)}`);
+  }
+  const parts = rel.split("/").filter((p) => p.length && p !== ".");
+  if (parts.some((p) => p === "..")) {
+    throw new Error(`Unsafe file path (traversal): ${JSON.stringify(rel)}`);
+  }
+  if (!parts.length) throw new Error(`Empty file path: ${JSON.stringify(rel)}`);
+  return parts.join("/");
+}
+
+// Final defense: ensure a resolved destination never leaves its base directory.
+function assertWithin(baseDir, dest) {
+  const rel = relative(resolve(baseDir), resolve(dest));
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel) || rel.split(sep).includes("..")) {
+    throw new Error(`Refusing to write outside ${baseDir}: ${dest}`);
+  }
+  return dest;
+}
+
+const clean = (u) => (u || "").replace(/\/+$/, "");
+// API origin for scalable search/lookup (optional). When set it wins.
+const API_URL = clean(process.env.CLAUDEPACK_API_URL);
+// Static catalog base (pure-static deployments / small catalogs).
+const CATALOG_URL = clean(process.env.CLAUDEPACK_CATALOG_URL
+  || "https://raw.githubusercontent.com/plox-sumit/claudepack-catalog/main");
+// Where item files live. In API mode they sit under <api>/catalog; else CATALOG_URL.
+const FILES_BASE = API_URL ? `${API_URL}/catalog` : CATALOG_URL;
+
+const claudeDir = () => process.env.CLAUDEPACK_CLAUDE_DIR || join(homedir(), ".claude");
+
+const TARGETS = {
+  skill:   { dir: "skills",        layout: "folder", label: "skill" },
+  agent:   { dir: "agents",        layout: "flat",   label: "subagent" },
+  command: { dir: "commands",      layout: "flat",   label: "command" },
+  style:   { dir: "output-styles", layout: "flat",   label: "output style" },
+  plugin:  { dir: "plugins",       layout: "folder", label: "plugin" },
+};
+
+const log = (...a) => process.stderr.write("[claudepack-mcp] " + a.join(" ") + "\n");
+
+async function fetchText(url) {
+  const res = await fetch(url, { headers: { "user-agent": "claudepack-connector" } });
+  if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+  return res.text();
+}
+
+// Full catalog (static mode) with bundled fallback. Used when there's no API and
+// for local ranking.
+function rankLocal(items, query, limit = 10) {
+  const q = String(query || "").toLowerCase().trim();
+  if (!q) return items.slice(0, limit);
+  const terms = q.split(/\s+/).filter(Boolean);
+  return items
+    .map((it) => {
+      const hay = [it.id, it.title, it.summary, it.description, (it.tags || []).join(" "), it.type]
+        .filter(Boolean).join(" ").toLowerCase();
+      let score = 0;
+      for (const t of terms) if (hay.includes(t)) score++;
+      return { it, score };
+    })
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map((s) => s.it);
+}
+
+async function loadFullCatalog() {
+  try {
+    return { items: JSON.parse(await fetchText(`${CATALOG_URL}/catalog.json`)), source: CATALOG_URL };
+  } catch (e) {
+    log("static catalog unavailable, using bundled snapshot:", e.message);
+    try {
+      return { items: JSON.parse(readFileSync(join(BUNDLED_DIR, "catalog.json"), "utf8")), source: "bundled" };
+    } catch {
+      return { items: [], source: "none" };
+    }
+  }
+}
+
+// search -> top matches. API mode transfers only results; otherwise full catalog.
+async function doSearch(query, limit = 10) {
+  if (API_URL) {
+    try {
+      const url = `${API_URL}/api/search?q=${encodeURIComponent(query || "")}&limit=${limit}`;
+      return { items: JSON.parse(await fetchText(url)), source: `${API_URL}/api/search` };
+    } catch (e) {
+      log("api search failed, falling back to full catalog:", e.message);
+    }
+  }
+  const { items, source } = await loadFullCatalog();
+  return { items: rankLocal(items, query, limit), source };
+}
+
+// resolve one item's manifest. API mode = O(1); else scan full catalog.
+async function resolveItem(id) {
+  if (API_URL) {
+    try {
+      const item = JSON.parse(await fetchText(`${API_URL}/api/item/${encodeURIComponent(id)}`));
+      if (item && item.id) return { item, mode: "remote" };
+    } catch (e) {
+      log("api item lookup failed, falling back:", e.message);
+    }
+  }
+  const { items, source } = await loadFullCatalog();
+  return { item: items.find((i) => i.id === id), mode: source === "bundled" ? "bundled" : "remote" };
+}
+
+async function getFile(mode, id, rel) {
+  assertSafeId(id);
+  const safeRel = assertSafeRel(rel);
+  if (mode !== "bundled") {
+    // Build the URL from validated, per-segment-encoded parts (keep slashes).
+    const encoded = safeRel.split("/").map(encodeURIComponent).join("/");
+    try { return await fetchText(`${FILES_BASE}/items/${encodeURIComponent(id)}/${encoded}`); }
+    catch (e) { log(`remote file miss (${id}/${safeRel}):`, e.message); }
+  }
+  const dest = assertWithin(join(BUNDLED_DIR, "items"), join(BUNDLED_DIR, "items", id, safeRel));
+  return readFileSync(dest, "utf8");
+}
+
+async function installItem(id) {
+  try { assertSafeId(id); }
+  catch { return { ok: false, message: `Invalid item id "${id}".` }; }
+
+  const { item, mode } = await resolveItem(id);
+  if (!item) return { ok: false, message: `No item "${id}" in the catalog. Run search_catalog first.` };
+  const target = TARGETS[item.type];
+  if (!target) return { ok: false, message: `Unsupported item type "${item.type}".` };
+  const files = Array.isArray(item.files) ? item.files.filter(Boolean) : [];
+  if (!files.length) return { ok: false, message: `Catalog entry "${id}" lists no files.` };
+
+  const base = join(claudeDir(), target.dir);
+  const folderRoot = join(base, id); // where folder-layout items live
+  const written = [];
+  try {
+    for (const rel of files) {
+      const safeRel = assertSafeRel(rel);
+      const content = await getFile(mode, id, safeRel);
+      const dest =
+        target.layout === "folder"
+          ? assertWithin(folderRoot, join(folderRoot, safeRel))
+          : assertWithin(base, join(base, basename(safeRel)));
+      await mkdir(dirname(dest), { recursive: true });
+      await writeFile(dest, content);
+      written.push(dest);
+    }
+  } catch (e) {
+    return { ok: false, message: `Refused to install "${id}": ${e.message}` };
+  }
+  const installedTo = target.layout === "folder" ? folderRoot : base;
+  return { ok: true, id, kind: target.label, version: item.version, mode, installedTo, files: written };
+}
+
+function listInstalled() {
+  const base = claudeDir();
+  const out = {};
+  for (const t of Object.values(TARGETS)) {
+    const dir = join(base, t.dir);
+    if (!existsSync(dir)) continue;
+    try {
+      const entries = readdirSync(dir).filter((n) => !n.startsWith("."));
+      if (entries.length) out[t.label] = entries;
+    } catch { /* ignore */ }
+  }
+  return out;
+}
+
+const TOOLS = [
+  {
+    name: "search_catalog",
+    description:
+      "Search ClaudePack for installable Claude extensions - skills, subagents, commands, output-styles, plugins - by a natural-language description or keywords. The catalog is fetched live, so newly published and updated items appear automatically. Use whenever the user asks Claude to find or add something from ClaudePack. Returns matches with id, type, title and summary.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "A description of what you want, e.g. 'something that writes my git commit messages' or 'a subagent that writes tests'." },
+        limit: { type: "number", description: "Max results (default 10)." },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "install_item",
+    description:
+      "Install a ClaudePack item (skill / subagent / command / output-style / plugin) into the right ~/.claude/ folder. Always pulls the latest published version. Pass an id from search_catalog.",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string", description: "The item id to install." } },
+      required: ["id"],
+    },
+  },
+  {
+    name: "list_installed",
+    description: "List what's already installed under ~/.claude/ (skills, subagents, commands, styles, plugins).",
+    inputSchema: { type: "object", properties: {} },
+  },
+];
+
+async function callTool(name, args) {
+  if (name === "search_catalog") {
+    const { items, source } = await doSearch(args.query, args.limit);
+    const head = `(catalog source: ${source})`;
+    if (!items.length) return `${head}\nNothing in ClaudePack matched "${args.query}".`;
+    return head + "\n" + items.map((x) =>
+      `* [${x.type}] ${x.id}${x.version ? " v" + x.version : ""} - ${x.title}\n  ${x.summary}\n  tags: ${(x.tags || []).join(", ")}`).join("\n");
+  }
+  if (name === "install_item") {
+    const res = await installItem(args.id);
+    if (!res.ok) return res.message;
+    return `Installed ${res.kind} "${res.id}"${res.version ? " v" + res.version : ""} -> ${res.installedTo}\n` +
+      res.files.map((f) => "  " + f).join("\n") +
+      `\n\nStart a new Claude Code session to load it.`;
+  }
+  if (name === "list_installed") {
+    const m = listInstalled();
+    const lines = Object.entries(m).map(([k, v]) => `${k}: ${v.join(", ")}`);
+    return lines.length ? lines.join("\n") : "Nothing installed yet.";
+  }
+  throw new Error("Unknown tool: " + name);
+}
+
+function send(msg) { process.stdout.write(JSON.stringify(msg) + "\n"); }
+
+async function handle(req) {
+  const { id, method, params } = req;
+  if (method === "initialize") {
+    return { jsonrpc: "2.0", id, result: {
+      protocolVersion: params?.protocolVersion || PROTOCOL_FALLBACK,
+      capabilities: { tools: {} }, serverInfo: SERVER,
+    } };
+  }
+  if (method === "tools/list") return { jsonrpc: "2.0", id, result: { tools: TOOLS } };
+  if (method === "tools/call") {
+    try {
+      const text = await callTool(params?.name, params?.arguments || {});
+      return { jsonrpc: "2.0", id, result: { content: [{ type: "text", text }] } };
+    } catch (e) {
+      return { jsonrpc: "2.0", id, result: { content: [{ type: "text", text: "Error: " + e.message }], isError: true } };
+    }
+  }
+  if (method === "ping") return { jsonrpc: "2.0", id, result: {} };
+  if (id === undefined || id === null) return null;
+  return { jsonrpc: "2.0", id, error: { code: -32601, message: "Method not found: " + method } };
+}
+
+createInterface({ input: process.stdin }).on("line", async (line) => {
+  const s = line.trim(); if (!s) return;
+  let req; try { req = JSON.parse(s); } catch { return; }
+  const res = await handle(req); if (res) send(res);
+});
+
+log("ready;", API_URL ? `api=${API_URL}` : `catalog=${CATALOG_URL}`, "; claude dir =", claudeDir());