@vantageos/vantage-registry-mcp 1.2.0 → 1.5.0

package/server.js

@@ -0,0 +1,1732 @@
+#!/usr/bin/env bun
+
+// server.ts
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ConvexHttpClient } from "convex/browser";
+import { z } from "zod";
+
+// ../convex/_generated/api.js
+import { anyApi, componentsGeneric } from "convex/server";
+var api = anyApi;
+var components = componentsGeneric();
+
+// server.ts
+function loadConvexUrl() {
+  if (process.env.CONVEX_URL) {
+    return process.env.CONVEX_URL;
+  }
+  const envPath = resolve(import.meta.dirname ?? __dirname, "../.env.local");
+  try {
+    const raw = readFileSync(envPath, "utf-8");
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("CONVEX_URL=")) {
+        const value = trimmed.slice("CONVEX_URL=".length).split("#")[0].trim();
+        if (value) return value;
+      }
+    }
+  } catch {
+  }
+  throw new Error(
+    "CONVEX_URL not found. Set it as an environment variable or add it to .env.local"
+  );
+}
+var teamStatusSchema = z.enum(["active", "planned", "deprecated"]).describe("Team status");
+var agentStatusSchema = z.enum(["active", "draft", "deprecated"]).describe("Agent status");
+var skillStatusSchema = z.enum(["active", "draft", "deprecated"]).describe("Skill status");
+var pluginStatusSchema = z.enum(["active", "draft", "deprecated"]).describe("Plugin status");
+var hookStatusSchema = z.enum(["active", "dead", "deprecated"]).describe("Hook status");
+var sourceSchema = z.enum(["internal", "external", "plugin"]).describe(
+  "Component source \u2014 internal (our code), external (third-party), plugin (from plugin)"
+);
+var pluginSourceSchema = z.enum(["internal", "external"]).describe("Plugin source \u2014 internal or external");
+var skillCategorySchema = z.enum(["capability", "composite", "playbook", "root", "external"]).describe("Skill category type");
+var hookEventSchema = z.enum([
+  "PreToolUse",
+  "PostToolUse",
+  "SessionStart",
+  "SessionEnd",
+  "Stop",
+  "SubagentStop",
+  "PreCompact",
+  "Notification",
+  "UserPromptSubmit"
+]).describe("Hook lifecycle event");
+var runbookStatusSchema = z.enum(["draft", "published", "deprecated"]).describe("Runbook status");
+var templateTypeSchema = z.enum(["standard", "mission", "brief", "runbook", "document", "checklist"]).describe("Template type");
+var linkTypeSchema = z.enum(["uses", "produces", "references"]).describe(
+  "Link type \u2014 uses: template consumed during execution, produces: output document generated, references: informational cross-reference"
+);
+var convexUrl = loadConvexUrl();
+var convex = new ConvexHttpClient(convexUrl);
+var server = new McpServer({
+  name: "vantage-registry",
+  version: "1.5.0"
+});
+server.tool(
+  "upsert_team",
+  "Create or update a team in VantageRegistry. Upserts by name \u2014 if a team with the same name exists, it is updated.",
+  {
+    name: z.string().describe("Team name \u2014 e.g. 'core', 'geo', 'dev'"),
+    description: z.string().describe("What this team does"),
+    agentCount: z.number().int().describe("Number of agents in this team"),
+    skillCount: z.number().int().describe("Number of skills in this team"),
+    status: teamStatusSchema,
+    project: z.string().optional().describe("Associated project \u2014 e.g. 'vantage-starter'")
+  },
+  async (args) => {
+    const id = await convex.mutation(api.teams.upsert, args);
+    return {
+      content: [
+        { type: "text", text: JSON.stringify({ id, ...args }, null, 2) }
+      ]
+    };
+  }
+);
+server.tool(
+  "list_teams",
+  "List all teams in VantageRegistry. Optionally filter by status (active, planned, deprecated).",
+  {
+    status: teamStatusSchema.optional().describe("Filter by status \u2014 omit to list all")
+  },
+  async ({ status }) => {
+    const results = await convex.query(api.teams.list, { status });
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "get_team",
+  "Get a single team by its Convex document ID.",
+  {
+    id: z.string().describe("Convex document ID for the team")
+  },
+  async ({ id }) => {
+    const result = await convex.query(api.teams.get, { id });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "upsert_agent",
+  "Create or update an agent in VantageRegistry. Upserts by name+team \u2014 if an agent with the same name and team exists, it is updated.",
+  {
+    name: z.string().describe("Agent name \u2014 e.g. 'copywriter', 'strategy-researcher'"),
+    team: z.string().describe("Team this agent belongs to"),
+    description: z.string().describe("What this agent does"),
+    content: z.string().describe("Full agent definition content (markdown)"),
+    filePath: z.string().describe("File path relative to project root"),
+    lineCount: z.number().int().describe("Number of lines in the agent file"),
+    status: agentStatusSchema,
+    version: z.string().optional().describe("Semantic version \u2014 e.g. '1.0.0'"),
+    source: sourceSchema,
+    pricing: z.enum(["free", "paid"]).optional().describe("Pricing tier"),
+    price: z.number().optional().describe("Price in EUR (if paid)"),
+    license: z.string().optional().describe("License \u2014 e.g. 'MIT', 'proprietary'"),
+    publisherId: z.string().optional().describe("Publisher identifier"),
+    categories: z.array(z.string()).optional().describe("Categories beyond team name")
+  },
+  async (args) => {
+    const id = await convex.mutation(api.agents.upsert, args);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            { id, name: args.name, team: args.team },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  }
+);
+server.tool(
+  "list_agents",
+  "List all agents in VantageRegistry. Optionally filter by status, team, or category. fields='lite' returns compact {_id, name, team, status}. fields='full' returns the complete document including content.",
+  {
+    status: agentStatusSchema.optional().describe("Filter by status \u2014 omit to list all"),
+    team: z.string().optional().describe("Filter by team \u2014 e.g. 'dev', 'core'"),
+    category: z.string().optional().describe("Filter by category"),
+    fields: z.enum(["lite", "full"]).optional().describe(
+      "Projection: 'lite' (compact) or 'full' (complete document). Omit to use legacy summary behaviour."
+    ),
+    summary: z.boolean().optional().describe(
+      "Return summary only (no content). Default: true \u2014 legacy, prefer fields='lite'"
+    )
+  },
+  async ({ status, team, category, fields, summary }) => {
+    const results = await convex.query(api.agents.list, {
+      status,
+      team,
+      category,
+      fields,
+      summary
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "list_agents_by_team",
+  "List all agents belonging to a specific team.",
+  {
+    team: z.string().describe("Team name to filter by"),
+    summary: z.boolean().optional().describe("Return summary only (no content). Default: true")
+  },
+  async ({ team, summary }) => {
+    const results = await convex.query(api.agents.listByTeam, {
+      team,
+      summary
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "get_agent",
+  "Get a single agent by its Convex document ID.",
+  {
+    id: z.string().describe("Convex document ID for the agent")
+  },
+  async ({ id }) => {
+    const result = await convex.query(api.agents.get, { id });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "upsert_skill",
+  "Create or update a skill in VantageRegistry. Upserts by name+team \u2014 if a skill with the same name and team exists, it is updated.",
+  {
+    name: z.string().describe("Skill name \u2014 e.g. 'social-post', 'competitor-watch'"),
+    team: z.string().describe("Team this skill belongs to"),
+    category: skillCategorySchema,
+    description: z.string().describe("What this skill does \u2014 use pushy trigger descriptions"),
+    content: z.string().describe("Full SKILL.md content"),
+    filePath: z.string().describe("File path relative to project root"),
+    lineCount: z.number().int().describe("Number of lines in the skill file"),
+    status: skillStatusSchema,
+    version: z.string().optional().describe("Semantic version \u2014 e.g. '1.0.0'"),
+    source: sourceSchema,
+    pricing: z.enum(["free", "paid"]).optional().describe("Pricing tier"),
+    price: z.number().optional().describe("Price in EUR (if paid)"),
+    license: z.string().optional().describe("License \u2014 e.g. 'MIT', 'proprietary'"),
+    publisherId: z.string().optional().describe("Publisher identifier"),
+    categories: z.array(z.string()).optional().describe("Categories beyond team name")
+  },
+  async (args) => {
+    const id = await convex.mutation(api.skills.upsert, args);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            { id, name: args.name, team: args.team, category: args.category },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  }
+);
+server.tool(
+  "list_skills",
+  "List all skills in VantageRegistry. Optionally filter by status, team, or category. fields='lite' returns compact {_id, name, team, category, status}. fields='full' returns the complete document including content.",
+  {
+    status: skillStatusSchema.optional().describe("Filter by status \u2014 omit to list all"),
+    team: z.string().optional().describe("Filter by team \u2014 e.g. 'dev', 'core'"),
+    category: skillCategorySchema.optional().describe(
+      "Filter by category: capability, composite, playbook, root, or external"
+    ),
+    fields: z.enum(["lite", "full"]).optional().describe(
+      "Projection: 'lite' (compact) or 'full' (complete document). Omit to use legacy summary behaviour."
+    ),
+    summary: z.boolean().optional().describe(
+      "Return summary only (no content). Default: true \u2014 legacy, prefer fields='lite'"
+    )
+  },
+  async ({ status, team, category, fields, summary }) => {
+    const results = await convex.query(api.skills.list, {
+      status,
+      team,
+      category,
+      fields,
+      summary
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "list_skills_by_team",
+  "List all skills belonging to a specific team.",
+  {
+    team: z.string().describe("Team name to filter by"),
+    summary: z.boolean().optional().describe("Return summary only (no content). Default: true")
+  },
+  async ({ team, summary }) => {
+    const results = await convex.query(api.skills.listByTeam, {
+      team,
+      summary
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "list_skills_by_category",
+  "List all skills of a specific category (capability, composite, playbook, root, external).",
+  {
+    category: skillCategorySchema,
+    summary: z.boolean().optional().describe("Return summary only (no content). Default: true")
+  },
+  async ({ category, summary }) => {
+    const results = await convex.query(api.skills.listByCategory, {
+      category,
+      summary
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "get_skill",
+  "Get a single skill by its Convex document ID.",
+  {
+    id: z.string().describe("Convex document ID for the skill")
+  },
+  async ({ id }) => {
+    const result = await convex.query(api.skills.get, { id });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "get_skill_content",
+  "Fetch the VR-hosted canonical SKILL.md body for a skill. Returns content, sha256 hash, semver version, and last sync timestamp. Returns null fields if the skill has not been hosted in VR yet.",
+  {
+    name: z.string().describe("Skill slug \u2014 e.g. 'check-messages', 'blog-writer'")
+  },
+  async ({ name }) => {
+    const result = await convex.query(api.skillContentDb.getSkillContent, {
+      name
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "upsert_skill_content",
+  "Set or update the canonical SKILL.md body in VantageRegistry. Computes sha256; if content is unchanged from the stored version the call is idempotent (version is not bumped, only contentSyncedAt is updated). If content changed, patch version is bumped (X.Y.Z \u2192 X.Y.Z+1). First write sets version to '1.0.0'. If createIfMissing=true, auto-creates a placeholder skill row if it does not exist yet. Throws if the skill does not exist and createIfMissing is not set.",
+  {
+    name: z.string().describe("Skill slug \u2014 e.g. 'check-messages'"),
+    content: z.string().describe("Full SKILL.md body (frontmatter + markdown)"),
+    createIfMissing: z.boolean().optional().default(false).describe(
+      "Auto-create a placeholder skill row if it does not exist (default: false)"
+    )
+  },
+  async ({ name, content, createIfMissing }) => {
+    const result = await convex.mutation(
+      api.skillContentDb.upsertSkillContent,
+      {
+        name,
+        content,
+        createIfMissing
+      }
+    );
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "detect_skill_drift",
+  "Return the VR-side sha256 hash and filePath for each skill in scope. IMPORTANT: Convex queries have no filesystem access. This tool returns the VR canonical hash + stored filePath so the caller can compute disk SHA256 and compare. scope='all' (default) returns every skill. name=<slug> filters to a single skill.",
+  {
+    name: z.string().optional().describe("Skill slug \u2014 filter to a single skill"),
+    scope: z.string().optional().describe("'all' to return every skill (default when name is omitted)")
+  },
+  async ({ name, scope }) => {
+    const result = await convex.query(api.skillContentDb.detectSkillDrift, {
+      name,
+      scope
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "get_agent_content",
+  "Fetch the VR-hosted canonical agent content body for an agent. Returns content, sha256 hash, semver version, and last sync timestamp. Returns null fields if the agent has not been hosted in VR yet.",
+  {
+    name: z.string().describe("Agent slug \u2014 e.g. 'dev-convex-expert', 'dev-senior-dev'")
+  },
+  async ({ name }) => {
+    const result = await convex.query(api.agentContentDb.getAgentContent, {
+      name
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "upsert_agent_content",
+  "Set or update the canonical agent content body in VantageRegistry. Computes sha256; if content is unchanged the call is idempotent (version not bumped). If content changed, patch version is bumped (X.Y.Z \u2192 X.Y.Z+1). First write sets version to '1.0.0'. If createIfMissing=true, auto-creates a placeholder agent row if it does not exist yet. Throws if the agent does not exist and createIfMissing is not set.",
+  {
+    name: z.string().describe("Agent slug \u2014 e.g. 'dev-convex-expert'"),
+    content: z.string().describe("Full agent content body (AGENT.md or similar)"),
+    createIfMissing: z.boolean().optional().default(false).describe(
+      "Auto-create a placeholder agent row if it does not exist (default: false)"
+    )
+  },
+  async ({ name, content, createIfMissing }) => {
+    const result = await convex.mutation(
+      api.agentContentDb.upsertAgentContent,
+      {
+        name,
+        content,
+        createIfMissing
+      }
+    );
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "detect_agent_drift",
+  "Return the VR-side sha256 hash and filePath for each agent in scope. IMPORTANT: Convex queries have no filesystem access. This tool returns the VR canonical hash + stored filePath so the caller can compute disk SHA256 and compare. scope='all' (default) returns every agent. name=<slug> filters to a single agent.",
+  {
+    name: z.string().optional().describe("Agent slug \u2014 filter to a single agent"),
+    scope: z.string().optional().describe("'all' to return every agent (default when name is omitted)")
+  },
+  async ({ name, scope }) => {
+    const result = await convex.query(api.agentContentDb.detectAgentDrift, {
+      name,
+      scope
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "get_plugin_content",
+  "Fetch the VR-hosted canonical plugin content body for a plugin. Returns content, sha256 hash, semver version, and last sync timestamp. Returns null fields if the plugin has not been hosted in VR yet.",
+  {
+    name: z.string().describe("Plugin slug \u2014 e.g. 'perello-bootstrap', 'perello-identity'")
+  },
+  async ({ name }) => {
+    const result = await convex.query(api.pluginContentDb.getPluginContent, {
+      name
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "upsert_plugin_content",
+  "Set or update the canonical plugin content body in VantageRegistry. Computes sha256; if content is unchanged the call is idempotent (version not bumped). If content changed, patch version is bumped (X.Y.Z \u2192 X.Y.Z+1). First write sets version to '1.0.0'. If createIfMissing=true, auto-creates a placeholder plugin row if it does not exist yet. Throws if the plugin does not exist and createIfMissing is not set.",
+  {
+    name: z.string().describe("Plugin slug \u2014 e.g. 'perello-bootstrap'"),
+    content: z.string().describe("Full plugin content body"),
+    createIfMissing: z.boolean().optional().default(false).describe(
+      "Auto-create a placeholder plugin row if it does not exist (default: false)"
+    )
+  },
+  async ({ name, content, createIfMissing }) => {
+    const result = await convex.mutation(
+      api.pluginContentDb.upsertPluginContent,
+      {
+        name,
+        content,
+        createIfMissing
+      }
+    );
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "detect_plugin_drift",
+  "Return the VR-side sha256 hash and filePath for each plugin in scope. IMPORTANT: Convex queries have no filesystem access. This tool returns the VR canonical hash + stored filePath so the caller can compute disk SHA256 and compare. scope='all' (default) returns every plugin. name=<slug> filters to a single plugin.",
+  {
+    name: z.string().optional().describe("Plugin slug \u2014 filter to a single plugin"),
+    scope: z.string().optional().describe("'all' to return every plugin (default when name is omitted)")
+  },
+  async ({ name, scope }) => {
+    const result = await convex.query(api.pluginContentDb.detectPluginDrift, {
+      name,
+      scope
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "get_hook_content",
+  "Fetch the VR-hosted canonical hook content body for a hook. Returns content, sha256 hash, semver version, and last sync timestamp. Returns null fields if the hook has not been hosted in VR yet.",
+  {
+    name: z.string().describe("Hook slug \u2014 e.g. 'enforce-no-task-in-message', 'check-pii'")
+  },
+  async ({ name }) => {
+    const result = await convex.query(api.hookContentDb.getHookContent, {
+      name
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "upsert_hook_content",
+  "Set or update the canonical hook content body in VantageRegistry. Computes sha256; if content is unchanged the call is idempotent (version not bumped). If content changed, patch version is bumped (X.Y.Z \u2192 X.Y.Z+1). First write sets version to '1.0.0'. If createIfMissing=true, auto-creates a placeholder hook row if it does not exist yet (event defaults to 'PreToolUse' \u2014 update via upsert_hook afterward). Throws if the hook does not exist and createIfMissing is not set.",
+  {
+    name: z.string().describe("Hook slug \u2014 e.g. 'enforce-no-task-in-message'"),
+    content: z.string().describe("Full hook script content"),
+    createIfMissing: z.boolean().optional().default(false).describe(
+      "Auto-create a placeholder hook row if it does not exist (default: false)"
+    )
+  },
+  async ({ name, content, createIfMissing }) => {
+    const result = await convex.mutation(api.hookContentDb.upsertHookContent, {
+      name,
+      content,
+      createIfMissing
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "detect_hook_drift",
+  "Return the VR-side sha256 hash and filePath for each hook in scope. IMPORTANT: Convex queries have no filesystem access. This tool returns the VR canonical hash + stored filePath so the caller can compute disk SHA256 and compare. scope='all' (default) returns every hook. name=<slug> filters to a single hook.",
+  {
+    name: z.string().optional().describe("Hook slug \u2014 filter to a single hook"),
+    scope: z.string().optional().describe("'all' to return every hook (default when name is omitted)")
+  },
+  async ({ name, scope }) => {
+    const result = await convex.query(api.hookContentDb.detectHookDrift, {
+      name,
+      scope
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "get_command_content",
+  "Fetch the VR-hosted canonical command content body for a command. Returns content, sha256 hash, semver version, and last sync timestamp. Returns null fields if the command has not been hosted in VR yet.",
+  {
+    name: z.string().describe("Command slug \u2014 e.g. 'sync-workspace-from-vr', 'deploy-prod'")
+  },
+  async ({ name }) => {
+    const result = await convex.query(api.commandContentDb.getCommandContent, {
+      name
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "upsert_command_content",
+  "Set or update the canonical command content body in VantageRegistry. Computes sha256; if content is unchanged the call is idempotent (version not bumped). If content changed, patch version is bumped (X.Y.Z \u2192 X.Y.Z+1). First write sets version to '1.0.0'. Auto-creates the command document if it does not exist yet.",
+  {
+    name: z.string().describe("Command slug \u2014 e.g. 'sync-workspace-from-vr'"),
+    content: z.string().describe("Full command script content")
+  },
+  async ({ name, content }) => {
+    const result = await convex.mutation(
+      api.commandContentDb.upsertCommandContent,
+      {
+        name,
+        content
+      }
+    );
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "detect_command_drift",
+  "Return the VR-side sha256 hash and filePath for each command in scope. IMPORTANT: Convex queries have no filesystem access. This tool returns the VR canonical hash + stored filePath so the caller can compute disk SHA256 and compare. scope='all' (default) returns every command. name=<slug> filters to a single command.",
+  {
+    name: z.string().optional().describe("Command slug \u2014 filter to a single command"),
+    scope: z.string().optional().describe("'all' to return every command (default when name is omitted)")
+  },
+  async ({ name, scope }) => {
+    const result = await convex.query(api.commandContentDb.detectCommandDrift, {
+      name,
+      scope
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "upsert_plugin",
+  "Create or update a plugin in VantageRegistry. Upserts by name.",
+  {
+    name: z.string().describe("Plugin name \u2014 e.g. 'perello-bootstrap', 'perello-identity'"),
+    description: z.string().describe("What this plugin provides"),
+    agentCount: z.number().int().describe("Number of agents in this plugin"),
+    skillCount: z.number().int().describe("Number of skills in this plugin"),
+    hookCount: z.number().int().describe("Number of hooks in this plugin"),
+    source: pluginSourceSchema,
+    status: pluginStatusSchema,
+    version: z.string().optional().describe("Semantic version \u2014 e.g. '1.0.0'"),
+    filePath: z.string().optional().describe("Plugin directory path"),
+    pricing: z.enum(["free", "paid"]).optional().describe("Pricing tier"),
+    price: z.number().optional().describe("Price in EUR (if paid)"),
+    license: z.string().optional().describe("License \u2014 e.g. 'MIT', 'proprietary'"),
+    publisherId: z.string().optional().describe("Publisher identifier"),
+    categories: z.array(z.string()).optional().describe("Categories beyond team name")
+  },
+  async (args) => {
+    const id = await convex.mutation(api.plugins.upsert, args);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ id, name: args.name }, null, 2)
+        }
+      ]
+    };
+  }
+);
+server.tool(
+  "list_plugins",
+  "List all plugins in VantageRegistry. Optionally filter by status, source, or team. fields='lite' returns compact {_id, name, status, source}. fields='full' returns the complete document.",
+  {
+    status: pluginStatusSchema.optional().describe("Filter by status \u2014 omit to list all"),
+    source: pluginSourceSchema.optional().describe("Filter by source: 'internal' or 'external'"),
+    team: z.string().optional().describe("Filter by owning team"),
+    fields: z.enum(["lite", "full"]).optional().describe("Projection: 'lite' (compact) or 'full' (complete document)")
+  },
+  async ({ status, source, team, fields }) => {
+    const results = await convex.query(api.plugins.list, {
+      status,
+      source,
+      team,
+      fields
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "get_plugin",
+  "Get a single plugin by its Convex document ID.",
+  {
+    id: z.string().describe("Convex document ID for the plugin")
+  },
+  async ({ id }) => {
+    const result = await convex.query(api.plugins.get, { id });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "upsert_hook",
+  "Create or update a hook in VantageRegistry. Upserts by name.",
+  {
+    name: z.string().describe("Hook name \u2014 e.g. 'check-pii', 'enforce-skill-references'"),
+    event: hookEventSchema,
+    matcher: z.string().optional().describe("Tool matcher pattern \u2014 e.g. 'Bash', 'Agent'"),
+    description: z.string().describe("What this hook does"),
+    content: z.string().describe("Full hook script content"),
+    filePath: z.string().describe("File path relative to project root"),
+    registered: z.boolean().describe("Whether this hook is registered in settings.json"),
+    status: hookStatusSchema,
+    version: z.string().optional().describe("Semantic version \u2014 e.g. '1.0.0'")
+  },
+  async (args) => {
+    const id = await convex.mutation(api.hooks.upsert, args);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            { id, name: args.name, event: args.event },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  }
+);
+server.tool(
+  "list_hooks",
+  "List all hooks in VantageRegistry. Optionally filter by status or lifecycle event. fields='lite' returns compact {_id, name, status, event, registered}. fields='full' returns the complete document including content.",
+  {
+    status: hookStatusSchema.optional().describe("Filter by status \u2014 omit to list all"),
+    event: hookEventSchema.optional().describe(
+      "Filter by lifecycle event \u2014 e.g. 'PreToolUse', 'SessionStart'"
+    ),
+    fields: z.enum(["lite", "full"]).optional().describe(
+      "Projection: 'lite' (compact) or 'full' (complete document with content)"
+    )
+  },
+  async ({ status, event, fields }) => {
+    const results = await convex.query(api.hooks.list, {
+      status,
+      event,
+      fields
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "get_hook",
+  "Get a single hook by its Convex document ID.",
+  {
+    id: z.string().describe("Convex document ID for the hook")
+  },
+  async ({ id }) => {
+    const result = await convex.query(api.hooks.get, { id });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "upsert_prompt",
+  "Create or update a prompt in VantageRegistry. Upserts by name.",
+  {
+    name: z.string().describe("Prompt name \u2014 e.g. 'system-prompt', 'review-checklist'"),
+    team: z.string().optional().describe("Team this prompt belongs to \u2014 defaults to 'global'"),
+    purpose: z.string().describe("What this prompt is used for"),
+    content: z.string().describe("Full prompt content"),
+    version: z.string().optional().describe("Semantic version \u2014 e.g. '1.0.0'")
+  },
+  async (args) => {
+    const id = await convex.mutation(api.prompts.upsert, args);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ id, name: args.name }, null, 2)
+        }
+      ]
+    };
+  }
+);
+server.tool(
+  "list_prompts",
+  "List all prompts in VantageRegistry. Optionally filter by team.",
+  {
+    team: z.string().optional().describe("Filter by team \u2014 omit to list all")
+  },
+  async ({ team }) => {
+    const results = await convex.query(api.prompts.list, { team });
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "get_prompt",
+  "Get a single prompt by its Convex document ID.",
+  {
+    id: z.string().describe("Convex document ID for the prompt")
+  },
+  async ({ id }) => {
+    const result = await convex.query(api.prompts.get, { id });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "upsert_template",
+  "Create or update a template in VantageRegistry. Upserts by name. contentHash is auto-computed server-side (sha256 of content) when omitted.",
+  {
+    name: z.string().describe("Template name \u2014 e.g. 'agent-brief', 'skill-md'"),
+    team: z.string().optional().describe("Team this template belongs to \u2014 defaults to 'global'"),
+    purpose: z.string().describe("What this template is used for"),
+    content: z.string().describe("Full template content"),
+    version: z.string().optional().describe("Semantic version \u2014 e.g. '1.0.0'"),
+    template_type: templateTypeSchema.optional().describe(
+      "Template type: standard, mission, brief, runbook, document, or checklist"
+    ),
+    category: z.string().optional().describe("Category \u2014 e.g. 'standards/fleet-shared'"),
+    contentHash: z.string().optional().describe("sha256 of content \u2014 auto-computed server-side when omitted"),
+    sourceCommit: z.string().optional().describe("Git commit SHA the template content was sourced from"),
+    sourceRepo: z.string().optional().describe("Git repo the template content was sourced from")
+  },
+  async (args) => {
+    const id = await convex.mutation(api.templates.upsert, args);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ id, name: args.name }, null, 2)
+        }
+      ]
+    };
+  }
+);
+server.tool(
+  "list_templates",
+  "List all templates in VantageRegistry. Optionally filter by team and/or template_type.",
+  {
+    team: z.string().optional().describe("Filter by team \u2014 omit to list all"),
+    template_type: templateTypeSchema.optional().describe("Filter by template type: mission, document, or checklist")
+  },
+  async ({ team, template_type }) => {
+    const results = await convex.query(api.templates.list, {
+      team,
+      template_type
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "get_template",
+  "Get a single template by its Convex document ID.",
+  {
+    id: z.string().describe("Convex document ID for the template")
+  },
+  async ({ id }) => {
+    const result = await convex.query(api.templates.get, { id });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "detect_template_drift",
+  "Return the VR-side sha256 contentHash + provenance (sourceCommit, sourceRepo) for each template in scope. IMPORTANT: Convex queries have no filesystem access. This tool returns the VR canonical contentHash so the caller can read the source file, compute its SHA256, and compare. name=<slug> filters to a single template; omit name to return every template.",
+  {
+    name: z.string().optional().describe("Template slug \u2014 filter to a single template")
+  },
+  async ({ name }) => {
+    const result = await convex.query(api.templates.detectTemplateDrift, {
+      name
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "list_templates_by_category",
+  "List templates for a specific category using the byCategory index.",
+  {
+    category: z.string().describe("Category to filter by \u2014 e.g. 'standards/fleet-shared'")
+  },
+  async ({ category }) => {
+    const result = await convex.query(api.templates.listTemplatesByCategory, {
+      category
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "upsert_test_run",
+  "Insert a skill quality test run and update denormalized quality fields on the parent skill (lastTestedAt, lastReviewerScore, lastEvalDelta, testStatus). reviewerScore format is 'X/Y' e.g. '37/45'. evalDelta is pp delta vs without-skill baseline.",
+  {
+    skillId: z.string().describe("Convex document ID of the skill being tested"),
+    runDate: z.number().describe("Unix timestamp (ms) when the run was executed"),
+    runByOrchestrator: z.string().describe("Orchestrator that ran the test \u2014 e.g. 'alpha', 'pi'"),
+    runByMission: z.string().optional().describe("Mission reference \u2014 e.g. 'D70'"),
+    reviewerScore: z.string().describe("Score as 'X/Y' \u2014 e.g. '37/45'"),
+    evalDelta: z.number().describe("Percentage-point delta vs without-skill baseline"),
+    evalAbsoluteWith: z.number().describe("Absolute score with skill (0-100)"),
+    evalAbsoluteWithout: z.number().describe("Absolute score without skill (0-100)"),
+    runnerModel: z.string().describe("Model used to run the skill \u2014 e.g. 'claude-sonnet-4-6'"),
+    judgeModel: z.string().describe("Model used as judge \u2014 e.g. 'claude-haiku-4-5'"),
+    corpusVersion: z.string().describe("Eval corpus version used \u2014 e.g. '2.0.0'"),
+    harnessVersion: z.string().describe("Test harness version \u2014 e.g. '0.1.0'"),
+    skillSha: z.string().describe("Git SHA of the skill file at test time"),
+    gradingJsonPath: z.string().optional().describe("Path to grading output JSON"),
+    benchmarkJsonPath: z.string().optional().describe("Path to benchmark output JSON"),
+    reportPath: z.string().optional().describe("Path to human-readable report"),
+    timeSpentMinutes: z.number().optional().describe("Time spent running the test in minutes"),
+    notes: z.string().optional().describe("Free-form notes about this run"),
+    testStatus: z.enum(["untested", "tested", "needs_retest", "improving", "untestable"]).optional().describe("Override test status \u2014 defaults to 'tested'")
+  },
+  async (args) => {
+    const id = await convex.mutation(api.skillTestRuns.upsertTestRun, {
+      ...args,
+      skillId: args.skillId
+    });
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            { id, skillId: args.skillId, runDate: args.runDate },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  }
+);
+server.tool(
+  "get_skill_test_history",
+  "Return test run history for a skill, ordered newest-first.",
+  {
+    skillId: z.string().describe("Convex document ID of the skill"),
+    limit: z.number().optional().describe("Max number of runs to return \u2014 defaults to 50")
+  },
+  async ({ skillId, limit }) => {
+    const results = await convex.query(api.skillTestRuns.getSkillTestHistory, {
+      skillId,
+      limit
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "list_skills_by_freshness",
+  "Return skills that have never been tested or were last tested more than staleDays ago. Use this to find skills that need a quality test run. Defaults to fields='lite' (bounded output) to stay under MCP token cap. Use fields='full' to retrieve complete skill documents.",
+  {
+    staleDays: z.number().describe("Number of days since last test run to consider stale"),
+    fields: z.enum(["lite", "full"]).optional().default("lite").describe(
+      "Projection: 'lite' (default, compact \u2014 bounded output) or 'full' (complete document)"
+    ),
+    limit: z.number().int().optional().describe("Max results \u2014 defaults to 100, max 500")
+  },
+  async ({ staleDays, fields, limit }) => {
+    const results = await convex.query(
+      api.skillTestRuns.listSkillsByFreshness,
+      { staleDays, fields, limit }
+    );
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "list_skills_below_threshold",
+  "Return skills whose last test run was below a score ratio (scoreMin as 0-1 fraction of 'X/Y') or below a delta threshold (deltaMin in pp). Omit a param to skip that filter. fields='lite' returns compact output. fields='full' returns complete skill documents.",
+  {
+    scoreMin: z.number().optional().describe(
+      "Minimum acceptable score ratio (0-1). Skills below this are returned."
+    ),
+    deltaMin: z.number().optional().describe(
+      "Minimum acceptable eval delta in pp. Skills below this are returned."
+    ),
+    fields: z.enum(["lite", "full"]).optional().describe(
+      "Projection: 'lite' (compact) or 'full' (complete document). Omit for full (backward compat)."
+    )
+  },
+  async ({ scoreMin, deltaMin, fields }) => {
+    const results = await convex.query(
+      api.skillTestRuns.listSkillsBelowThreshold,
+      { scoreMin, deltaMin, fields }
+    );
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+);
+server.tool(
+  "upsert_skill_eval_corpus",
+  "Insert or update an eval corpus version for a skill. Upserts by (skillId, version).",
+  {
+    skillId: z.string().describe("Convex document ID of the skill"),
+    version: z.string().describe("Corpus version \u2014 e.g. '2.0.0'"),
+    casesCount: z.number().int().describe("Number of eval cases"),
+    assertionsCount: z.number().int().describe("Total number of assertions across all cases"),
+    baselinePrompt: z.string().describe("The baseline prompt used without the skill"),
+    evalsJsonContent: z.string().describe("Full JSON content of the evals file, or '{}' as placeholder"),
+    authoredBy: z.string().describe("Orchestrator or person who authored this corpus"),
+    authoredAt: z.number().describe("Unix timestamp (ms) when the corpus was authored"),
+    supersedesVersion: z.string().optional().describe("Version this corpus supersedes \u2014 e.g. '1.0.0'")
+  },
+  async (args) => {
+    const id = await convex.mutation(
+      api.skillEvalCorpus.upsertSkillEvalCorpus,
+      {
+        ...args,
+        skillId: args.skillId
+      }
+    );
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            { id, skillId: args.skillId, version: args.version },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  }
+);
+var phaseSchema = z.object({
+  name: z.string().describe("Phase name"),
+  description: z.string().describe("What this phase accomplishes"),
+  steps: z.array(z.string()).describe("Ordered list of steps in this phase")
+});
+var runbookInputSchema = z.object({
+  name: z.string().describe("Input parameter name"),
+  type: z.string().describe("Input type \u2014 e.g. 'string', 'boolean'"),
+  required: z.boolean().describe("Whether this input is required"),
+  description: z.string().describe("What this input controls")
+});
+var runbookOutputSchema = z.object({
+  name: z.string().describe("Output artifact name"),
+  description: z.string().describe("What this output contains"),
+  path_pattern: z.string().optional().describe("File path pattern \u2014 e.g. 'reports/{name}.md'")
+});
+var applicabilitySchema = z.object({
+  orchestrators: z.array(z.string()).describe("Orchestrator slugs this runbook applies to"),
+  business_units: z.array(z.string()).describe("Business unit slugs this runbook applies to"),
+  use_cases: z.array(z.string()).describe("Use case slugs this runbook applies to")
+});
+var linkedTemplateSchema = z.object({
+  name: z.string().describe("Template name"),
+  template_type: z.string().describe("Template type \u2014 mission, document, or checklist"),
+  version: z.string().describe("Template version \u2014 e.g. '1.0.0'"),
+  usage_phase: z.string().describe("Phase name where this template is used"),
+  required: z.boolean().describe("Whether this template is required for the runbook"),
+  description: z.string().describe("How this template is used in this runbook")
+});
+server.tool(
+  "upsert_runbook",
+  "Create or update a runbook in VantageRegistry. Upserts by name \u2014 if a runbook with the same name exists, it is updated.",
+  {
+    name: z.string().describe("Runbook slug \u2014 e.g. 'deploy-production', 'onboard-agent'"),
+    description: z.string().describe("What this runbook accomplishes"),
+    version: z.string().describe("Semantic version \u2014 e.g. '1.0.0'"),
+    status: runbookStatusSchema,
+    category: z.string().describe("Category \u2014 e.g. 'deployment', 'onboarding', 'quality'"),
+    tags: z.array(z.string()).describe("Searchable tags"),
+    content: z.string().describe("Full runbook content (markdown)"),
+    phases: z.array(phaseSchema).describe("Ordered phases of the runbook"),
+    inputs: z.array(runbookInputSchema).describe("Input parameters for the runbook"),
+    outputs: z.array(runbookOutputSchema).describe("Output artifacts produced by the runbook"),
+    applicability: applicabilitySchema,
+    author: z.string().describe("Author slug \u2014 e.g. 'omega'"),
+    team: z.string().describe("Owning team slug \u2014 e.g. 'core', 'dev'"),
+    related_skills: z.array(z.string()).describe("Skill slugs referenced by this runbook"),
+    related_agents: z.array(z.string()).describe("Agent slugs referenced by this runbook"),
+    linked_templates: z.array(linkedTemplateSchema).describe("Templates used during this runbook")
+  },
+  async (args) => {
+    try {
+      const result = await convex.mutation(api.runbooks.upsertRunbook, args);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: true, data: result }, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "get_runbook",
+  "Get a single runbook by name. Optionally guard by exact version.",
+  {
+    name: z.string().describe("Runbook slug \u2014 e.g. 'deploy-production'"),
+    version: z.string().optional().describe("If provided, returns null when stored version differs")
+  },
+  async ({ name, version }) => {
+    try {
+      const result = await convex.query(api.runbooks.getRunbook, {
+        name,
+        version
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: true, data: result }, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "list_runbooks",
+  "List runbooks in VantageRegistry. Defaults to published status. Supports applicability filters.",
+  {
+    status: runbookStatusSchema.optional().describe("Filter by status \u2014 defaults to 'published'"),
+    category: z.string().optional().describe("Filter by category \u2014 e.g. 'deployment'"),
+    team: z.string().optional().describe("Filter by owning team"),
+    applicability_orchestrator: z.string().optional().describe("Filter by orchestrator slug in applicability"),
+    applicability_bu: z.string().optional().describe("Filter by business unit slug in applicability"),
+    applicability_use_case: z.string().optional().describe("Filter by use case slug in applicability"),
+    limit: z.number().int().optional().describe("Max results to return \u2014 defaults to 50, max 200")
+  },
+  async (args) => {
+    try {
+      const result = await convex.query(api.runbooks.listRunbooks, args);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: true, data: result }, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "list_runbooks_by_category",
+  "List runbooks for a specific category using the byCategory index.",
+  {
+    category: z.string().describe("Category to filter by \u2014 e.g. 'deployment', 'quality'"),
+    status: runbookStatusSchema.optional().describe(
+      "Filter by status \u2014 omit to list all statuses in this category"
+    )
+  },
+  async ({ category, status }) => {
+    try {
+      const result = await convex.query(api.runbooks.listRunbooksByCategory, {
+        category,
+        status
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: true, data: result }, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "list_runbooks_by_team",
+  "List runbooks for a specific team using the byTeam index.",
+  {
+    team: z.string().describe("Team slug to filter by \u2014 e.g. 'core', 'dev'"),
+    status: runbookStatusSchema.optional().describe("Filter by status \u2014 omit to list all statuses for this team")
+  },
+  async ({ team, status }) => {
+    try {
+      const result = await convex.query(api.runbooks.listRunbooksByTeam, {
+        team,
+        status
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: true, data: result }, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "delete_runbook",
+  "Soft-delete a runbook by name \u2014 sets status to 'deprecated'. Returns {deleted: true} if found, {deleted: false} if not found.",
+  {
+    name: z.string().describe("Runbook slug to soft-delete")
+  },
+  async ({ name }) => {
+    try {
+      const result = await convex.mutation(api.runbooks.deleteRunbook, {
+        name
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: true, data: result }, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "link_runbook_template",
+  "Create or update a typed link between a runbook and a template in the runbook_template_links junction table. Upserts by (runbookId, templateId) pair \u2014 at-most-one link per pair. linkType controls the relationship semantics: 'uses' = template consumed during execution, 'produces' = output document generated by this runbook, 'references' = informational cross-reference. Returns {linkId, created: true} on insert or {linkId, created: false} on update.",
+  {
+    runbookId: z.string().describe("Convex document ID for the runbook"),
+    templateId: z.string().describe("Convex document ID for the template"),
+    linkType: linkTypeSchema,
+    usagePhase: z.string().optional().describe(
+      "Phase name where this template is used \u2014 kebab-case convention e.g. 'bootstrap', 'audit-phase-2'"
+    ),
+    order: z.number().optional().describe(
+      "Sort order for template lists \u2014 lower numbers appear first (null items sorted last)"
+    ),
+    createdBy: z.string().optional().describe("Orchestrator or person creating this link \u2014 e.g. 'omega'")
+  },
+  async (args) => {
+    try {
+      const result = await convex.mutation(
+        api.runbookTemplateLinks.linkRunbookTemplate,
+        {
+          runbookId: args.runbookId,
+          templateId: args.templateId,
+          linkType: args.linkType,
+          usagePhase: args.usagePhase,
+          order: args.order,
+          createdBy: args.createdBy
+        }
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: true, data: result }, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "unlink_runbook_template",
+  "Hard-delete the typed link between a runbook and a template. Links have no lifecycle state \u2014 they either exist or they don't (no soft-delete). Returns {unlinked: true} if the link was found and deleted, {unlinked: false} if the pair was not linked.",
+  {
+    runbookId: z.string().describe("Convex document ID for the runbook"),
+    templateId: z.string().describe("Convex document ID for the template")
+  },
+  async (args) => {
+    try {
+      const result = await convex.mutation(
+        api.runbookTemplateLinks.unlinkRunbookTemplate,
+        {
+          runbookId: args.runbookId,
+          templateId: args.templateId
+        }
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: true, data: result }, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "list_templates_for_runbook",
+  "List all templates linked to a runbook, with enriched template metadata. Returns enriched [{link, template}] objects sorted by link.order ASC then link.createdAt ASC. Optionally filter by linkType ('uses', 'produces', or 'references'). Orphaned links (template deleted) are automatically skipped.",
+  {
+    runbookId: z.string().describe("Convex document ID for the runbook"),
+    linkType: linkTypeSchema.optional().describe(
+      "Filter by link type \u2014 omit to return all link types for this runbook"
+    )
+  },
+  async (args) => {
+    try {
+      const result = await convex.query(
+        api.runbookTemplateLinks.listTemplatesForRunbook,
+        {
+          runbookId: args.runbookId,
+          linkType: args.linkType
+        }
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: true, data: result }, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "list_runbooks_for_template",
+  "List all runbooks linked to a template (reverse lookup), with enriched runbook metadata. Symmetric reverse of list_templates_for_runbook \u2014 uses the byTemplate index. Returns enriched [{link, runbook}] objects sorted by link.order ASC then link.createdAt ASC. Optionally filter by linkType ('uses', 'produces', or 'references'). Orphaned links (runbook deleted) are automatically skipped.",
+  {
+    templateId: z.string().describe("Convex document ID for the template"),
+    linkType: linkTypeSchema.optional().describe(
+      "Filter by link type \u2014 omit to return all link types for this template"
+    )
+  },
+  async (args) => {
+    try {
+      const result = await convex.query(
+        api.runbookTemplateLinks.listRunbooksForTemplate,
+        {
+          templateId: args.templateId,
+          linkType: args.linkType
+        }
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: true, data: result }, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+var componentKindSchema = z.enum(["skill", "agent", "hook", "plugin", "prompt", "runbook", "template"]).describe("Component kind");
+var componentStatusSchema = z.enum(["active", "deprecated", "experimental"]).describe("Component status");
+server.tool(
+  "register_component",
+  "Create or update a component in the VantageRegistry components catalog. Upserts by name+kind \u2014 if a component with the same name and kind exists it is updated. Use this to register any VantageOS primitive: skill, agent, hook, plugin, prompt, runbook, or template.",
+  {
+    name: z.string().describe(
+      "Component name slug \u2014 e.g. 'check-messages', 'dev-convex-expert'"
+    ),
+    kind: componentKindSchema,
+    status: componentStatusSchema,
+    ownerTeam: z.string().optional().describe("Team that owns this component \u2014 e.g. 'core', 'dev'"),
+    description: z.string().optional().describe("Short description of what this component does"),
+    vrEntityId: z.string().optional().describe("ID of the backing VR entity (skill _id, agent _id, etc.)"),
+    metadata: z.record(z.string(), z.unknown()).optional().describe("Arbitrary metadata bag \u2014 store extra fields here"),
+    tags: z.array(z.string()).optional().describe("Searchable tags \u2014 e.g. ['ai', 'backend']")
+  },
+  async (args) => {
+    try {
+      const id = await convex.mutation(api.components.registerComponent, args);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { id, name: args.name, kind: args.kind },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "list_components",
+  "List components in the VantageRegistry catalog. Supports filtering by kind, ownerTeam, status, and tags. fields='lite' (default) returns compact {_id, name, kind, status, ownerTeam}. fields='full' returns the complete document including description, tags, metadata, vrEntityId. limit defaults to 100, max 500.",
+  {
+    kind: componentKindSchema.optional().describe("Filter by kind \u2014 omit to return all kinds"),
+    ownerTeam: z.string().optional().describe("Filter by owning team"),
+    status: componentStatusSchema.optional().describe("Filter by status \u2014 omit to return all statuses"),
+    tags: z.array(z.string()).optional().describe("Filter by tags \u2014 ALL specified tags must match"),
+    fields: z.enum(["lite", "full"]).optional().describe("Projection: 'lite' (default) or 'full'"),
+    limit: z.number().int().optional().describe("Max results \u2014 defaults to 100, max 500")
+  },
+  async ({ kind, ownerTeam, status, tags, fields, limit }) => {
+    try {
+      const filter = kind !== void 0 || ownerTeam !== void 0 || status !== void 0 || tags !== void 0 ? { kind, ownerTeam, status, tags } : void 0;
+      const results = await convex.query(api.components.listComponents, {
+        filter,
+        fields,
+        limit
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "get_component",
+  "Get a single component by its Convex document ID. Returns the full document or null if not found.",
+  {
+    id: z.string().describe("Convex document ID of the component")
+  },
+  async ({ id }) => {
+    try {
+      const result = await convex.query(api.components.getComponent, {
+        id
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "search_components",
+  "Search components by name prefix. Returns up to `limit` lite results whose name starts with the query string. Case-sensitive index range scan. Use list_components with filters for kind/status/tags filtering.",
+  {
+    query: z.string().describe("Name prefix to search for \u2014 e.g. 'check', 'dev-'"),
+    limit: z.number().int().optional().describe("Max results \u2014 defaults to 50, max 200")
+  },
+  async ({ query, limit }) => {
+    try {
+      const results = await convex.query(api.components.searchComponents, {
+        query,
+        limit
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "update_component",
+  "Patch individual fields on an existing component. Only provided fields are updated. Throws if not found.",
+  {
+    id: z.string().describe("Convex document ID of the component to update"),
+    name: z.string().optional().describe("New name slug"),
+    kind: componentKindSchema.optional().describe("New kind"),
+    ownerTeam: z.string().optional().describe("New owning team"),
+    description: z.string().optional().describe("New description"),
+    status: componentStatusSchema.optional().describe("New status"),
+    vrEntityId: z.string().optional().describe("Updated vrEntityId reference"),
+    metadata: z.record(z.string(), z.unknown()).optional().describe("Updated metadata bag"),
+    tags: z.array(z.string()).optional().describe("Updated tags array")
+  },
+  async (args) => {
+    try {
+      await convex.mutation(api.components.updateComponent, {
+        ...args,
+        id: args.id
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: true, id: args.id }, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "delete_component",
+  "Soft-delete a component by ID \u2014 sets status to 'deprecated'. The document remains in the database and is still retrievable. Returns {deleted: true} if found, {deleted: false} if not found.",
+  {
+    id: z.string().describe("Convex document ID of the component to soft-delete")
+  },
+  async ({ id }) => {
+    try {
+      const result = await convex.mutation(api.components.deleteComponent, {
+        id
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: true, ...result }, null, 2)
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { success: false, error: String(err) },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  }
+);
+server.tool(
+  "get_stats",
+  "Get counts per table in VantageRegistry \u2014 teams, agents, skills, plugins, hooks, and runbooks. Runbooks include breakdown by_status (draft/published/deprecated) and by_category. Use this to get a quick overview of the registry contents.",
+  {},
+  async () => {
+    const [
+      teams,
+      agents,
+      skills,
+      plugins,
+      hooks,
+      rbDraft,
+      rbPublished,
+      rbDeprecated
+    ] = await Promise.all([
+      convex.query(api.teams.list, {}),
+      convex.query(api.agents.list, {}),
+      convex.query(api.skills.list, {}),
+      convex.query(api.plugins.list, {}),
+      convex.query(api.hooks.list, {}),
+      convex.query(api.runbooks.listRunbooks, { status: "draft", limit: 1e3 }),
+      convex.query(api.runbooks.listRunbooks, {
+        status: "published",
+        limit: 1e3
+      }),
+      convex.query(api.runbooks.listRunbooks, {
+        status: "deprecated",
+        limit: 1e3
+      })
+    ]);
+    const byCategoryMap = {};
+    for (const rb of [...rbDraft, ...rbPublished, ...rbDeprecated]) {
+      byCategoryMap[rb.category] = (byCategoryMap[rb.category] ?? 0) + 1;
+    }
+    const runbooksTotal = rbDraft.length + rbPublished.length + rbDeprecated.length;
+    const stats = {
+      teams: teams.length,
+      agents: agents.length,
+      skills: skills.length,
+      plugins: plugins.length,
+      hooks: hooks.length,
+      runbooks_count: {
+        total: runbooksTotal,
+        by_status: {
+          draft: rbDraft.length,
+          published: rbPublished.length,
+          deprecated: rbDeprecated.length
+        },
+        by_category: byCategoryMap
+      },
+      total: teams.length + agents.length + skills.length + plugins.length + hooks.length + runbooksTotal
+    };
+    return {
+      content: [{ type: "text", text: JSON.stringify(stats, null, 2) }]
+    };
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("VantageRegistry MCP server running on stdio");
+}
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});