@lifeaitools/rdc-skills 0.16.0 → 0.17.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "RDC typed-agent dispatch skill suite for Claude Code — plan, build, review, overnight unattended builds with work-item tracking and TDD enforcement.",
   "author": {
     "name": "LIFEAI",

package/bin/rdc-skills-mcp.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * bin/rdc-skills-mcp.mjs — local MCP server exposing the rdc-skills library.
+ *
+ * Mirrors the codeflow MCP topology (packages/codeflow/src/mcp/server.ts):
+ *   express + @modelcontextprotocol/sdk McpServer + StreamableHTTPServerTransport,
+ *   stateless (a fresh server+transport per POST /mcp), PORT from env.
+ *
+ * Routes:
+ *   POST /mcp     — MCP over StreamableHTTP. NO Authorization (URL is the shared
+ *                   secret, consistent with codeflow/clauth tunnel MCPs).
+ *   GET  /health  — { status, service, version, skills } — no auth, no heavy work.
+ *   /.well-known/* + /authorize + /token → 404 (force connectors to skip OAuth).
+ *
+ * It is tunneled in production at https://rdc-skills.regendevcorp.com/mcp; this
+ * process only listens on PORT (default 3110) and does not configure the tunnel.
+ *
+ * ── Caller detection → variant (best-effort) ────────────────────────────────
+ * Tools render a `cli` or `cloud` body. Detection rule: on MCP `initialize`,
+ * `clientInfo.name` containing `claude-code` or `codex` → `cli`; anything else
+ * (claude.ai web) → `cloud`; unknown → `cloud` (safer for web).
+ *
+ * APPROACH TAKEN — default + explicit override (NOT session-threaded):
+ * The transport is stateless (a new McpServer per POST, sessionIdGenerator:
+ * undefined), so there is no durable session to thread clientInfo through to a
+ * later tools/call. Rather than build a fragile session map, we:
+ *   - capture clientInfo on `initialize` and remember the MOST RECENT one
+ *     process-wide as a soft default (helps the common single-client case), and
+ *   - ALWAYS honor an explicit `variant` arg on rdc_skill_get (the must-have).
+ * If no explicit variant is given and no client has initialized this process,
+ * the default is `cloud`. This keeps the override correct and the auto-detect
+ * best-effort, exactly as the spec permits.
+ */
+
+import express from 'express';
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  listSkills,
+  getSkill,
+  getSkillBody,
+  getCloudOverride,
+  skillNames,
+  searchSkills,
+} from '../lib/catalog.mjs';
+import { toCloudBody } from '../lib/cloud-rewrite.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..');
+const PORT = parseInt(process.env.PORT || '3110', 10);
+
+function pkgVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8')).version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+// Soft process-wide default variant, updated whenever a client initializes.
+let lastDetectedVariant = 'cloud';
+
+/** Map a clientInfo.name → variant. */
+function variantForClient(clientName) {
+  const n = String(clientName || '').toLowerCase();
+  if (n.includes('claude-code') || n.includes('codex')) return 'cli';
+  return 'cloud'; // claude.ai web client and anything unknown
+}
+
+/**
+ * Render a skill body for the resolved variant.
+ *   - cli   → SKILL.md body unchanged.
+ *   - cloud → SKILL.cloud.md verbatim if present, else toCloudBody(SKILL.md).
+ * Returns { header, body } or null if the skill has no body on disk.
+ */
+function renderSkill(name, variant) {
+  const body = getSkillBody(name);
+  if (body == null) return null;
+  if (variant === 'cli') {
+    return { header: `<!-- rdc-skills: '${name}' served as CLI variant -->`, body };
+  }
+  const override = getCloudOverride(name);
+  if (override != null) {
+    return {
+      header: `<!-- rdc-skills: '${name}' served as CLOUD variant (hand-tuned SKILL.cloud.md) -->`,
+      body: override,
+    };
+  }
+  return {
+    header: `<!-- rdc-skills: '${name}' served as CLOUD variant (auto-rewritten from SKILL.md) -->`,
+    body: toCloudBody(body),
+  };
+}
+
+function textResult(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+function buildMcpServer() {
+  const srv = new McpServer({ name: 'rdc-skills', version: pkgVersion() });
+
+  // Capture clientInfo on initialize to refine the soft default variant.
+  // The SDK exposes the underlying low-level server; oninitialized fires after
+  // the client's initialize params are recorded.
+  try {
+    srv.server.oninitialized = () => {
+      const info = srv.server.getClientVersion?.();
+      if (info?.name) lastDetectedVariant = variantForClient(info.name);
+    };
+  } catch {
+    /* non-fatal: detection stays at the cloud default */
+  }
+
+  // ── rdc_skill_list ─────────────────────────────────────────────────────────
+  srv.registerTool(
+    'rdc_skill_list',
+    {
+      description:
+        'List the rdc-skills catalog: every skill with its slash form, category, summary, when-to-use triggers, usage, args, and required capabilities. No input required.',
+      inputSchema: {},
+    },
+    async () => {
+      const catalog = listSkills();
+      return textResult(JSON.stringify({ count: catalog.length, skills: catalog }, null, 2));
+    },
+  );
+
+  // ── rdc_skill_get ──────────────────────────────────────────────────────────
+  srv.registerTool(
+    'rdc_skill_get',
+    {
+      description:
+        "Get a skill's SKILL.md body rendered for the caller. variant 'cli' returns the body unchanged; 'cloud' rewrites local-shell/clauth-daemon steps for the claude.ai web client. Omit variant to use auto-detection (defaults to cloud).",
+      inputSchema: {
+        name: z.string().describe('Skill name (e.g. "deploy", "build"). See rdc_skill_list.'),
+        variant: z.enum(['cli', 'cloud']).optional().describe('Force the rendered variant; overrides caller detection.'),
+      },
+    },
+    async ({ name, variant }) => {
+      const valid = skillNames();
+      if (!valid.includes(name)) {
+        return textResult(
+          `Unknown skill '${name}'. Valid skills (${valid.length}): ${valid.join(', ')}`,
+        );
+      }
+      const resolved = variant || lastDetectedVariant || 'cloud';
+      const rendered = renderSkill(name, resolved);
+      if (!rendered) {
+        return textResult(`Skill '${name}' exists in the catalog but has no SKILL.md body on disk.`);
+      }
+      return textResult(`${rendered.header}\n\n${rendered.body}`);
+    },
+  );
+
+  // ── rdc_skill_search ───────────────────────────────────────────────────────
+  srv.registerTool(
+    'rdc_skill_search',
+    {
+      description:
+        'Fuzzy/substring search the rdc-skills catalog over name, slash, summary, and trigger phrases. Returns ranked matches.',
+      inputSchema: {
+        query: z.string().describe('Search terms, e.g. "deploy coolify" or "work items".'),
+      },
+    },
+    async ({ query }) => {
+      const results = searchSkills(query);
+      return textResult(JSON.stringify({ query, count: results.length, results }, null, 2));
+    },
+  );
+
+  return srv;
+}
+
+function startHttp() {
+  const app = express();
+  app.use(express.json({ limit: '4mb' }));
+
+  // /health — open, cheap, reports live skill count.
+  app.get('/health', (_req, res) => {
+    let skills = 0;
+    try {
+      skills = listSkills().length;
+    } catch {
+      skills = 0;
+    }
+    res.json({ status: 'ok', service: 'rdc-skills-mcp', version: pkgVersion(), skills });
+  });
+
+  // Block OAuth discovery so connectors skip OAuth and connect direct — /mcp is open.
+  app.get('/.well-known/oauth-authorization-server', (_req, res) => res.status(404).end());
+  app.get('/.well-known/openid-configuration', (_req, res) => res.status(404).end());
+  app.get('/authorize', (_req, res) => res.status(404).end());
+  app.post('/token', (_req, res) => res.status(404).end());
+
+  // POST /mcp — stateless StreamableHTTP transport, no Authorization required.
+  app.post('/mcp', async (req, res) => {
+    try {
+      const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+      const srv = buildMcpServer();
+      await srv.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+      res.on('close', async () => {
+        await transport.close().catch(() => {});
+        await srv.close().catch(() => {});
+      });
+    } catch (err) {
+      console.error('[rdc-skills-mcp] MCP error:', err);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: '2.0',
+          error: { code: -32603, message: err?.message || 'internal error' },
+          id: null,
+        });
+      }
+    }
+  });
+
+  app.get('/mcp', (_req, res) => {
+    res.status(405).json({
+      jsonrpc: '2.0',
+      error: { code: -32000, message: 'Use POST for MCP requests' },
+      id: null,
+    });
+  });
+
+  app.listen(PORT, () => {
+    console.log(`[rdc-skills-mcp] ready on port ${PORT}`);
+    console.log(`  MCP:    POST http://localhost:${PORT}/mcp`);
+    console.log(`  Health: GET  http://localhost:${PORT}/health`);
+  });
+}
+
+startHttp();

