skill-rules 0.2.0 → 0.3.0

package/README.md

@@ -304,6 +304,60 @@ sr use --help
 
 ---
 
+## MCP Server
+
+`skill-rules` ships a built-in [Model Context Protocol](https://modelcontextprotocol.io) server so Claude (or any MCP-compatible agent) can manage your skills directly — no terminal required.
+
+```bash
+sr mcp                     # start with global install
+npx skill-rules mcp        # start without installing
+```
+
+The server uses **stdio transport** and runs in the project directory where it is started. It exposes the following tools:
+
+| Tool     | Description                                                            |
+| -------- | ---------------------------------------------------------------------- |
+| `sync`   | Sync active skills across all detected IDEs                            |
+| `status` | Show active stage, detected IDEs, installed skills, and stash contents |
+| `init`   | Initialize `skills-lock.json`, `skills.rules`, and update `.gitignore` |
+| `add`    | Assign a skill to a stage (`skill`, `stage`, optional `track`)         |
+| `remove` | Remove a skill from a stage or all stages                              |
+| `use`    | Activate a stage or restore everything with `off: true`                |
+| `list`   | List all skills with stages, install status, and git tracking          |
+| `ignore` | Regenerate the `.gitignore` block                                      |
+
+### Configure in Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "skill-rules": {
+      "command": "npx",
+      "args": ["-y", "skill-rules", "mcp"]
+    }
+  }
+}
+```
+
+Or add globally in `~/.claude/settings.json` (requires global install):
+
+```json
+{
+  "mcpServers": {
+    "skill-rules": {
+      "command": "sr",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Once connected, Claude can call `sync`, `status`, `use`, and any other tool directly from the conversation — no CLI needed.
+
+---
+
 ## Configuration files
 
 ### `skills-lock.json`

package/dist/index.js

@@ -4,7 +4,7 @@
 import { Command } from "commander";
 import { readFileSync as readFileSync5 } from "fs";
 import { fileURLToPath } from "url";
-import { join as join11, dirname } from "path";
+import { join as join12, dirname } from "path";
 
 // src/commands/run.jsx
 import React2, { useEffect, useState as useState2 } from "react";
@@ -385,10 +385,10 @@ Available: ${available.join(", ")}` : "\nNo stages defined yet."}${hint}`
     const msg = activeStage ? `Stage [${activeStage}] has no skills. Run: skill-rules add --stage ${activeStage}` : "No skills yet. Run: skill-rules add";
     return /* @__PURE__ */ React2.createElement(Text2, { dimColor: true }, msg);
   }
-  const ok = results.filter((r) => r.status === "ok");
+  const ok2 = results.filter((r) => r.status === "ok");
   const synced = results.filter((r) => r.status === "synced");
   const missing = results.filter((r) => r.status === "missing");
-  return /* @__PURE__ */ React2.createElement(Box2, { flexDirection: "column", gap: 1 }, /* @__PURE__ */ React2.createElement(Header, null, "skill-rules", activeStage ? ` [${activeStage}]` : ""), /* @__PURE__ */ React2.createElement(Box2, { flexDirection: "column" }, /* @__PURE__ */ React2.createElement(Text2, { dimColor: true }, "IDEs (", ides.length, ")"), ides.map((ide) => /* @__PURE__ */ React2.createElement(IDEItem, { key: ide.id, ide }))), /* @__PURE__ */ React2.createElement(Box2, { flexDirection: "column" }, /* @__PURE__ */ React2.createElement(Text2, { dimColor: true }, "Skills (", results.length, ")"), results.map((r) => /* @__PURE__ */ React2.createElement(SkillStatus, { key: r.name, name: r.name, status: r.status, detail: r.detail }))), /* @__PURE__ */ React2.createElement(Box2, { gap: 3 }, ok.length > 0 && /* @__PURE__ */ React2.createElement(Text2, { color: "green" }, ok.length, " up to date"), synced.length > 0 && /* @__PURE__ */ React2.createElement(Text2, { color: "yellow" }, synced.length, " synced"), missing.length > 0 && /* @__PURE__ */ React2.createElement(Text2, { color: "red" }, missing.length, " missing \u2014 install via ", /* @__PURE__ */ React2.createElement(Text2, { bold: true }, "skills.sh"), " or", " ", /* @__PURE__ */ React2.createElement(Text2, { bold: true }, "autoskill"))));
+  return /* @__PURE__ */ React2.createElement(Box2, { flexDirection: "column", gap: 1 }, /* @__PURE__ */ React2.createElement(Header, null, "skill-rules", activeStage ? ` [${activeStage}]` : ""), /* @__PURE__ */ React2.createElement(Box2, { flexDirection: "column" }, /* @__PURE__ */ React2.createElement(Text2, { dimColor: true }, "IDEs (", ides.length, ")"), ides.map((ide) => /* @__PURE__ */ React2.createElement(IDEItem, { key: ide.id, ide }))), /* @__PURE__ */ React2.createElement(Box2, { flexDirection: "column" }, /* @__PURE__ */ React2.createElement(Text2, { dimColor: true }, "Skills (", results.length, ")"), results.map((r) => /* @__PURE__ */ React2.createElement(SkillStatus, { key: r.name, name: r.name, status: r.status, detail: r.detail }))), /* @__PURE__ */ React2.createElement(Box2, { gap: 3 }, ok2.length > 0 && /* @__PURE__ */ React2.createElement(Text2, { color: "green" }, ok2.length, " up to date"), synced.length > 0 && /* @__PURE__ */ React2.createElement(Text2, { color: "yellow" }, synced.length, " synced"), missing.length > 0 && /* @__PURE__ */ React2.createElement(Text2, { color: "red" }, missing.length, " missing \u2014 install via ", /* @__PURE__ */ React2.createElement(Text2, { bold: true }, "skills.sh"), " or", " ", /* @__PURE__ */ React2.createElement(Text2, { bold: true }, "autoskill"))));
 }
 
 // src/commands/init.jsx
@@ -1106,9 +1106,418 @@ function DoneView({ data }) {
   return null;
 }
 
+// src/mcp/server.js
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { existsSync as existsSync10, writeFileSync as writeFileSync5 } from "fs";
+import { join as join11 } from "path";
+var TOOLS = [
+  {
+    name: "sync",
+    description: "Sync active skills across all detected IDEs. Copies skills from IDEs that have them to IDEs that are missing them.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        stage: {
+          type: "string",
+          description: "Stage to filter skills by. Defaults to the currently active stage."
+        }
+      }
+    }
+  },
+  {
+    name: "status",
+    description: "Show current state: active stage, detected IDEs, installed skills with their stage assignments, and stash contents.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "init",
+    description: "Initialize skill-rules in the project. Creates skills-lock.json and skills.rules if absent, and updates .gitignore.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "add",
+    description: "Assign a skill to a stage.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        skill: { type: "string", description: "Skill name to assign" },
+        stage: { type: "string", description: "Stage name to assign the skill to" },
+        track: {
+          type: "boolean",
+          description: "Commit this skill to git instead of gitignoring it (default: false)"
+        }
+      },
+      required: ["skill", "stage"]
+    }
+  },
+  {
+    name: "remove",
+    description: "Remove a skill from a stage, or from all stages when no stage is given.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        skill: { type: "string", description: "Skill name to remove" },
+        stage: {
+          type: "string",
+          description: "Stage to remove from. Omit to remove from all stages."
+        }
+      },
+      required: ["skill"]
+    }
+  },
+  {
+    name: "use",
+    description: "Activate a stage: stash skills not assigned to it, restore skills that are. Pass off: true to restore everything and clear the active stage.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        stage: { type: "string", description: "Stage name to activate" },
+        off: {
+          type: "boolean",
+          description: "Restore all stashed skills and clear the active stage"
+        }
+      }
+    }
+  },
+  {
+    name: "list",
+    description: "List all installed skills with their stage assignments, installation status, and git tracking. Use track/untrack to change tracking.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        track: { type: "string", description: "Skill name to start committing to git" },
+        untrack: { type: "string", description: "Skill name to exclude from git" }
+      }
+    }
+  },
+  {
+    name: "ignore",
+    description: "Regenerate the skill-rules block in .gitignore for all detected IDE directories.",
+    inputSchema: { type: "object", properties: {} }
+  }
+];
+function ok(text) {
+  return { content: [{ type: "text", text }] };
+}
+function fail(text) {
+  return { content: [{ type: "text", text: `Error: ${text}` }], isError: true };
+}
+function toolSync(cwd, args) {
+  const stage = args.stage ?? getActiveStage(cwd);
+  const ides = detectIDEs(cwd);
+  if (ides.length === 0)
+    return fail(
+      "No IDE directories detected. Expected: .claude/ .cursor/ .windsurf/ .agents/ .openhands/ .opencode/"
+    );
+  const lock = readLock(cwd);
+  const rules = readRules(cwd);
+  if (stage && rules && !(stage in (rules.stages ?? {}))) {
+    const available = listStages(rules);
+    return fail(
+      `Stage "${stage}" not found.${available.length ? ` Available: ${available.join(", ")}` : " No stages defined yet."}`
+    );
+  }
+  syncGitignore(cwd, ides, lock);
+  const skillsToCheck = stage ? getActiveSkills(rules, stage) : Object.keys(lock.skills);
+  if (skillsToCheck.length === 0)
+    return ok(
+      `No skills${stage ? ` in stage [${stage}]` : ""} to sync.
+IDEs (${ides.length}): ${ides.map((i) => i.name).join(", ")}`
+    );
+  const lines = [
+    `Sync${stage ? ` [${stage}]` : ""} \u2014 ${ides.length} IDE${ides.length !== 1 ? "s" : ""}`,
+    ""
+  ];
+  for (const skillName of skillsToCheck) {
+    const sources = findSkillSources(cwd, ides, skillName);
+    if (sources.length === 0) {
+      lines.push(`missing   ${skillName}`);
+    } else if (sources.length < ides.length) {
+      const copied = syncSkillToMissingIDEs(cwd, ides, skillName, sources[0]);
+      lines.push(
+        `synced    ${skillName}  \u2192 ${copied} IDE${copied !== 1 ? "s" : ""} from ${sources[0].name}`
+      );
+    } else {
+      lines.push(`ok        ${skillName}`);
+    }
+  }
+  return ok(lines.join("\n"));
+}
+function toolStatus(cwd) {
+  const ides = detectIDEs(cwd);
+  const lock = readLock(cwd);
+  const rules = readRules(cwd);
+  const activeStage = getActiveStage(cwd);
+  const stashed = listStashed(cwd);
+  const stages = listStages(rules ?? { stages: {} });
+  const skills = Object.entries(lock.skills);
+  const lines = [
+    `Active stage : ${activeStage ? `[${activeStage}]` : "none"}`,
+    `IDEs         : ${ides.length > 0 ? ides.map((i) => i.name).join(", ") : "none detected"}`,
+    `Stages       : ${stages.length > 0 ? stages.join(", ") : "none"}`,
+    `Stashed      : ${stashed.length > 0 ? stashed.join(", ") : "none"}`,
+    ""
+  ];
+  if (skills.length === 0) {
+    lines.push("No skills installed yet.");
+  } else {
+    lines.push("Skills:");
+    for (const [name, info] of skills) {
+      const skillStages = stages.filter((s) => (rules?.stages[s] ?? []).includes(name));
+      const stageStr = skillStages.length ? skillStages.join(", ") : "\u2014";
+      const tracking = info.track ? "  [git tracked]" : "";
+      lines.push(`  ${name.padEnd(22)} ${stageStr}${tracking}`);
+    }
+  }
+  return ok(lines.join("\n"));
+}
+function toolInit(cwd) {
+  const ides = detectIDEs(cwd);
+  const lines = [];
+  const lockPath = join11(cwd, "skills-lock.json");
+  if (!existsSync10(lockPath)) {
+    writeFileSync5(lockPath, JSON.stringify({ version: 1, skills: {} }, null, 2) + "\n");
+    lines.push("created  skills-lock.json");
+  } else {
+    lines.push("exists   skills-lock.json");
+  }
+  const rulesPath = join11(cwd, "skills.rules");
+  if (!existsSync10(rulesPath)) {
+    writeFileSync5(rulesPath, JSON.stringify(createEmptyRules(), null, 2) + "\n");
+    lines.push("created  skills.rules");
+  } else {
+    lines.push("exists   skills.rules");
+  }
+  if (ides.length > 0) {
+    const lock = readLock(cwd);
+    syncGitignore(cwd, ides, lock);
+    lines.push("updated  .gitignore");
+    lines.push(`IDEs     ${ides.map((i) => i.name).join(", ")}`);
+  } else {
+    lines.push(
+      "warning  No IDE directories detected \u2014 .gitignore not updated\n         Create one of: .claude/ .cursor/ .windsurf/ .agents/ .openhands/ .opencode/"
+    );
+  }
+  return ok(lines.join("\n"));
+}
+function toolAdd(cwd, args) {
+  const { skill, stage, track = false } = args;
+  const lock = readLock(cwd);
+  const ides = detectIDEs(cwd);
+  const rules = readRules(cwd) ?? createEmptyRules();
+  const inLock = !!lock.skills[skill];
+  const alreadyInStage = (rules.stages[stage] ?? []).includes(skill);
+  const isNewStage = !listStages(rules).includes(stage);
+  if (!alreadyInStage) {
+    addSkillToStage(rules, skill, stage);
+    writeRules(rules, cwd);
+  }
+  if (track && inLock) {
+    setSkillTracked(lock, skill, true);
+    writeLock(lock, cwd);
+  }
+  if (ides.length > 0) syncGitignore(cwd, ides, lock);
+  const lines = [];
+  if (!inLock)
+    lines.push(
+      `warning  "${skill}" not in skills-lock.json \u2014 install via skills.sh or autoskill first`
+    );
+  if (isNewStage && !alreadyInStage) lines.push(`created  stage [${stage}]`);
+  lines.push(
+    alreadyInStage ? `exists   "${skill}" already in [${stage}]` : `added    "${skill}" \u2192 [${stage}]`
+  );
+  if (track)
+    lines.push(
+      inLock ? "tracked  git tracking enabled" : "warning  git tracking skipped (not in lock)"
+    );
+  return ok(lines.join("\n"));
+}
+function toolRemove(cwd, args) {
+  const { skill, stage } = args;
+  const rules = readRules(cwd);
+  if (!rules) return fail("No skills.rules found. Run init first.");
+  const stages = listStages(rules);
+  const inAnyStage = stages.some((s) => (rules.stages[s] ?? []).includes(skill));
+  if (!inAnyStage) return fail(`"${skill}" is not assigned to any stage.`);
+  if (stage && !(rules.stages[stage] ?? []).includes(skill)) {
+    const assignedTo = stages.filter((s) => (rules.stages[s] ?? []).includes(skill));
+    return fail(`"${skill}" is not in [${stage}]. Assigned to: ${assignedTo.join(", ")}`);
+  }
+  removeSkillFromStage(rules, skill, stage ?? null);
+  writeRules(rules, cwd);
+  const lock = readLock(cwd);
+  const ides = detectIDEs(cwd);
+  if (ides.length > 0) syncGitignore(cwd, ides, lock);
+  return ok(`removed  "${skill}" from ${stage ? `[${stage}]` : "all stages"}`);
+}
+function toolUse(cwd, args) {
+  const { stage, off } = args;
+  const ides = detectIDEs(cwd);
+  const lock = readLock(cwd);
+  if (!stage && !off) {
+    const activeStage = getActiveStage(cwd);
+    const stashed = listStashed(cwd);
+    if (!activeStage)
+      return ok(
+        `No active stage \u2014 all skills available.
+Stashed: ${stashed.length > 0 ? stashed.join(", ") : "none"}`
+      );
+    return ok(
+      `Active stage: [${activeStage}]
+Stashed (${stashed.length}): ${stashed.join(", ") || "none"}`
+    );
+  }
+  if (off) {
+    const stashed = listStashed(cwd);
+    if (stashed.length === 0) {
+      clearActiveStage(cwd);
+      return ok("Nothing stashed \u2014 no active stage to clear.");
+    }
+    if (ides.length === 0)
+      return fail("No IDE directories detected \u2014 cannot restore stashed skills.");
+    for (const s of stashed) restoreSkill(cwd, ides, s);
+    clearActiveStage(cwd);
+    syncGitignore(cwd, ides, lock);
+    return ok(
+      `Restored all stashed skills:
+${stashed.map((s) => `  restored  ${s}`).join("\n")}
+
+No active stage \u2014 all skills available.`
+    );
+  }
+  if (ides.length === 0) return fail("No IDE directories detected.");
+  const rules = readRules(cwd);
+  if (!rules) return fail("No skills.rules found. Run init first.");
+  const available = listStages(rules);
+  if (!available.includes(stage))
+    return fail(
+      `Stage "${stage}" not found.${available.length ? ` Available: ${available.join(", ")}` : " No stages defined yet."}`
+    );
+  const currentStage = getActiveStage(cwd);
+  if (currentStage === stage) return ok(`Stage [${stage}] is already active.`);
+  const targetSkills = new Set(rules.stages[stage] ?? []);
+  const allStagedSkills = new Set(getActiveSkills(rules, null));
+  const trackedSkills = new Set(
+    Object.entries(lock.skills ?? {}).filter(([, info]) => info.track).map(([name]) => name)
+  );
+  const toActivate = [], toRestore = [], toMissing = [], toStash = [], toSkip = [];
+  for (const skill of allStagedSkills) {
+    if (trackedSkills.has(skill)) {
+      toSkip.push(skill);
+      continue;
+    }
+    if (targetSkills.has(skill)) {
+      if (isStashed(cwd, skill)) toRestore.push(skill);
+      else {
+        const inIDEs = ides.some((ide) => existsSync10(join11(cwd, ide.skillsDir, skill)));
+        if (inIDEs) toActivate.push(skill);
+        else toMissing.push(skill);
+      }
+    } else if (!isStashed(cwd, skill)) {
+      const inIDEs = ides.some((ide) => existsSync10(join11(cwd, ide.skillsDir, skill)));
+      if (inIDEs) toStash.push(skill);
+    }
+  }
+  for (const skill of toStash) stashSkill(cwd, ides, skill);
+  for (const skill of toRestore) restoreSkill(cwd, ides, skill);
+  setActiveStage(stage, cwd);
+  syncGitignore(cwd, ides, lock);
+  const lines = [`Active stage: [${stage}]`, ""];
+  if (toActivate.length) lines.push(...toActivate.map((s) => `keep      ${s}`));
+  if (toRestore.length) lines.push(...toRestore.map((s) => `restored  ${s}`));
+  if (toStash.length) lines.push(...toStash.map((s) => `stashed   ${s}`));
+  if (toMissing.length) lines.push(...toMissing.map((s) => `missing   ${s}  (not installed)`));
+  if (toSkip.length) lines.push(...toSkip.map((s) => `skip      ${s}  (tracked in git)`));
+  return ok(lines.join("\n"));
+}
+function toolList(cwd, args) {
+  const { track, untrack } = args;
+  const lock = readLock(cwd);
+  const ides = detectIDEs(cwd);
+  if (track || untrack) {
+    const skillName = track ?? untrack;
+    if (!lock.skills[skillName]) return fail(`"${skillName}" not found in skills-lock.json`);
+    setSkillTracked(lock, skillName, !!track);
+    writeLock(lock, cwd);
+    syncGitignore(cwd, ides, lock);
+    return ok(
+      `${track ? "tracked" : "untracked"}  "${skillName}" \u2014 ${track ? "will be committed to git" : "excluded from git"}`
+    );
+  }
+  const rules = readRules(cwd);
+  const stages = listStages(rules ?? { stages: {} });
+  const skills = Object.entries(lock.skills);
+  if (skills.length === 0) return ok("No skills installed yet. Run: sr add");
+  const header = `${"SKILL".padEnd(22)} ${"STAGES".padEnd(18)} INSTALLED    TRACKING`;
+  const lines = [header, ""];
+  for (const [name, info] of skills) {
+    const sources = findSkillSources(cwd, ides, name);
+    const skillStages = stages.filter((s) => (rules?.stages[s] ?? []).includes(name));
+    const installed = sources.length === 0 ? "missing" : sources.length === ides.length ? "all IDEs" : "partial";
+    const tracking = info.track ? "git" : "ignored";
+    lines.push(
+      `${name.padEnd(22)} ${(skillStages.join(", ") || "\u2014").padEnd(18)} ${installed.padEnd(13)}${tracking}`
+    );
+  }
+  return ok(lines.join("\n"));
+}
+function toolIgnore(cwd) {
+  const ides = detectIDEs(cwd);
+  if (ides.length === 0) return fail("No IDE directories detected. Nothing to ignore.");
+  const lock = readLock(cwd);
+  syncGitignore(cwd, ides, lock);
+  return ok(
+    `.gitignore updated for ${ides.length} IDE${ides.length !== 1 ? "s" : ""}: ${ides.map((i) => i.name).join(", ")}`
+  );
+}
+async function startMcpServer() {
+  const cwd = process.cwd();
+  const server = new Server(
+    { name: "skill-rules", version: "0.2.0" },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    try {
+      switch (name) {
+        case "sync":
+          return toolSync(cwd, args);
+        case "status":
+          return toolStatus(cwd);
+        case "init":
+          return toolInit(cwd);
+        case "add":
+          return toolAdd(cwd, args);
+        case "remove":
+          return toolRemove(cwd, args);
+        case "use":
+          return toolUse(cwd, args);
+        case "list":
+          return toolList(cwd, args);
+        case "ignore":
+          return toolIgnore(cwd);
+        default:
+          return fail(`Unknown tool: ${name}`);
+      }
+    } catch (e) {
+      return fail(e.message);
+    }
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+// src/commands/mcp.js
+async function mcp() {
+  await startMcpServer();
+}
+
 // src/cli.jsx
 var __dirname = dirname(fileURLToPath(import.meta.url));
-var { version } = JSON.parse(readFileSync5(join11(__dirname, "../package.json"), "utf8"));
+var { version } = JSON.parse(readFileSync5(join12(__dirname, "../package.json"), "utf8"));
 var stageOption = ["-s, --stage <stage>", "limit to a specific stage (e.g. dev, qa)"];
 function createCli() {
   const program = new Command();
@@ -1120,6 +1529,7 @@ function createCli() {
   program.command("ignore").description("Regenerate .gitignore for detected IDE skill directories").action(ignore);
   program.command("use [stage]").description("Activate a stage \u2014 stashes skills not in it, restores those that are").option("--off", "restore all stashed skills and clear the active stage").action(use);
   program.command("help").description("Show help for all commands").action(help);
+  program.command("mcp").description("Start the skill-rules MCP server (stdio transport)").action(mcp);
   return program;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-rules",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Sync AI agent skills across Claude Code, Cursor, Windsurf and more — activate per-environment rule sets with one command",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
   ],
   "dependencies": {
     "@inkjs/ui": "~2.0.0",
+    "@modelcontextprotocol/sdk": "~1.29.0",
     "commander": "~12.1.0",
     "figures": "~6.1.0",
     "ink": "~5.2.1",