@vantageos/vantage-registry-mcp 1.6.0 → 1.7.0

package/server.ts

@@ -19,10 +19,15 @@
  * Orchestrator: Omega — VantageOS Team | 2026-06-01
  */
 
+import { createServer } from "node:http";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import { timingSafeEqual } from "node:crypto";
 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 { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { ConvexHttpClient } from "convex/browser";
 import { z } from "zod";
 import { api } from "../convex/_generated/api.js";
@@ -121,23 +126,330 @@ const linkTypeSchema = z
 		"Link type — uses: template consumed during execution, produces: output document generated, references: informational cross-reference",
 	);
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Admin write secret — ported from scripts/backfill-vr-content.ts pattern (lines 58-68)
+// All Convex write mutations require this secret since PR #93 (write-auth-guard).
+// Only injected when the MCP server is in ADMIN mode (MCP_BEARER_TOKEN auth).
+// Read-only instances (MCP_BEARER_TOKEN_READONLY) must never inject or execute writes.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Injects adminSecret into mutation args, gated on ADMIN mode AND secret presence.
+ * Mirrors the pattern from scripts/backfill-vr-content.ts lines 58-68 / 231.
+ *
+ * VR_ADMIN_WRITE_SECRET is read from process.env at call time (not module load)
+ * so tests can set it after import and live servers pick up rotated values.
+ *
+ * Two failure modes (both throw — zero mutations fired):
+ *   1. isAdmin=false → read-only mode; write forbidden regardless of secret presence.
+ *   2. VR_ADMIN_WRITE_SECRET unset → admin mode but server not configured for writes.
+ *
+ * @param args    - Mutation args the caller would pass without the secret.
+ * @param isAdmin - true when authenticated via MCP_BEARER_TOKEN (admin role).
+ *                  Defaults to true for the stdio path (no HTTP layer);
+ *                  HTTP write tools pass role==="admin" from resolveRole().
+ */
+export function adminWriteArgs<T extends Record<string, unknown>>(
+	args: T,
+	isAdmin = true,
+): T & { adminSecret: string } {
+	if (!isAdmin) {
+		throw new Error(
+			"This MCP instance is in read-only mode. Write tools are not available. " +
+			"Use an admin token (MCP_BEARER_TOKEN) to enable write operations.",
+		);
+	}
+	const secret = process.env.VR_ADMIN_WRITE_SECRET;
+	if (!secret || secret.length === 0) {
+		throw new Error(
+			"This MCP instance is not configured for writes: VR_ADMIN_WRITE_SECRET is not set. " +
+			"Set VR_ADMIN_WRITE_SECRET in the server environment to enable write operations.",
+		);
+	}
+	return { ...args, adminSecret: secret };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Server setup
 // ─────────────────────────────────────────────────────────────────────────────
 
-const convexUrl = loadConvexUrl();
-const convex = new ConvexHttpClient(convexUrl);
+// Lazy ConvexHttpClient — deferred until first use so tests can mock
+// convex/browser before any instantiation occurs at module load time.
+let _convex: ConvexHttpClient | null = null;
+function getConvex(): ConvexHttpClient {
+	if (!_convex) {
+		_convex = new ConvexHttpClient(loadConvexUrl());
+	}
+	return _convex;
+}
+// Proxy object so existing `convex.query(...)` / `convex.mutation(...)` calls
+// in tool handlers continue to work without modification.
+const convex = new Proxy({} as ConvexHttpClient, {
+	get(_target, prop) {
+		const client = getConvex();
+		const value = (client as unknown as Record<string | symbol, unknown>)[prop];
+		if (typeof value === "function") {
+			return value.bind(client);
+		}
+		return value;
+	},
+});
 
 const server = new McpServer({
 	name: "vantage-registry",
-	version: "1.5.0",
+	version: "1.7.0",
 });
 
+// ─────────────────────────────────────────────────────────────────────────────
+// HTTP transport — Bearer auth + read-only scope
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Write tools — any tools/call for these names is blocked for read-only tokens.
+ * Derived from the full set of `server.tool(...)` registrations above.
+ */
+export const WRITE_TOOLS: ReadonlySet<string> = new Set([
+	"upsert_team",
+	"upsert_agent",
+	"upsert_skill",
+	"upsert_skill_content",
+	"upsert_agent_content",
+	"upsert_plugin_content",
+	"upsert_hook_content",
+	"upsert_command_content",
+	"upsert_plugin",
+	"upsert_hook",
+	"upsert_prompt",
+	"upsert_template",
+	"upsert_test_run",
+	"upsert_skill_eval_corpus",
+	"upsert_runbook",
+	"delete_runbook",
+	"link_runbook_template",
+	"unlink_runbook_template",
+	"register_component",
+	"update_component",
+	"delete_component",
+]);
+
+/** Resolve incoming bearer token to a role or null (unauthorized). */
+function resolveRole(
+	authHeader: string | undefined,
+): "admin" | "readonly" | null {
+	if (!authHeader) return null;
+	const prefix = "Bearer ";
+	if (!authHeader.startsWith(prefix)) return null;
+	const token = authHeader.slice(prefix.length);
+
+	const adminToken = process.env.MCP_BEARER_TOKEN;
+	const roToken = process.env.MCP_BEARER_TOKEN_READONLY;
+
+	const enc = new TextEncoder();
+	const tokenBuf = enc.encode(token);
+
+	if (adminToken) {
+		const adminBuf = enc.encode(adminToken);
+		// timingSafeEqual requires same length — pad shorter with zeros
+		const len = Math.max(tokenBuf.length, adminBuf.length);
+		const a = Buffer.alloc(len);
+		const b = Buffer.alloc(len);
+		Buffer.from(tokenBuf).copy(a);
+		Buffer.from(adminBuf).copy(b);
+		if (timingSafeEqual(a, b) && token.length === adminToken.length) {
+			return "admin";
+		}
+	}
+
+	if (roToken) {
+		const roBuf = enc.encode(roToken);
+		const len = Math.max(tokenBuf.length, roBuf.length);
+		const a = Buffer.alloc(len);
+		const b = Buffer.alloc(len);
+		Buffer.from(tokenBuf).copy(a);
+		Buffer.from(roBuf).copy(b);
+		if (timingSafeEqual(a, b) && token.length === roToken.length) {
+			return "readonly";
+		}
+	}
+
+	return null;
+}
+
+/** Send a JSON error response. */
+function sendJsonError(
+	res: ServerResponse,
+	status: number,
+	body: Record<string, unknown>,
+	extraHeaders?: Record<string, string>,
+): void {
+	const payload = JSON.stringify(body);
+	res.writeHead(status, {
+		"Content-Type": "application/json",
+		"Content-Length": Buffer.byteLength(payload),
+		...extraHeaders,
+	});
+	res.end(payload);
+}
+
+/** Read the full request body as a Buffer. */
+async function readBody(req: IncomingMessage): Promise<Buffer> {
+	return new Promise((resolve, reject) => {
+		const chunks: Buffer[] = [];
+		req.on("data", (c: Buffer) => chunks.push(c));
+		req.on("end", () => resolve(Buffer.concat(chunks)));
+		req.on("error", reject);
+	});
+}
+
+/**
+ * Create the node:http request handler with Bearer auth + read-only scope gate.
+ * Returns an app-like object with a `fetch`-compatible `.handler` property.
+ */
+export function createHttpApp(): (
+	req: IncomingMessage,
+	res: ServerResponse,
+) => void {
+	return async function handler(
+		req: IncomingMessage,
+		res: ServerResponse,
+	): Promise<void> {
+		const url = new URL(req.url ?? "/", `http://localhost`);
+
+		// Health check — unauthenticated
+		if (req.method === "GET" && url.pathname === "/health") {
+			sendJsonError(res, 200, {
+				status: "ok",
+				service: "vantage-registry-mcp",
+				transport: "streamable-http",
+			});
+			return;
+		}
+
+		// Only handle /mcp
+		if (url.pathname !== "/mcp") {
+			sendJsonError(res, 404, { error: "not_found" });
+			return;
+		}
+
+		// ── Bearer auth ──────────────────────────────────────────────────────
+		// Only enforce bearer auth when MCP_BEARER_TOKEN is configured.
+		// If neither token is set, the server runs in open mode (e.g., local dev).
+		const adminToken = process.env.MCP_BEARER_TOKEN;
+		const roToken = process.env.MCP_BEARER_TOKEN_READONLY;
+		const bearerEnabled = Boolean(adminToken || roToken);
+
+		let role: "admin" | "readonly" | "open" = "open";
+		if (bearerEnabled) {
+			const resolved = resolveRole(req.headers["authorization"]);
+			if (resolved === null) {
+				sendJsonError(
+					res,
+					401,
+					{ error: "Unauthorized", message: "Missing or invalid bearer token" },
+					{ "WWW-Authenticate": 'Bearer realm="vantage-registry"' },
+				);
+				return;
+			}
+			role = resolved;
+		}
+
+		// ── Read body once (needed for scope gate + forwarding to transport) ──
+		const rawBody = await readBody(req);
+		let parsedBody: unknown = null;
+		try {
+			parsedBody = JSON.parse(rawBody.toString("utf-8"));
+		} catch {
+			sendJsonError(res, 400, { error: "invalid_json" });
+			return;
+		}
+
+		// ── Read-only scope gate: block write tools ──────────────────────────
+		if (role === "readonly") {
+			const body = parsedBody as Record<string, unknown>;
+			if (
+				body &&
+				typeof body === "object" &&
+				body.method === "tools/call" &&
+				body.params &&
+				typeof body.params === "object"
+			) {
+				const toolName = (body.params as Record<string, unknown>).name;
+				if (typeof toolName === "string" && WRITE_TOOLS.has(toolName)) {
+					sendJsonError(res, 403, {
+						error: "Forbidden",
+						message: `Tool '${toolName}' requires admin scope. Read-only token cannot call write tools.`,
+					});
+					return;
+				}
+			}
+		}
+
+		// ── Fresh MCP server + stateless transport per request ───────────────
+		const mcpServer = new McpServer({
+			name: "vantage-registry",
+			version: "1.7.0",
+		});
+		// Re-register all tools on the per-request server, passing ADMIN mode flag
+		// so write tools know whether to inject adminSecret or refuse.
+		registerAllTools(mcpServer, role === "admin");
+
+		const transport = new StreamableHTTPServerTransport({
+			sessionIdGenerator: undefined, // stateless
+			enableJsonResponse: true, // return plain JSON, not SSE
+		});
+		await mcpServer.connect(transport);
+
+		// Inject the already-read body so transport doesn't need to re-read it
+		await transport.handleRequest(req, res, parsedBody);
+	};
+}
+
+/**
+ * Start an HTTP server on the given port.
+ * Returns { close(), address() } matching the test contract.
+ */
+export function startHttpServer(
+	port: number,
+): Promise<{ close(): void; address(): AddressInfo }> {
+	return new Promise((resolve, reject) => {
+		const handler = createHttpApp();
+		const httpServer = createServer(handler);
+		httpServer.on("error", reject);
+		httpServer.listen(port, "0.0.0.0", () => {
+			resolve({
+				close() {
+					httpServer.close();
+				},
+				address() {
+					return httpServer.address() as AddressInfo;
+				},
+			});
+		});
+	});
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool registration — called once for stdio server, and per-request for HTTP
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Register all MCP tools on the given server instance.
+ *
+ * @param s       - The McpServer to register tools on.
+ * @param isAdmin - Whether the caller has admin privileges.
+ *                  - HTTP path: pass role==="admin" (resolved from MCP_BEARER_TOKEN).
+ *                  - stdio path: defaults to true — stdio has no token layer;
+ *                    adminWriteArgs() still enforces VR_ADMIN_WRITE_SECRET presence.
+ *                  Write tools call adminWriteArgs(args, isAdmin) which throws (zero
+ *                  mutation) if isAdmin=false OR VR_ADMIN_WRITE_SECRET is unset.
+ */
+function registerAllTools(s: McpServer, isAdmin = true): void {
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // TEAMS
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.tool(
 	"upsert_team",
 	"Create or update a team in VantageRegistry. Upserts by name — if a team with the same name exists, it is updated.",
 	{
@@ -152,7 +464,7 @@ server.tool(
 			.describe("Associated project — e.g. 'vantage-starter'"),
 	},
 	async (args) => {
-		const id = await convex.mutation(api.teams.upsert, args);
+		const id = await convex.mutation(api.teams.upsert, adminWriteArgs(args, isAdmin));
 		return {
 			content: [
 				{ type: "text", text: JSON.stringify({ id, ...args }, null, 2) },
@@ -161,7 +473,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"list_teams",
 	"List all teams in VantageRegistry. Optionally filter by status (active, planned, deprecated).",
 	{
@@ -177,7 +489,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"get_team",
 	"Get a single team by its Convex document ID.",
 	{
@@ -195,7 +507,7 @@ server.tool(
 // AGENTS
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.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.",
 	{
@@ -223,7 +535,7 @@ server.tool(
 			.describe("Categories beyond team name"),
 	},
 	async (args) => {
-		const id = await convex.mutation(api.agents.upsert, args);
+		const id = await convex.mutation(api.agents.upsert, adminWriteArgs(args, isAdmin));
 		return {
 			content: [
 				{
@@ -239,7 +551,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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.",
@@ -276,7 +588,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"list_agents_by_team",
 	"List all agents belonging to a specific team.",
 	{
@@ -297,7 +609,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"get_agent",
 	"Get a single agent by its Convex document ID.",
 	{
@@ -315,7 +627,7 @@ server.tool(
 // SKILLS
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.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. " +
 		"Pass vrBody to write the full SKILL.md body (vrContent/vrContentHash/vrContentVersion) in the SAME call — no separate upsert_skill_content needed (that tool remains for back-compat). Omit vrBody for metadata-only upsert.",
@@ -353,7 +665,7 @@ server.tool(
 			),
 	},
 	async (args) => {
-		const id = await convex.mutation(api.skills.upsert, args);
+		const id = await convex.mutation(api.skills.upsert, adminWriteArgs(args, isAdmin));
 		return {
 			content: [
 				{
@@ -369,7 +681,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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.",
@@ -410,7 +722,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"list_skills_by_team",
 	"List all skills belonging to a specific team.",
 	{
@@ -431,7 +743,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"list_skills_by_category",
 	"List all skills of a specific category (capability, composite, playbook, root, external).",
 	{
@@ -452,7 +764,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"get_skill",
 	"Get a single skill by its Convex document ID.",
 	{
@@ -470,7 +782,7 @@ server.tool(
 // SKILL CONTENT — VR Single-Source-of-Truth (D72-VR-SoT)
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.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. " +
@@ -490,7 +802,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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 " +
@@ -513,11 +825,7 @@ server.tool(
 	async ({ name, content, createIfMissing }) => {
 		const result = await convex.mutation(
 			api.skillContentDb.upsertSkillContent,
-			{
-				name,
-				content,
-				createIfMissing,
-			},
+			adminWriteArgs({ name, content, createIfMissing }, isAdmin),
 		);
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
@@ -525,7 +833,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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 " +
@@ -556,7 +864,7 @@ server.tool(
 // AGENT CONTENT — VR Single-Source-of-Truth (D72-VR-SoT Phase A)
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.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. " +
@@ -576,7 +884,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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). " +
@@ -600,11 +908,7 @@ server.tool(
 	async ({ name, content, createIfMissing }) => {
 		const result = await convex.mutation(
 			api.agentContentDb.upsertAgentContent,
-			{
-				name,
-				content,
-				createIfMissing,
-			},
+			adminWriteArgs({ name, content, createIfMissing }, isAdmin),
 		);
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
@@ -612,7 +916,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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 " +
@@ -643,7 +947,7 @@ server.tool(
 // PLUGIN CONTENT — VR Single-Source-of-Truth (D72-VR-SoT Phase A)
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.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. " +
@@ -663,7 +967,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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). " +
@@ -685,11 +989,7 @@ server.tool(
 	async ({ name, content, createIfMissing }) => {
 		const result = await convex.mutation(
 			api.pluginContentDb.upsertPluginContent,
-			{
-				name,
-				content,
-				createIfMissing,
-			},
+			adminWriteArgs({ name, content, createIfMissing }, isAdmin),
 		);
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
@@ -697,7 +997,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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 " +
@@ -728,7 +1028,7 @@ server.tool(
 // HOOK CONTENT — VR Single-Source-of-Truth (D72-VR-SoT Phase A)
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.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. " +
@@ -748,7 +1048,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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). " +
@@ -769,18 +1069,16 @@ server.tool(
 			),
 	},
 	async ({ name, content, createIfMissing }) => {
-		const result = await convex.mutation(api.hookContentDb.upsertHookContent, {
-			name,
-			content,
-			createIfMissing,
-		});
+		const result = await convex.mutation(api.hookContentDb.upsertHookContent,
+			adminWriteArgs({ name, content, createIfMissing }, isAdmin),
+		);
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
 	},
 );
 
-server.tool(
+s.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 " +
@@ -808,7 +1106,7 @@ server.tool(
 // COMMAND CONTENT — VR Single-Source-of-Truth (D72-VR-SoT Phase A)
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.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. " +
@@ -828,7 +1126,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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). " +
@@ -842,10 +1140,7 @@ server.tool(
 	async ({ name, content }) => {
 		const result = await convex.mutation(
 			api.commandContentDb.upsertCommandContent,
-			{
-				name,
-				content,
-			},
+			adminWriteArgs({ name, content }, isAdmin),
 		);
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
@@ -853,7 +1148,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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 " +
@@ -884,7 +1179,7 @@ server.tool(
 // PLUGINS
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.tool(
 	"upsert_plugin",
 	"Create or update a plugin in VantageRegistry. Upserts by name.",
 	{
@@ -912,7 +1207,7 @@ server.tool(
 			.describe("Categories beyond team name"),
 	},
 	async (args) => {
-		const id = await convex.mutation(api.plugins.upsert, args);
+		const id = await convex.mutation(api.plugins.upsert, adminWriteArgs(args, isAdmin));
 		return {
 			content: [
 				{
@@ -924,7 +1219,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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.",
@@ -954,7 +1249,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"get_plugin",
 	"Get a single plugin by its Convex document ID.",
 	{
@@ -972,7 +1267,7 @@ server.tool(
 // HOOKS
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.tool(
 	"upsert_hook",
 	"Create or update a hook in VantageRegistry. Upserts by name.",
 	{
@@ -1000,7 +1295,7 @@ server.tool(
 			),
 	},
 	async (args) => {
-		const id = await convex.mutation(api.hooks.upsert, args);
+		const id = await convex.mutation(api.hooks.upsert, adminWriteArgs(args, isAdmin));
 		return {
 			content: [
 				{
@@ -1016,7 +1311,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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.",
@@ -1048,7 +1343,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"get_hook",
 	"Get a single hook by its Convex document ID.",
 	{
@@ -1066,7 +1361,7 @@ server.tool(
 // PROMPTS
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.tool(
 	"upsert_prompt",
 	"Create or update a prompt in VantageRegistry. Upserts by name.",
 	{
@@ -1082,7 +1377,7 @@ server.tool(
 		version: z.string().optional().describe("Semantic version — e.g. '1.0.0'"),
 	},
 	async (args) => {
-		const id = await convex.mutation(api.prompts.upsert, args);
+		const id = await convex.mutation(api.prompts.upsert, adminWriteArgs(args, isAdmin));
 		return {
 			content: [
 				{
@@ -1094,7 +1389,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"list_prompts",
 	"List all prompts in VantageRegistry. Optionally filter by team.",
 	{
@@ -1108,7 +1403,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"get_prompt",
 	"Get a single prompt by its Convex document ID.",
 	{
@@ -1126,7 +1421,7 @@ server.tool(
 // TEMPLATES
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.tool(
 	"upsert_template",
 	"Create or update a template in VantageRegistry. Upserts by name. " +
 		"contentHash is auto-computed server-side (sha256 of content) when omitted.",
@@ -1162,7 +1457,7 @@ server.tool(
 			.describe("Git repo the template content was sourced from"),
 	},
 	async (args) => {
-		const id = await convex.mutation(api.templates.upsert, args);
+		const id = await convex.mutation(api.templates.upsert, adminWriteArgs(args, isAdmin));
 		return {
 			content: [
 				{
@@ -1174,7 +1469,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"list_templates",
 	"List all templates in VantageRegistry. Optionally filter by team and/or template_type.",
 	{
@@ -1194,7 +1489,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"get_template",
 	"Get a single template by its Convex document ID.",
 	{
@@ -1208,7 +1503,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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. " +
@@ -1231,7 +1526,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"list_templates_by_category",
 	"List templates for a specific category using the byCategory index.",
 	{
@@ -1253,7 +1548,7 @@ server.tool(
 // SKILL TEST RUNS
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.tool(
 	"upsert_test_run",
 	"Insert a skill quality test run and update denormalized quality fields on the parent skill " +
 		"(lastTestedAt, lastReviewerScore, lastEvalDelta, testStatus). " +
@@ -1311,10 +1606,9 @@ server.tool(
 			.describe("Override test status — defaults to 'tested'"),
 	},
 	async (args) => {
-		const id = await convex.mutation(api.skillTestRuns.upsertTestRun, {
-			...args,
-			skillId: args.skillId as any,
-		});
+		const id = await convex.mutation(api.skillTestRuns.upsertTestRun,
+			adminWriteArgs({ ...args, skillId: args.skillId as any }, isAdmin),
+		);
 		return {
 			content: [
 				{
@@ -1330,7 +1624,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"get_skill_test_history",
 	"Return test run history for a skill, ordered newest-first.",
 	{
@@ -1351,7 +1645,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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. " +
@@ -1385,7 +1679,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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. " +
@@ -1421,7 +1715,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"upsert_skill_eval_corpus",
 	"Insert or update an eval corpus version for a skill. Upserts by (skillId, version).",
 	{
@@ -1452,10 +1746,7 @@ server.tool(
 	async (args) => {
 		const id = await convex.mutation(
 			api.skillEvalCorpus.upsertSkillEvalCorpus,
-			{
-				...args,
-				skillId: args.skillId as any,
-			},
+			adminWriteArgs({ ...args, skillId: args.skillId as any }, isAdmin),
 		);
 		return {
 			content: [
@@ -1523,7 +1814,7 @@ const linkedTemplateSchema = z.object({
 	description: z.string().describe("How this template is used in this runbook"),
 });
 
-server.tool(
+s.tool(
 	"upsert_runbook",
 	"Create or update a runbook in VantageRegistry. Upserts by name — if a runbook with the same name exists, it is updated.",
 	{
@@ -1560,7 +1851,7 @@ server.tool(
 	},
 	async (args) => {
 		try {
-			const result = await convex.mutation(api.runbooks.upsertRunbook, args);
+			const result = await convex.mutation(api.runbooks.upsertRunbook, adminWriteArgs(args, isAdmin));
 			return {
 				content: [
 					{
@@ -1586,7 +1877,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"get_runbook",
 	"Get a single runbook by name. Optionally guard by exact version.",
 	{
@@ -1627,7 +1918,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"list_runbooks",
 	"List runbooks in VantageRegistry. Defaults to published status. Supports applicability filters.",
 	{
@@ -1685,7 +1976,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"list_runbooks_by_category",
 	"List runbooks for a specific category using the byCategory index.",
 	{
@@ -1729,7 +2020,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"list_runbooks_by_team",
 	"List runbooks for a specific team using the byTeam index.",
 	{
@@ -1769,7 +2060,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"delete_runbook",
 	"Soft-delete a runbook by name — sets status to 'deprecated'. Returns {deleted: true} if found, {deleted: false} if not found.",
 	{
@@ -1777,9 +2068,9 @@ server.tool(
 	},
 	async ({ name }) => {
 		try {
-			const result = await convex.mutation(api.runbooks.deleteRunbook, {
-				name,
-			});
+			const result = await convex.mutation(api.runbooks.deleteRunbook,
+				adminWriteArgs({ name }, isAdmin),
+			);
 			return {
 				content: [
 					{
@@ -1805,7 +2096,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"detect_runbook_drift",
 	"Return the VR-side sha256 hash (vrHash) plus category and version for each runbook in scope. " +
 		"IMPORTANT: Convex queries have no filesystem access. This tool computes sha256(runbook.content) " +
@@ -1831,7 +2122,7 @@ server.tool(
 // RUNBOOK ↔ TEMPLATE LINKS (Sprint B T4 — junction table typed links)
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.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 — at-most-one link per pair. " +
@@ -1865,14 +2156,17 @@ server.tool(
 		try {
 			const result = await convex.mutation(
 				api.runbookTemplateLinks.linkRunbookTemplate,
-				{
-					runbookId: args.runbookId as any,
-					templateId: args.templateId as any,
-					linkType: args.linkType,
-					usagePhase: args.usagePhase,
-					order: args.order,
-					createdBy: args.createdBy,
-				},
+				adminWriteArgs(
+					{
+						runbookId: args.runbookId as any,
+						templateId: args.templateId as any,
+						linkType: args.linkType,
+						usagePhase: args.usagePhase,
+						order: args.order,
+						createdBy: args.createdBy,
+					},
+					isAdmin,
+				),
 			);
 			return {
 				content: [
@@ -1899,7 +2193,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"unlink_runbook_template",
 	"Hard-delete the typed link between a runbook and a template. " +
 		"Links have no lifecycle state — they either exist or they don't (no soft-delete). " +
@@ -1912,10 +2206,13 @@ server.tool(
 		try {
 			const result = await convex.mutation(
 				api.runbookTemplateLinks.unlinkRunbookTemplate,
-				{
-					runbookId: args.runbookId as any,
-					templateId: args.templateId as any,
-				},
+				adminWriteArgs(
+					{
+						runbookId: args.runbookId as any,
+						templateId: args.templateId as any,
+					},
+					isAdmin,
+				),
 			);
 			return {
 				content: [
@@ -1942,7 +2239,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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. " +
@@ -1990,7 +2287,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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 — uses the byTemplate index. " +
@@ -2060,7 +2357,7 @@ const componentStatusSchema = z
 	.enum(["active", "deprecated", "experimental"])
 	.describe("Component status");
 
-server.tool(
+s.tool(
 	"register_component",
 	"Create or update a component in the VantageRegistry components catalog. " +
 		"Upserts by name+kind — if a component with the same name and kind exists it is updated. " +
@@ -2096,7 +2393,7 @@ server.tool(
 	},
 	async (args) => {
 		try {
-			const id = await convex.mutation(api.components.registerComponent, args);
+			const id = await convex.mutation(api.components.registerComponent, adminWriteArgs(args, isAdmin));
 			return {
 				content: [
 					{
@@ -2126,7 +2423,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"list_components",
 	"List components in the VantageRegistry catalog. " +
 		"Supports filtering by kind, ownerTeam, status, and tags. " +
@@ -2189,7 +2486,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"get_component",
 	"Get a single component by its Convex document ID. Returns the full document or null if not found.",
 	{
@@ -2220,7 +2517,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.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.",
@@ -2260,7 +2557,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"update_component",
 	"Patch individual fields on an existing component. Only provided fields are updated. Throws if not found.",
 	{
@@ -2279,10 +2576,9 @@ server.tool(
 	},
 	async (args) => {
 		try {
-			await convex.mutation(api.components.updateComponent, {
-				...args,
-				id: args.id as any,
-			});
+			await convex.mutation(api.components.updateComponent,
+				adminWriteArgs({ ...args, id: args.id as any }, isAdmin),
+			);
 			return {
 				content: [
 					{
@@ -2308,7 +2604,7 @@ server.tool(
 	},
 );
 
-server.tool(
+s.tool(
 	"delete_component",
 	"Soft-delete a component by ID — sets status to 'deprecated'. " +
 		"The document remains in the database and is still retrievable. " +
@@ -2320,9 +2616,9 @@ server.tool(
 	},
 	async ({ id }) => {
 		try {
-			const result = await convex.mutation(api.components.deleteComponent, {
-				id: id as any,
-			});
+			const result = await convex.mutation(api.components.deleteComponent,
+				adminWriteArgs({ id: id as any }, isAdmin),
+			);
 			return {
 				content: [
 					{
@@ -2352,7 +2648,7 @@ server.tool(
 // STATS
 // ═══════════════════════════════════════════════════════════════════════════════
 
-server.tool(
+s.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. " +
@@ -2424,14 +2720,33 @@ server.tool(
 	},
 );
 
+} // end registerAllTools
+
+// Register tools on the module-level stdio server.
+// stdio path has no HTTP bearer layer; adminWriteArgs() still enforces
+// VR_ADMIN_WRITE_SECRET presence at call time.
+registerAllTools(server, true);
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Start
 // ─────────────────────────────────────────────────────────────────────────────
 
+const PORT = Number(process.env.PORT ?? 3000);
+
 async function main() {
-	const transport = new StdioServerTransport();
-	await server.connect(transport);
-	console.error("VantageRegistry MCP server running on stdio");
+	if (process.env.MCP_TRANSPORT === "http") {
+		const instance = await startHttpServer(PORT);
+		const addr = instance.address();
+		console.error(
+			`VantageRegistry MCP server running on HTTP port ${addr.port}`,
+		);
+		console.error(`Health: http://0.0.0.0:${addr.port}/health`);
+		console.error(`MCP:    http://0.0.0.0:${addr.port}/mcp`);
+	} else {
+		const transport = new StdioServerTransport();
+		await server.connect(transport);
+		console.error("VantageRegistry MCP server running on stdio");
+	}
 }
 
 main().catch((err) => {