@vantageos/vantage-registry-mcp 1.1.0

package/server.ts

@@ -0,0 +1,1267 @@
+#!/usr/bin/env bun
+/**
+ * VantageRegistry MCP Server
+ * Exposes Convex registry functions as Claude Code tools via stdio transport.
+ *
+ * Tools:
+ *   upsert_team, list_teams, get_team
+ *   upsert_agent, list_agents, list_agents_by_team, get_agent
+ *   upsert_skill, list_skills, list_skills_by_team, list_skills_by_category, get_skill
+ *   upsert_plugin, list_plugins, get_plugin
+ *   upsert_hook, list_hooks, get_hook
+ *   upsert_prompt, list_prompts, get_prompt
+ *   upsert_template, list_templates, get_template
+ *   upsert_runbook, get_runbook, list_runbooks, list_runbooks_by_category, list_runbooks_by_team, delete_runbook
+ *   get_stats
+ *
+ * Orchestrator: Omega — VantageOS Team | 2026-05-19
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ConvexHttpClient } from "convex/browser";
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import { z } from "zod";
+import { api } from "../convex/_generated/api.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Bootstrap: resolve CONVEX_URL from env or .env.local
+// ─────────────────────────────────────────────────────────────────────────────
+
+function loadConvexUrl(): string {
+	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 {
+		// .env.local not found — fall through to error
+	}
+
+	throw new Error(
+		"CONVEX_URL not found. Set it as an environment variable or add it to .env.local",
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Shared Zod schemas
+// ─────────────────────────────────────────────────────────────────────────────
+
+const teamStatusSchema = z
+	.enum(["active", "planned", "deprecated"])
+	.describe("Team status");
+
+const agentStatusSchema = z
+	.enum(["active", "draft", "deprecated"])
+	.describe("Agent status");
+
+const skillStatusSchema = z
+	.enum(["active", "draft", "deprecated"])
+	.describe("Skill status");
+
+const pluginStatusSchema = z
+	.enum(["active", "draft", "deprecated"])
+	.describe("Plugin status");
+
+const hookStatusSchema = z
+	.enum(["active", "dead", "deprecated"])
+	.describe("Hook status");
+
+const sourceSchema = z
+	.enum(["internal", "external", "plugin"])
+	.describe("Component source — internal (our code), external (third-party), plugin (from plugin)");
+
+const pluginSourceSchema = z
+	.enum(["internal", "external"])
+	.describe("Plugin source — internal or external");
+
+const skillCategorySchema = z
+	.enum(["capability", "composite", "playbook", "root", "external"])
+	.describe("Skill category type");
+
+const hookEventSchema = z
+	.enum([
+		"PreToolUse",
+		"PostToolUse",
+		"SessionStart",
+		"SessionEnd",
+		"Stop",
+		"SubagentStop",
+		"PreCompact",
+		"Notification",
+		"UserPromptSubmit",
+	])
+	.describe("Hook lifecycle event");
+
+const runbookStatusSchema = z
+	.enum(["draft", "published", "deprecated"])
+	.describe("Runbook status");
+
+const templateTypeSchema = z
+	.enum(["mission", "document", "checklist"])
+	.describe("Template type");
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Server setup
+// ─────────────────────────────────────────────────────────────────────────────
+
+const convexUrl = loadConvexUrl();
+const convex = new ConvexHttpClient(convexUrl);
+
+const server = new McpServer({
+	name: "vantage-registry",
+	version: "1.1.0",
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TEAMS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+server.tool(
+	"upsert_team",
+	"Create or update a team in VantageRegistry. Upserts by name — if a team with the same name exists, it is updated.",
+	{
+		name: z.string().describe("Team name — 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 — 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 — 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: id as any });
+		return {
+			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+		};
+	},
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// AGENTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+server.tool(
+	"upsert_agent",
+	"Create or update an agent in VantageRegistry. Upserts by name+team — if an agent with the same name and team exists, it is updated.",
+	{
+		name: z.string().describe("Agent name — 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 — 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 — 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.",
+	{
+		status: agentStatusSchema.optional().describe("Filter by status — omit to list all"),
+		summary: z.boolean().optional().describe("Return summary only (no content). Default: true"),
+	},
+	async ({ status, summary }) => {
+		const results = await convex.query(api.agents.list, { status, 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: id as any });
+		return {
+			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+		};
+	},
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SKILLS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+server.tool(
+	"upsert_skill",
+	"Create or update a skill in VantageRegistry. Upserts by name+team — if a skill with the same name and team exists, it is updated.",
+	{
+		name: z.string().describe("Skill name — 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 — 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 — 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 — 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.",
+	{
+		status: skillStatusSchema.optional().describe("Filter by status — omit to list all"),
+		summary: z.boolean().optional().describe("Return summary only (no content). Default: true"),
+	},
+	async ({ status, summary }) => {
+		const results = await convex.query(api.skills.list, { status, 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: id as any });
+		return {
+			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+		};
+	},
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SKILL CONTENT — VR Single-Source-of-Truth (D72-VR-SoT)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+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 — 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 → 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 — 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 — 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) }],
+		};
+	},
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// AGENT CONTENT — VR Single-Source-of-Truth (D72-VR-SoT Phase A)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+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 — 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 → 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 — 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 — 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) }],
+		};
+	},
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// PLUGIN CONTENT — VR Single-Source-of-Truth (D72-VR-SoT Phase A)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+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 — 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 → 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 — 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 — 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) }],
+		};
+	},
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HOOK CONTENT — VR Single-Source-of-Truth (D72-VR-SoT Phase A)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+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 — 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 → 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' — update via upsert_hook afterward). " +
+		"Throws if the hook does not exist and createIfMissing is not set.",
+	{
+		name: z.string().describe("Hook slug — 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 — 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) }],
+		};
+	},
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// COMMAND CONTENT — VR Single-Source-of-Truth (D72-VR-SoT Phase A)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+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 — 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 → 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 — 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 — 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) }],
+		};
+	},
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// PLUGINS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+server.tool(
+	"upsert_plugin",
+	"Create or update a plugin in VantageRegistry. Upserts by name.",
+	{
+		name: z.string().describe("Plugin name — 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 — 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 — 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.",
+	{
+		status: pluginStatusSchema.optional().describe("Filter by status — omit to list all"),
+	},
+	async ({ status }) => {
+		const results = await convex.query(api.plugins.list, { status });
+		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: id as any });
+		return {
+			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+		};
+	},
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HOOKS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+server.tool(
+	"upsert_hook",
+	"Create or update a hook in VantageRegistry. Upserts by name.",
+	{
+		name: z.string().describe("Hook name — e.g. 'check-pii', 'enforce-skill-references'"),
+		event: hookEventSchema,
+		matcher: z.string().optional().describe("Tool matcher pattern — 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 — 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.",
+	{
+		status: hookStatusSchema.optional().describe("Filter by status — omit to list all"),
+	},
+	async ({ status }) => {
+		const results = await convex.query(api.hooks.list, { status });
+		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: id as any });
+		return {
+			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+		};
+	},
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// PROMPTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+server.tool(
+	"upsert_prompt",
+	"Create or update a prompt in VantageRegistry. Upserts by name.",
+	{
+		name: z.string().describe("Prompt name — e.g. 'system-prompt', 'review-checklist'"),
+		team: z.string().optional().describe("Team this prompt belongs to — 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 — 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 — 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: id as any });
+		return {
+			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+		};
+	},
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TEMPLATES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+server.tool(
+	"upsert_template",
+	"Create or update a template in VantageRegistry. Upserts by name.",
+	{
+		name: z.string().describe("Template name — e.g. 'agent-brief', 'skill-md'"),
+		team: z.string().optional().describe("Team this template belongs to — 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 — e.g. '1.0.0'"),
+	},
+	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 — 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: id as any });
+		return {
+			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+		};
+	},
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SKILL TEST RUNS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+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 — e.g. 'alpha', 'pi'"),
+		runByMission: z.string().optional().describe("Mission reference — e.g. 'D70'"),
+		reviewerScore: z.string().describe("Score as 'X/Y' — 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 — e.g. 'claude-sonnet-4-6'"),
+		judgeModel: z.string().describe("Model used as judge — e.g. 'claude-haiku-4-5'"),
+		corpusVersion: z.string().describe("Eval corpus version used — e.g. '2.0.0'"),
+		harnessVersion: z.string().describe("Test harness version — 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 — defaults to 'tested'"),
+	},
+	async (args) => {
+		const id = await convex.mutation(api.skillTestRuns.upsertTestRun, {
+			...args,
+			skillId: args.skillId as any,
+		});
+		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 — defaults to 50"),
+	},
+	async ({ skillId, limit }) => {
+		const results = await convex.query(api.skillTestRuns.getSkillTestHistory, {
+			skillId: skillId as any,
+			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.",
+	{
+		staleDays: z.number().describe("Number of days since last test run to consider stale"),
+	},
+	async ({ staleDays }) => {
+		const results = await convex.query(api.skillTestRuns.listSkillsByFreshness, { staleDays });
+		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.",
+	{
+		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."),
+	},
+	async ({ scoreMin, deltaMin }) => {
+		const results = await convex.query(api.skillTestRuns.listSkillsBelowThreshold, { scoreMin, deltaMin });
+		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 — 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 — e.g. '1.0.0'"),
+	},
+	async (args) => {
+		const id = await convex.mutation(api.skillEvalCorpus.upsertSkillEvalCorpus, {
+			...args,
+			skillId: args.skillId as any,
+		});
+		return {
+			content: [{ type: "text", text: JSON.stringify({ id, skillId: args.skillId, version: args.version }, null, 2) }],
+		};
+	},
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// RUNBOOKS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const 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"),
+});
+
+const runbookInputSchema = z.object({
+	name: z.string().describe("Input parameter name"),
+	type: z.string().describe("Input type — e.g. 'string', 'boolean'"),
+	required: z.boolean().describe("Whether this input is required"),
+	description: z.string().describe("What this input controls"),
+});
+
+const 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 — e.g. 'reports/{name}.md'"),
+});
+
+const 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"),
+});
+
+const linkedTemplateSchema = z.object({
+	name: z.string().describe("Template name"),
+	template_type: z.string().describe("Template type — mission, document, or checklist"),
+	version: z.string().describe("Template version — 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 — if a runbook with the same name exists, it is updated.",
+	{
+		name: z.string().describe("Runbook slug — e.g. 'deploy-production', 'onboard-agent'"),
+		description: z.string().describe("What this runbook accomplishes"),
+		version: z.string().describe("Semantic version — e.g. '1.0.0'"),
+		status: runbookStatusSchema,
+		category: z.string().describe("Category — 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 — e.g. 'omega'"),
+		team: z.string().describe("Owning team slug — 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 — 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 — defaults to 'published'"),
+		category: z.string().optional().describe("Filter by category — 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 — 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 — e.g. 'deployment', 'quality'"),
+		status: runbookStatusSchema.optional().describe("Filter by status — 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 — e.g. 'core', 'dev'"),
+		status: runbookStatusSchema.optional().describe("Filter by status — 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 — 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) }],
+			};
+		}
+	},
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// STATS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+server.tool(
+	"get_stats",
+	"Get counts per table in VantageRegistry — 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: 1000 }),
+			convex.query(api.runbooks.listRunbooks, { status: "published", limit: 1000 }),
+			convex.query(api.runbooks.listRunbooks, { status: "deprecated", limit: 1000 }),
+		]);
+
+		// Build by_category map across all statuses
+		const byCategoryMap: Record<string, number> = {};
+		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) }],
+		};
+	},
+);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Start
+// ─────────────────────────────────────────────────────────────────────────────
+
+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);
+});