package/lib/catalog.mjs

@@ -0,0 +1,174 @@
+/**
+ * lib/catalog.mjs — rdc-skills catalog loader for the local MCP server.
+ *
+ * Source of truth: `.claude-plugin/plugin.json` → `skills_meta` (an object keyed
+ * by skill name). Each entry provides { name, slash, category, usage, args,
+ * requires, triggers, ... }. We enrich each entry with the `description` from
+ * the skill's own `skills/<name>/SKILL.md` frontmatter (the human summary).
+ *
+ * Loading is LIVE: the catalog is re-read from disk when older than CACHE_TTL_MS
+ * so a skill edit (frontmatter or body) is picked up without a server restart.
+ * A skill that has a `skills_meta` entry but no SKILL.md on disk is still listed
+ * (meta-only); a skill dir with a SKILL.md but no meta entry is also surfaced
+ * (frontmatter-only) so nothing silently disappears from the catalog.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..');
+const PLUGIN_JSON = path.join(REPO_ROOT, '.claude-plugin', 'plugin.json');
+const SKILLS_DIR = path.join(REPO_ROOT, 'skills');
+
+const CACHE_TTL_MS = 5000; // short TTL: live-from-disk feel, cheap re-reads
+
+let _cache = null;
+let _cacheAt = 0;
+
+/** Read + parse the YAML frontmatter block of a SKILL.md. Returns {} on miss. */
+function readFrontmatter(skillMdPath) {
+  try {
+    const raw = fs.readFileSync(skillMdPath, 'utf8').replace(/\r\n/g, '\n');
+    const m = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!m) return {};
+    const parsed = YAML.parse(m[1]);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Map a raw skills_meta entry + SKILL.md frontmatter into a compact catalog row. */
+function toCatalogEntry(name, meta, frontmatter) {
+  const description = frontmatter.description || meta.description || '';
+  // `summary` is the short customer-facing line; `when_to_use` pulls the triggers.
+  const triggers = Array.isArray(meta.triggers) ? meta.triggers : [];
+  return {
+    name,
+    slash: meta.slash || `rdc:${name}`,
+    category: meta.category || 'tooling',
+    summary: description,
+    when_to_use: triggers,
+    usage: meta.usage || '',
+    args: meta.args || { positional: [], flags: [] },
+    requires: Array.isArray(meta.requires) ? meta.requires : [],
+  };
+}
+
+/** Re-read plugin.json + skill frontmatter from disk and rebuild the catalog. */
+function buildCatalog() {
+  let plugin = {};
+  try {
+    plugin = JSON.parse(fs.readFileSync(PLUGIN_JSON, 'utf8'));
+  } catch {
+    plugin = {};
+  }
+  const skillsMeta = plugin.skills_meta && typeof plugin.skills_meta === 'object' ? plugin.skills_meta : {};
+
+  const byName = new Map();
+
+  // 1. Every skills_meta entry → enrich with its SKILL.md frontmatter.
+  for (const [name, meta] of Object.entries(skillsMeta)) {
+    const skillMd = path.join(SKILLS_DIR, name, 'SKILL.md');
+    const fm = fs.existsSync(skillMd) ? readFrontmatter(skillMd) : {};
+    byName.set(name, toCatalogEntry(name, meta || {}, fm));
+  }
+
+  // 2. Any skill dir with a SKILL.md but NO meta entry → frontmatter-only row.
+  if (fs.existsSync(SKILLS_DIR)) {
+    for (const entry of fs.readdirSync(SKILLS_DIR, { withFileTypes: true })) {
+      if (!entry.isDirectory() || byName.has(entry.name)) continue;
+      const skillMd = path.join(SKILLS_DIR, entry.name, 'SKILL.md');
+      if (!fs.existsSync(skillMd)) continue;
+      const fm = readFrontmatter(skillMd);
+      byName.set(entry.name, toCatalogEntry(entry.name, {}, fm));
+    }
+  }
+
+  return Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Return the cached catalog, rebuilding if the TTL has elapsed. */
+function getCatalog() {
+  const now = Date.now();
+  if (!_cache || now - _cacheAt > CACHE_TTL_MS) {
+    _cache = buildCatalog();
+    _cacheAt = now;
+  }
+  return _cache;
+}
+
+/** Compact catalog for `rdc_skill_list`. */
+export function listSkills() {
+  return getCatalog();
+}
+
+/** Full catalog row for one skill, or null if unknown. */
+export function getSkill(name) {
+  return getCatalog().find((s) => s.name === name) || null;
+}
+
+/** List of valid skill names (for error messages). */
+export function skillNames() {
+  return getCatalog().map((s) => s.name);
+}
+
+/**
+ * Read the raw SKILL.md body (frontmatter stripped) for a skill, live from disk.
+ * Returns null if the file does not exist.
+ */
+export function getSkillBody(name) {
+  const skillMd = path.join(SKILLS_DIR, name, 'SKILL.md');
+  if (!fs.existsSync(skillMd)) return null;
+  const raw = fs.readFileSync(skillMd, 'utf8').replace(/\r\n/g, '\n');
+  // Strip the leading frontmatter block if present.
+  const m = raw.match(/^---\n[\s\S]*?\n---\n?/);
+  return m ? raw.slice(m[0].length).replace(/^\n+/, '') : raw;
+}
+
+/** Absolute path to a hand-tuned cloud override, or null if absent. */
+export function cloudOverridePath(name) {
+  const p = path.join(SKILLS_DIR, name, 'SKILL.cloud.md');
+  return fs.existsSync(p) ? p : null;
+}
+
+/** Read the hand-tuned cloud override body (frontmatter stripped), or null. */
+export function getCloudOverride(name) {
+  const p = cloudOverridePath(name);
+  if (!p) return null;
+  const raw = fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n');
+  const m = raw.match(/^---\n[\s\S]*?\n---\n?/);
+  return m ? raw.slice(m[0].length).replace(/^\n+/, '') : raw;
+}
+
+/**
+ * Fuzzy/substring search over name + slash + summary + triggers.
+ * Returns ranked [{ name, slash, summary, score }] (score: higher = better).
+ */
+export function searchSkills(query) {
+  const q = String(query || '').trim().toLowerCase();
+  if (!q) return [];
+  const terms = q.split(/\s+/).filter(Boolean);
+  const results = [];
+  for (const s of getCatalog()) {
+    const hay = {
+      name: s.name.toLowerCase(),
+      slash: (s.slash || '').toLowerCase(),
+      summary: (s.summary || '').toLowerCase(),
+      triggers: (s.when_to_use || []).join(' ').toLowerCase(),
+    };
+    let score = 0;
+    for (const term of terms) {
+      if (hay.name === term) score += 100;
+      else if (hay.name.includes(term)) score += 40;
+      if (hay.slash.includes(term)) score += 20;
+      if (hay.triggers.includes(term)) score += 12;
+      if (hay.summary.includes(term)) score += 6;
+    }
+    if (score > 0) results.push({ name: s.name, slash: s.slash, summary: s.summary, score });
+  }
+  return results.sort((a, b) => b.score - a.score);
+}

package/lib/cloud-rewrite.mjs

@@ -0,0 +1,155 @@
+/**
+ * lib/cloud-rewrite.mjs — transform a CLI SKILL.md body into a cloud
+ * (claude.ai web) body.
+ *
+ * The CLI bodies assume a Claude Code session on Dave's Windows host: a local
+ * clauth HTTP daemon at 127.0.0.1:52437, a local shell, PM2, git, pnpm, and
+ * local node scripts. The claude.ai web client has NONE of those — it reaches
+ * credentials through the clauth MCP and the filesystem through the File System
+ * MCP, and it cannot run local processes at all.
+ *
+ * `toCloudBody(markdown)` applies rule-based rewrites:
+ *   1. clauth daemon curl  → "retrieve `<svc>` via the clauth MCP"
+ *   2. local shell/Bash fs ops + local `fs` → File System MCP tools
+ *   3. CLI-only mechanics (PM2 reload, git push, local node scripts, daemon
+ *      restart, pnpm) → annotated with a callout (NOT deleted — the cloud
+ *      caller needs to know to hand that step to a Claude Code session).
+ *
+ * The rewriter is intentionally rule-based and conservative: it annotates rather
+ * than rips out, so no information is lost. A hand-tuned `SKILL.cloud.md` (handled
+ * by the caller in catalog.mjs) bypasses this entirely.
+ *
+ * Contract: the cloud body for `deploy` MUST NOT contain `127.0.0.1:52437`.
+ */
+
+const CLI_CALLOUT = '> ⚠ CLI-only step — hand this to a Claude Code session.';
+
+/**
+ * Rule 1 — clauth daemon credential retrieval.
+ * Matches `curl ... http://127.0.0.1:52437/v/<svc>` (and /get/<svc>), with or
+ * without flags, optionally wrapped in $(...). Collapses to instruction text.
+ */
+function rewriteClauthCurls(md) {
+  let out = md;
+
+  // `_VAR=$(curl ... 127.0.0.1:52437/v/<svc>)`  → assignment-style instruction
+  out = out.replace(
+    /([A-Za-z_][A-Za-z0-9_]*)=\$\(\s*curl[^\n)]*?(?:127\.0\.0\.1|localhost):52437\/(?:v|get)\/([A-Za-z0-9._-]+)[^\n)]*\)/g,
+    (_m, varName, svc) => `# ${varName}: retrieve \`${svc}\` via the clauth MCP (clauth_inject / clauth_get)`,
+  );
+
+  // bare `curl ... 127.0.0.1:52437/v/<svc>` → instruction
+  out = out.replace(
+    /curl[^\n]*?(?:127\.0\.0\.1|localhost):52437\/(?:v|get)\/([A-Za-z0-9._-]+)[^\n]*/g,
+    (_m, svc) => `retrieve \`${svc}\` via the clauth MCP (clauth_inject / clauth_get)`,
+  );
+
+  // any remaining ping/list/other daemon references → MCP instruction
+  out = out.replace(
+    /curl[^\n]*?(?:127\.0\.0\.1|localhost):52437\/(?:ping|list-services|status|meta)[^\n]*/g,
+    'check clauth health via the clauth MCP (clauth_ping / clauth_status)',
+  );
+
+  // belt-and-suspenders: kill any stray bare daemon URL still standing
+  out = out.replace(
+    /https?:\/\/(?:127\.0\.0\.1|localhost):52437\/(?:v|get)\/([A-Za-z0-9._-]+)/g,
+    (_m, svc) => `the clauth MCP value for \`${svc}\``,
+  );
+  out = out.replace(
+    /https?:\/\/(?:127\.0\.0\.1|localhost):52437\S*/g,
+    'the clauth MCP',
+  );
+
+  return out;
+}
+
+/**
+ * Rule 2 — local shell/Bash file ops and a local `fs` → File System MCP.
+ * We add a one-line note rather than rewriting every cat/ls/grep, since the
+ * shapes vary wildly; the note tells the cloud caller which tools to reach for.
+ */
+function rewriteFsOps(md) {
+  let out = md;
+  // Direct references to a local `fs` module / node fs.
+  out = out.replace(
+    /\bnode:fs\b|\brequire\(['"]fs['"]\)\b|\bfrom ['"]fs['"]/g,
+    'the File System MCP (fs_read/fs_write/fs_glob/fs_grep)',
+  );
+  return out;
+}
+
+/**
+ * Rule 3 — flag CLI-only mechanics with a callout. We annotate fenced code
+ * blocks and bullet/numbered lines that contain a CLI-only verb. The callout
+ * is inserted ABOVE the offending block/line; the content is preserved.
+ */
+const CLI_ONLY_PATTERNS = [
+  /\bpm2\s+(?:start|restart|reload|delete|stop|list|status)\b/i,
+  /\bgit\s+push\b/i,
+  /\bpnpm\b/i,
+  /\bnpm\s+(?:install|run|publish|ci)\b/i,
+  /\bnode\s+[A-Za-z0-9_./-]+\.(?:mjs|cjs|js)\b/i,
+  /\brestart-clauth(?:\.bat)?\b/i,
+  /\bclauth\s+(?:scrub|restart|serve|lock|unlock)\b/i,
+];
+
+function isCliOnlyLine(line) {
+  return CLI_ONLY_PATTERNS.some((re) => re.test(line));
+}
+
+/**
+ * Walk the markdown line by line. Inside fenced ``` blocks, if ANY line trips a
+ * CLI-only pattern, emit one callout immediately before the fence. Outside code
+ * blocks, annotate individual list/prose lines that trip a pattern.
+ */
+function annotateCliOnly(md) {
+  const lines = md.split('\n');
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const fenceMatch = line.match(/^(\s*)```/);
+    if (fenceMatch) {
+      // Collect the whole fenced block.
+      const block = [line];
+      let j = i + 1;
+      for (; j < lines.length; j++) {
+        block.push(lines[j]);
+        if (/^\s*```/.test(lines[j])) {
+          j++;
+          break;
+        }
+      }
+      const hasCliOnly = block.some(isCliOnlyLine);
+      if (hasCliOnly) out.push(`${fenceMatch[1]}${CLI_CALLOUT}`);
+      out.push(...block);
+      i = j;
+      continue;
+    }
+
+    // Non-fence line: annotate list/prose lines that trip a pattern, but never
+    // double-annotate (skip if previous emitted line is already the callout).
+    if (isCliOnlyLine(line) && out[out.length - 1] !== CLI_CALLOUT) {
+      const indent = (line.match(/^(\s*)/) || ['', ''])[1];
+      out.push(`${indent}${CLI_CALLOUT}`);
+    }
+    out.push(line);
+    i++;
+  }
+  return out.join('\n');
+}
+
+/**
+ * Transform a CLI SKILL.md body into the cloud body.
+ * Order matters: rewrite clauth curls FIRST (they often live in code blocks that
+ * the CLI-only annotator would otherwise also flag), then fs ops, then annotate
+ * remaining CLI-only mechanics.
+ */
+export function toCloudBody(markdown) {
+  if (typeof markdown !== 'string' || !markdown) return markdown;
+  let out = markdown;
+  out = rewriteClauthCurls(out);
+  out = rewriteFsOps(out);
+  out = annotateCliOnly(out);
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",
@@ -24,7 +24,8 @@
   },
   "bin": {
     "rdc-skills-install": "scripts/install-rdc-skills.js",
-    "rdc-skills-self-test": "scripts/self-test.mjs"
+    "rdc-skills-self-test": "scripts/self-test.mjs",
+    "rdc-skills-mcp": "bin/rdc-skills-mcp.mjs"
   },
   "scripts": {
     "install-rdc-skills": "node scripts/install-rdc-skills.js",
@@ -33,9 +34,16 @@
     "validate": "node tests/validate-skills.js",
     "rdc-design": "node scripts/rdc-design-cli.mjs",
     "test:hooks": "node scripts/test-rdc-hooks.mjs",
+    "test:mcp": "node tests/mcp.test.mjs",
+    "test:mcp:remote": "node tests/mcp.test.mjs --remote",
+    "mcp": "node bin/rdc-skills-mcp.mjs",
+    "rebuild-mcp": "node scripts/rebuild-mcp.mjs",
     "prepack": "node scripts/validate-publish-manifests.js --mode warn || true && node scripts/validate-place-histories.js --mode warn || true"
   },
-  "devDependencies": {
-    "yaml": "^2.9.0"
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^5.0.0",
+    "yaml": "^2.9.0",
+    "zod": "^3.25.76"
   }
 }

package/scripts/install-rdc-skills.js

@@ -675,6 +675,66 @@ function buildHooksConfig(hooksDir, profile = 'core') {
   return config;
 }
 
+// ── MCP server registration (non-fatal) ───────────────────────────────────────
+// Ensures the rdc-skills MCP deps are installed, registers/starts the local MCP
+// under PM2 as `rdc-skills-mcp` on PORT=3110, and prints the claude.ai connector
+// line. Every failure here WARNs — it must never abort the installer.
+function registerMcpServer() {
+  const MCP_NAME = 'rdc-skills-mcp';
+  const MCP_PORT = '3110';
+  const binPath = path.join(repoRoot, 'bin', 'rdc-skills-mcp.mjs');
+  const connector = 'https://rdc-skills.regendevcorp.com/mcp';
+
+  try {
+    // (a) ensure MCP runtime deps are present (express, @modelcontextprotocol/sdk, yaml, zod)
+    const needDeps = ['express', '@modelcontextprotocol/sdk', 'yaml', 'zod'].some((d) => {
+      try { require.resolve(d, { paths: [repoRoot] }); return false; } catch { return true; }
+    });
+    if (needDeps) {
+      try {
+        execSync('npm install --no-audit --no-fund', { cwd: repoRoot, stdio: 'pipe' });
+        ok('[7/7] MCP deps   — installed');
+      } catch (e) {
+        warn(`[7/7] MCP deps   — npm install failed (${e.message.split('\n')[0]}); install manually with \`npm install\``);
+      }
+    } else {
+      ok('[7/7] MCP deps   — already present');
+    }
+
+    // (b) register/start under PM2 (tolerate pm2 missing)
+    let pm2Ok = false;
+    try { execSync('pm2 -v', { stdio: 'pipe' }); pm2Ok = true; } catch { pm2Ok = false; }
+
+    if (!pm2Ok) {
+      warn('[7/7] MCP server — pm2 not found; start manually:');
+      info(`       PORT=${MCP_PORT} pm2 start ${binPath} --name ${MCP_NAME}`);
+    } else {
+      let registered = false;
+      try {
+        const jlist = JSON.parse(execSync('pm2 jlist', { encoding: 'utf8', stdio: 'pipe' }));
+        registered = Array.isArray(jlist) && jlist.some((p) => p.name === MCP_NAME);
+      } catch {}
+      try {
+        if (registered) {
+          execSync(`pm2 restart ${MCP_NAME} --update-env`, { cwd: repoRoot, stdio: 'pipe', env: { ...process.env, PORT: MCP_PORT } });
+          ok(`[7/7] MCP server — pm2 restarted ${MCP_NAME} (PORT=${MCP_PORT})`);
+        } else {
+          execSync(`pm2 start "${binPath}" --name ${MCP_NAME}`, { cwd: repoRoot, stdio: 'pipe', env: { ...process.env, PORT: MCP_PORT } });
+          ok(`[7/7] MCP server — pm2 started ${MCP_NAME} (PORT=${MCP_PORT})`);
+        }
+      } catch (e) {
+        warn(`[7/7] MCP server — pm2 start/restart failed (${e.message.split('\n')[0]})`);
+        info(`       PORT=${MCP_PORT} pm2 start ${binPath} --name ${MCP_NAME}`);
+      }
+    }
+
+    // (c) print the claude.ai connector line
+    info(`       claude.ai connector: ${connector}  (Auth: none — URL is the shared secret)`);
+  } catch (e) {
+    warn(`[7/7] MCP server — skipped (${e.message.split('\n')[0]})`);
+  }
+}
+
 // ── Preflight ─────────────────────────────────────────────────────────────────
 function runPreflight() {
   const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
@@ -982,6 +1042,11 @@ async function main() {
     process.exit(2);
   }
 
+  // 7. MCP server registration (non-fatal — WARNs only, never aborts)
+  console.log('');
+  console.log('  \x1b[36mMCP server:\x1b[0m');
+  try { registerMcpServer(); } catch (e) { warn(`[7/7] MCP server — unexpected error (${e.message})`); }
+
   // Done
   console.log('');
   console.log('  \x1b[32mDone!\x1b[0m');

package/scripts/rebuild-mcp.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * scripts/rebuild-mcp.mjs — "build hook" for the rdc-skills MCP server.
+ *
+ * The server reads skills live from disk, so a skill edit is usually picked up
+ * without a restart. This script exists to (a) bounce the PM2 process so any
+ * in-memory module cache is dropped, and (b) assert the local /health endpoint
+ * reports the current on-disk skill count — a fast smoke that the server is up
+ * and seeing the same catalog this script does.
+ *
+ * Tolerant of a missing PM2: if pm2 is not installed/registered, it prints how
+ * to start the server and exits 0. It never hard-fails the caller.
+ */
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { listSkills } from '../lib/catalog.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..');
+const PM2_NAME = 'rdc-skills-mcp';
+const PORT = parseInt(process.env.PORT || '3110', 10);
+const BIN = path.join(REPO_ROOT, 'bin', 'rdc-skills-mcp.mjs');
+
+const ok = (m) => console.log(`  \x1b[32m✓\x1b[0m ${m}`);
+const info = (m) => console.log(`  \x1b[36m→\x1b[0m ${m}`);
+const warn = (m) => console.log(`  \x1b[33m⚠\x1b[0m ${m}`);
+
+function sh(cmd) {
+  return execSync(cmd, { encoding: 'utf8', stdio: 'pipe' }).trim();
+}
+
+function pm2Available() {
+  try {
+    sh('pm2 -v');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function pm2HasProcess() {
+  try {
+    const list = JSON.parse(sh('pm2 jlist'));
+    return Array.isArray(list) && list.some((p) => p.name === PM2_NAME);
+  } catch {
+    return false;
+  }
+}
+
+async function checkHealth(expectedSkills) {
+  // Node 22 has global fetch.
+  try {
+    const res = await fetch(`http://127.0.0.1:${PORT}/health`, { signal: AbortSignal.timeout(4000) });
+    if (!res.ok) {
+      warn(`/health returned HTTP ${res.status}`);
+      return false;
+    }
+    const json = await res.json();
+    if (json.skills === expectedSkills) {
+      ok(`/health OK — skills=${json.skills} (matches disk), version=${json.version}`);
+      return true;
+    }
+    warn(`/health skills=${json.skills} but disk has ${expectedSkills} — server may be stale`);
+    return false;
+  } catch (err) {
+    warn(`/health unreachable on port ${PORT}: ${err?.message || err}`);
+    return false;
+  }
+}
+
+async function main() {
+  const diskSkills = listSkills().length;
+  info(`On-disk catalog: ${diskSkills} skill(s)`);
+
+  if (!pm2Available()) {
+    warn('pm2 not found — cannot bounce the MCP process.');
+    info(`Start it manually:  PORT=${PORT} pm2 start ${BIN} --name ${PM2_NAME}`);
+    info(`Or run directly:    PORT=${PORT} node ${BIN}`);
+    process.exit(0);
+  }
+
+  if (pm2HasProcess()) {
+    try {
+      sh(`pm2 restart ${PM2_NAME} --update-env`);
+      ok(`pm2 restart ${PM2_NAME}`);
+    } catch (err) {
+      warn(`pm2 restart failed: ${err?.message || err}`);
+    }
+  } else {
+    info(`pm2 process '${PM2_NAME}' not registered.`);
+    info(`Start it:  PORT=${PORT} pm2 start ${BIN} --name ${PM2_NAME}`);
+    process.exit(0);
+  }
+
+  // Give the process a beat to bind, then probe /health (no long sleeps).
+  await new Promise((r) => setTimeout(r, 1200));
+  await checkHealth(diskSkills);
+  process.exit(0);
+}
+
+main().catch((err) => {
+  warn(`rebuild-mcp error (non-fatal): ${err?.message || err}`);
+  process.exit(0);
+});

package/tests/mcp.test.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/**
+ * tests/mcp.test.mjs — layered test for the rdc-skills MCP server.
+ *
+ *   node tests/mcp.test.mjs            # unit + integration (spawns the server)
+ *   REMOTE=1 node tests/mcp.test.mjs   # ALSO sweep the live tunnel endpoint
+ *
+ * Coverage is 100% of skills: every skill in the catalog is fetched through the
+ * MCP in BOTH variants and asserted against its on-disk source, and the cloud
+ * contract (no `127.0.0.1:52437` daemon URL) is checked for EVERY skill.
+ *
+ * Layers:
+ *   1. unit        — catalog + cloud-rewrite pure functions.
+ *   2. integration — spawn `bin/rdc-skills-mcp.mjs` on a test port; exercise
+ *                    /health and the full MCP (initialize, tools/list, every
+ *                    tool, every skill, error paths) over HTTP, comparing each
+ *                    rendered body byte-for-byte to the library's own output.
+ *   3. systems     — (REMOTE=1) the same cloud-contract sweep against
+ *                    https://rdc-skills.regendevcorp.com/mcp through Cloudflare.
+ *
+ * Dependency-free: node builtins + the project's own lib + global fetch.
+ */
+
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  listSkills,
+  getSkill,
+  skillNames,
+  getSkillBody,
+  getCloudOverride,
+  searchSkills,
+} from '../lib/catalog.mjs';
+import { toCloudBody } from '../lib/cloud-rewrite.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..');
+const BIN = path.join(REPO_ROOT, 'bin', 'rdc-skills-mcp.mjs');
+const TEST_PORT = parseInt(process.env.TEST_PORT || '3197', 10);
+const LOCAL = `http://127.0.0.1:${TEST_PORT}`;
+const REMOTE_URL = 'https://rdc-skills.regendevcorp.com/mcp';
+const UA = 'Mozilla/5.0 (rdc-skills-test)';
+const DAEMON = '127.0.0.1:52437';
+
+// ── tiny assert harness ──────────────────────────────────────────────────────
+let pass = 0;
+let fail = 0;
+const failures = [];
+function check(name, cond, detail = '') {
+  if (cond) { pass++; }
+  else { fail++; failures.push(`${name}${detail ? ` — ${detail}` : ''}`); }
+}
+function strip(text) {
+  // The server prepends `<!-- rdc-skills: ... -->\n\n` to a rendered body.
+  return text.replace(/^<!--[^\n]*-->\n\n/, '');
+}
+
+// ── MCP-over-HTTP helper (stateless; SSE or JSON response) ───────────────────
+async function mcp(url, body) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json, text/event-stream',
+      'User-Agent': UA,
+    },
+    body: JSON.stringify(body),
+  });
+  const raw = await res.text();
+  if (raw.includes('data:')) {
+    let out = null;
+    for (const line of raw.split('\n')) {
+      if (line.startsWith('data:')) out = JSON.parse(line.slice(5).trim());
+    }
+    return { status: res.status, json: out };
+  }
+  return { status: res.status, json: raw ? JSON.parse(raw) : null };
+}
+function callText(json) {
+  return json?.result?.content?.[0]?.text ?? '';
+}
+
+// ── 1. UNIT ──────────────────────────────────────────────────────────────────
+function unitTests() {
+  const cat = listSkills();
+  check('unit: catalog non-empty', cat.length >= 20, `got ${cat.length}`);
+  check('unit: every entry has name+slash+category+summary field',
+    cat.every((s) => s.name && s.slash && s.category && 'summary' in s));
+  check('unit: every slash is rdc:<name> shape', cat.every((s) => /^rdc:/.test(s.slash)));
+  check('unit: getSkill(deploy) resolves', !!getSkill('deploy'));
+  check('unit: getSkill(nonexistent) is null', getSkill('___nope___') === null);
+  check('unit: search ranks exact name first', searchSkills('deploy')[0]?.name === 'deploy');
+  check('unit: empty search returns []', searchSkills('').length === 0);
+
+  // cloud-rewrite contract
+  const sample = '```bash\n_T=$(curl -s http://127.0.0.1:52437/v/coolify-api)\npm2 restart app\n```';
+  const rw = toCloudBody(sample);
+  check('unit: rewrite strips daemon URL', !rw.includes(DAEMON));
+  check('unit: rewrite mentions clauth MCP', rw.includes('clauth MCP'));
+  check('unit: rewrite flags CLI-only pm2', rw.includes('CLI-only'));
+  check('unit: rewrite guards empty input', toCloudBody('') === '');
+}
+
+// ── 2 & 3. shared per-skill sweep over an MCP endpoint ───────────────────────
+async function sweep(url, label, { compareSource }) {
+  // initialize
+  const init = await mcp(url, {
+    jsonrpc: '2.0', id: 1, method: 'initialize',
+    params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'rdc-skills-test', version: '1' } },
+  });
+  check(`${label}: initialize 200`, init.status === 200, `status ${init.status}`);
+  check(`${label}: serverInfo name`, init.json?.result?.serverInfo?.name === 'rdc-skills');
+
+  // tools/list
+  const tl = await mcp(url, { jsonrpc: '2.0', id: 2, method: 'tools/list' });
+  const toolNames = (tl.json?.result?.tools || []).map((t) => t.name).sort();
+  check(`${label}: exactly 3 expected tools`,
+    JSON.stringify(toolNames) === JSON.stringify(['rdc_skill_get', 'rdc_skill_list', 'rdc_skill_search']),
+    toolNames.join(','));
+
+  // rdc_skill_list
+  const sl = await mcp(url, { jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'rdc_skill_list', arguments: {} } });
+  let listed;
+  try { listed = JSON.parse(callText(sl.json)); } catch { listed = { count: 0, skills: [] }; }
+  const names = (listed.skills || []).map((s) => s.name);
+  check(`${label}: rdc_skill_list count matches`, listed.count === names.length && names.length >= 20, `count ${listed.count}`);
+  if (compareSource) {
+    check(`${label}: list names == local catalog`, JSON.stringify([...names].sort()) === JSON.stringify(skillNames().sort()));
+  }
+
+  // EVERY skill: fetch both variants, assert correctness + cloud contract.
+  let rewrittenCount = 0;
+  for (const name of names) {
+    const cloud = await mcp(url, { jsonrpc: '2.0', id: 10, method: 'tools/call', params: { name: 'rdc_skill_get', arguments: { name, variant: 'cloud' } } });
+    const cloudBody = strip(callText(cloud.json));
+    const cli = await mcp(url, { jsonrpc: '2.0', id: 11, method: 'tools/call', params: { name: 'rdc_skill_get', arguments: { name, variant: 'cli' } } });
+    const cliBody = strip(callText(cli.json));
+
+    check(`${label}: [${name}] cloud body non-empty`, cloudBody.length > 0);
+    check(`${label}: [${name}] cli body non-empty`, cliBody.length > 0);
+    // CLOUD CONTRACT — no daemon URL, for EVERY skill.
+    check(`${label}: [${name}] cloud has NO daemon URL`, !cloudBody.includes(DAEMON),
+      cloudBody.includes(DAEMON) ? 'leaked 127.0.0.1:52437' : '');
+
+    if (compareSource) {
+      // Correctness: the rendered bodies must equal the library's own output.
+      const expectedCli = getSkillBody(name);
+      const expectedCloud = getCloudOverride(name) ?? toCloudBody(expectedCli);
+      check(`${label}: [${name}] cli body == on-disk source`, cliBody === expectedCli);
+      check(`${label}: [${name}] cloud body == toCloudBody(source)/override`, cloudBody === expectedCloud);
+      if (expectedCli && expectedCli.includes(DAEMON)) rewrittenCount++;
+    }
+  }
+  if (compareSource) {
+    check(`${label}: at least one skill actually had a daemon URL rewritten`, rewrittenCount > 0, `rewritten ${rewrittenCount}`);
+  }
+
+  // error path
+  const unk = await mcp(url, { jsonrpc: '2.0', id: 20, method: 'tools/call', params: { name: 'rdc_skill_get', arguments: { name: '___nope___' } } });
+  check(`${label}: unknown skill returns helpful error`, /unknown skill/i.test(callText(unk.json)));
+
+  // search
+  const se = await mcp(url, { jsonrpc: '2.0', id: 21, method: 'tools/call', params: { name: 'rdc_skill_search', arguments: { query: 'deploy' } } });
+  let sr; try { sr = JSON.parse(callText(se.json)); } catch { sr = { results: [] }; }
+  check(`${label}: search returns ranked results`, (sr.results || []).length > 0 && sr.results[0].name);
+
+  return names.length;
+}
+
+// ── server lifecycle for integration ─────────────────────────────────────────
+async function waitHealth(url, tries = 40) {
+  for (let i = 0; i < tries; i++) {
+    try {
+      const r = await fetch(`${url}/health`);
+      if (r.status === 200) return await r.json();
+    } catch { /* not up yet */ }
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  throw new Error('server did not become healthy');
+}
+
+async function main() {
+  console.log('── unit ──');
+  unitTests();
+
+  console.log('── integration (spawned server) ──');
+  const proc = spawn('node', [BIN], { env: { ...process.env, PORT: String(TEST_PORT) }, stdio: 'ignore' });
+  let swept = 0;
+  try {
+    const health = await waitHealth(LOCAL);
+    check('integration: /health status ok', health.status === 'ok');
+    check('integration: /health skill count == catalog', health.skills === listSkills().length, `health ${health.skills} vs ${listSkills().length}`);
+    swept = await sweep(`${LOCAL}/mcp`, 'integration', { compareSource: true });
+    console.log(`   swept ${swept} skills (both variants)`);
+  } finally {
+    proc.kill();
+  }
+
+  if (process.env.REMOTE || process.argv.includes('--remote')) {
+    console.log('── systems (live tunnel) ──');
+    const n = await sweep(REMOTE_URL, 'systems', { compareSource: false });
+    console.log(`   swept ${n} skills over ${REMOTE_URL}`);
+  } else {
+    console.log('── systems skipped (set REMOTE=1 to sweep the live endpoint) ──');
+  }
+
+  console.log(`\nRESULTS: ${pass} passed, ${fail} failed`);
+  if (fail) {
+    console.log('FAILURES:');
+    for (const f of failures.slice(0, 40)) console.log(`  ✗ ${f}`);
+    process.exit(1);
+  }
+  console.log('✓ all green');
+  process.exit(0);
+}
+
+main().catch((e) => { console.error('test harness error:', e); process.exit(1); });