@canonical/pragma-cli 0.18.0

package/src/mcp/registerResources.ts

@@ -0,0 +1,303 @@
+import type { Store } from "@canonical/ke";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { PragmaError } from "#error";
+import { PROPERTY_MAP } from "../constants.js";
+import resolveUri from "../domains/graph/helpers/resolveUri.js";
+import { buildQuery } from "../domains/shared/buildQuery.js";
+import compactUri from "../domains/shared/compactUri.js";
+import type { PragmaRuntime } from "../domains/shared/runtime.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface PropertyValueLiteral {
+  readonly type: "literal";
+  readonly value: string;
+  readonly datatype?: string;
+}
+
+interface PropertyValueUri {
+  readonly type: "uri";
+  readonly uri: string;
+  readonly prefixed: string;
+  readonly label: string | null;
+}
+
+type PropertyValue = PropertyValueLiteral | PropertyValueUri;
+
+interface PropertyGroup {
+  readonly predicate: string;
+  readonly values: PropertyValue[];
+}
+
+interface ResourceEntity {
+  readonly uri: string;
+  readonly prefixed: string;
+  readonly types: string[];
+  readonly label: string | null;
+  readonly description: string | null;
+  readonly properties: PropertyGroup[];
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+const RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
+
+/**
+ * Determine the namespace prefix for a full URI.
+ */
+function findPrefix(
+  fullUri: string,
+  prefixes: Readonly<Record<string, string>>,
+): string | null {
+  for (const [prefix, namespace] of Object.entries(prefixes)) {
+    if (fullUri.startsWith(namespace)) return prefix;
+  }
+  return null;
+}
+
+/**
+ * Fetch a single property value for a URI using the PROPERTY_MAP.
+ */
+async function fetchProperty(
+  store: Store,
+  fullUri: string,
+  prefixes: Readonly<Record<string, string>>,
+  field: "label" | "description",
+): Promise<string | null> {
+  const prefix = findPrefix(fullUri, prefixes);
+  if (!prefix) return null;
+
+  const propUri = PROPERTY_MAP[prefix]?.[field];
+  if (!propUri) return null;
+
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?val
+      WHERE { <${fullUri}> <${propUri}> ?val }
+      LIMIT 1
+    `),
+  );
+
+  if (result.type === "select" && result.bindings.length > 0) {
+    return result.bindings[0]?.val ?? null;
+  }
+  return null;
+}
+
+/**
+ * Fetch the human-readable label for a URI using the PROPERTY_MAP.
+ */
+async function fetchLabel(
+  store: Store,
+  fullUri: string,
+  prefixes: Readonly<Record<string, string>>,
+): Promise<string | null> {
+  return fetchProperty(store, fullUri, prefixes, "label");
+}
+
+/**
+ * Fetch the human-readable description for a URI using the PROPERTY_MAP.
+ */
+async function fetchDescription(
+  store: Store,
+  fullUri: string,
+  prefixes: Readonly<Record<string, string>>,
+): Promise<string | null> {
+  return fetchProperty(store, fullUri, prefixes, "description");
+}
+
+/**
+ * Detect whether a SPARQL binding value is a URI or a literal.
+ * URIs start with http:// or https:// or are prefixed; literals are everything else.
+ */
+function isUri(value: string): boolean {
+  return (
+    value.startsWith("http://") ||
+    value.startsWith("https://") ||
+    value.startsWith("urn:")
+  );
+}
+
+/**
+ * Enumerate all distinct subject URIs in the graph.
+ */
+async function listAllSubjects(store: Store): Promise<string[]> {
+  const result = await store.query(
+    buildQuery("SELECT DISTINCT ?s WHERE { ?s ?p ?o } ORDER BY ?s"),
+  );
+
+  if (result.type !== "select") return [];
+  return result.bindings.map((b) => b.s ?? "").filter((s) => isUri(s));
+}
+
+/**
+ * Read a single entity: all its triples with level-1 object summaries.
+ */
+async function readEntity(
+  store: Store,
+  fullUri: string,
+  prefixes: Readonly<Record<string, string>>,
+): Promise<ResourceEntity> {
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?p ?o
+      WHERE { <${fullUri}> ?p ?o }
+      ORDER BY ?p ?o
+    `),
+  );
+
+  if (result.type !== "select" || result.bindings.length === 0) {
+    throw PragmaError.notFound("entity", compactUri(fullUri, prefixes), {
+      recovery: {
+        message:
+          "Check the URI is correct and run a SPARQL query to find valid URIs.",
+        cli: "pragma graph query 'SELECT ?s WHERE { ?s ?p ?o } LIMIT 10'",
+        mcp: { tool: "graph_query" },
+      },
+    });
+  }
+
+  const types: string[] = [];
+  const groupMap = new Map<string, PropertyValue[]>();
+
+  for (const b of result.bindings) {
+    const predicate = b.p ?? "";
+    const object = b.o ?? "";
+
+    if (predicate === RDF_TYPE) {
+      types.push(compactUri(object, prefixes));
+      continue;
+    }
+
+    const compactPred = compactUri(predicate, prefixes);
+    const existing = groupMap.get(compactPred) ?? [];
+
+    if (isUri(object)) {
+      const label = await fetchLabel(store, object, prefixes);
+      existing.push({
+        type: "uri",
+        uri: object,
+        prefixed: compactUri(object, prefixes),
+        label,
+      });
+    } else {
+      existing.push({ type: "literal", value: object });
+    }
+
+    groupMap.set(compactPred, existing);
+  }
+
+  const [label, description] = await Promise.all([
+    fetchLabel(store, fullUri, prefixes),
+    fetchDescription(store, fullUri, prefixes),
+  ]);
+
+  const properties: PropertyGroup[] = [...groupMap.entries()].map(
+    ([predicate, values]) => ({ predicate, values }),
+  );
+
+  return {
+    uri: fullUri,
+    prefixed: compactUri(fullUri, prefixes),
+    types,
+    label,
+    description,
+    properties,
+  };
+}
+
+// =============================================================================
+// Registration
+// =============================================================================
+
+/**
+ * Register graph-driven MCP resources on the server.
+ *
+ * Every subject URI in the ke graph becomes a discoverable MCP resource.
+ * Reading a resource returns the entity's properties with level-1 object
+ * relations resolved to summaries (label and description from PROPERTY_MAP).
+ *
+ * @param server - The MCP server to register resources on.
+ * @param runtime - The pragma runtime providing the ke store and prefixes.
+ *
+ * @note Impure
+ */
+export default function registerResources(
+  server: McpServer,
+  runtime: PragmaRuntime,
+): void {
+  const { store } = runtime;
+  const prefixes = store.prefixes;
+
+  const template = new ResourceTemplate("pragma:{+uri}", {
+    list: async () => {
+      const subjects = await listAllSubjects(store);
+      const resources = await Promise.all(
+        subjects.map(async (fullUri) => {
+          const prefixed = compactUri(fullUri, prefixes);
+          const label = await fetchLabel(store, fullUri, prefixes);
+          return {
+            uri: `pragma:${prefixed}`,
+            name: label ?? prefixed,
+            mimeType: "application/json" as const,
+          };
+        }),
+      );
+      return { resources };
+    },
+    complete: {
+      uri: async (value) => {
+        const subjects = await listAllSubjects(store);
+        const compacted = subjects.map((s) => compactUri(s, prefixes));
+        return compacted.filter((p) =>
+          p.toLowerCase().startsWith(value.toLowerCase()),
+        );
+      },
+    },
+  });
+
+  server.registerResource(
+    "graph-entity",
+    template,
+    {
+      description:
+        "An entity in the pragma knowledge graph. Returns all properties with level-1 relation summaries.",
+      mimeType: "application/json",
+    },
+    async (url, variables) => {
+      try {
+        const prefixedUri = variables.uri as string;
+        const fullUri = resolveUri(prefixedUri, prefixes);
+        const entity = await readEntity(store, fullUri, prefixes);
+        return {
+          contents: [
+            {
+              uri: url.href,
+              mimeType: "application/json",
+              text: JSON.stringify(entity, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        const message =
+          error instanceof PragmaError
+            ? JSON.stringify({ code: error.code, message: error.message })
+            : String(error);
+        return {
+          contents: [
+            {
+              uri: url.href,
+              mimeType: "text/plain",
+              text: message,
+            },
+          ],
+        };
+      }
+    },
+  );
+}

package/src/mcp/runMcpServer.test.ts

@@ -0,0 +1,66 @@
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const createMcpServerMock = vi.fn();
+
+vi.mock("./createMcpServer.js", () => ({
+  createMcpServer: createMcpServerMock,
+}));
+
+vi.mock("@modelcontextprotocol/sdk/server/stdio.js", () => ({
+  StdioServerTransport: class StdioServerTransport {},
+}));
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.clearAllMocks();
+});
+
+describe("runMcpServer", () => {
+  it("creates the server, connects stdio transport, and disposes on SIGINT", async () => {
+    const connect = vi.fn(async () => undefined);
+    const dispose = vi.fn();
+    createMcpServerMock.mockResolvedValue({
+      server: { connect },
+      dispose,
+    });
+
+    let sigintHandler: (() => void) | undefined;
+    vi.spyOn(process, "on").mockImplementation(((event, handler) => {
+      if (event === "SIGINT") sigintHandler = handler as () => void;
+      return process;
+    }) as typeof process.on);
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation((() => undefined) as never);
+
+    const { default: runMcpServer } = await import("./runMcpServer.js");
+    await runMcpServer();
+
+    expect(createMcpServerMock).toHaveBeenCalledTimes(1);
+    expect(connect).toHaveBeenCalledTimes(1);
+    expect(sigintHandler).toBeTypeOf("function");
+
+    sigintHandler?.();
+
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(exitSpy).toHaveBeenCalledWith(0);
+  });
+
+  it("pragma mcp subcommand starts and exits on stdin close", () => {
+    const binPath = resolve(import.meta.dirname, "../bin.ts");
+    const result = spawnSync("bun", ["run", binPath, "mcp"], {
+      input: "",
+      encoding: "utf-8",
+      timeout: 10_000,
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.signal).toBeNull();
+    if (result.status !== 0) {
+      console.error("pragma mcp stderr:", result.stderr);
+    }
+    expect(result.status).toBe(0);
+  });
+});

package/src/mcp/runMcpServer.ts

@@ -0,0 +1,24 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServer } from "./createMcpServer.js";
+
+/**
+ * Start the MCP server over stdio transport.
+ *
+ * Boots the pragma runtime, connects to stdin/stdout, and runs until the
+ * process receives SIGINT or stdin closes.
+ *
+ * @returns Resolves when the transport connection is established.
+ *
+ * @note Impure
+ */
+export default async function runMcpServer(): Promise<void> {
+  const { server, dispose } = await createMcpServer();
+  const transport = new StdioServerTransport();
+
+  process.on("SIGINT", () => {
+    dispose();
+    process.exit(0);
+  });
+
+  await server.connect(transport);
+}

package/src/mcp/tools/index.ts

@@ -0,0 +1,55 @@
+/**
+ * MCP tool registration orchestrator.
+ *
+ * Collects declarative ToolSpec arrays from each domain and registers
+ * them on the MCP server via the registerFromSpec adapter.
+ *
+ * @module
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { specs as blockSpecs } from "../../domains/block/mcp/index.js";
+import { specs as configSpecs } from "../../domains/config/mcp/index.js";
+import { specs as createSpecs } from "../../domains/create/mcp/index.js";
+import { specs as diagnosticSpecs } from "../../domains/doctor/mcp/index.js";
+import { specs as graphSpecs } from "../../domains/graph/mcp/index.js";
+import { specs as orientationSpecs } from "../../domains/llm/mcp/index.js";
+import { specs as modifierSpecs } from "../../domains/modifier/mcp/index.js";
+import { specs as ontologySpecs } from "../../domains/ontology/mcp/index.js";
+import type { PragmaRuntime } from "../../domains/shared/runtime.js";
+import type { ToolSpec } from "../../domains/shared/ToolSpec.js";
+import { specs as skillSpecs } from "../../domains/skill/mcp/index.js";
+import { specs as standardSpecs } from "../../domains/standard/mcp/index.js";
+import { specs as tierSpecs } from "../../domains/tier/mcp/index.js";
+import { specs as tokenSpecs } from "../../domains/token/mcp/index.js";
+import registerFromSpec from "./registerFromSpec.js";
+
+const allSpecs: readonly ToolSpec[] = [
+  ...blockSpecs,
+  ...standardSpecs,
+  ...modifierSpecs,
+  ...tokenSpecs,
+  ...tierSpecs,
+  ...configSpecs,
+  ...ontologySpecs,
+  ...graphSpecs,
+  ...skillSpecs,
+  ...diagnosticSpecs,
+  ...orientationSpecs,
+  ...createSpecs,
+];
+
+/**
+ * Register all MCP tools on the server.
+ *
+ * @param server - The MCP server to register tools on.
+ * @param runtime - The pragma runtime providing store and config.
+ */
+export default function registerAllTools(
+  server: McpServer,
+  runtime: PragmaRuntime,
+): void {
+  for (const spec of allSpecs) {
+    registerFromSpec(server, runtime, spec);
+  }
+}

package/src/mcp/tools/registerFromSpec.ts

@@ -0,0 +1,97 @@
+/**
+ * Adapter: ToolSpec → server.registerTool().
+ *
+ * Converts declarative domain-owned ToolSpecs into registered MCP tools.
+ * This is the single point where ToolSpec meets MCP infrastructure —
+ * zod schema generation, wrapTool envelope, and server registration.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { PragmaRuntime } from "../../domains/shared/runtime.js";
+import type { ToolParamDef, ToolSpec } from "../../domains/shared/ToolSpec.js";
+import type { ToolPayload } from "../types.js";
+import { wrapTool } from "../utils/index.js";
+
+/**
+ * Convert a ToolParamDef record to a zod object schema.
+ */
+function buildZodSchema(
+  params: Readonly<Record<string, ToolParamDef>>,
+): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  const shape: Record<string, z.ZodTypeAny> = {};
+
+  for (const [name, def] of Object.entries(params)) {
+    let field: z.ZodTypeAny;
+
+    switch (def.type) {
+      case "boolean":
+        field = z.boolean();
+        break;
+      case "string[]":
+        field = z.array(z.string());
+        break;
+      case "string":
+        field = def.enum
+          ? z.enum(def.enum as [string, ...string[]])
+          : z.string();
+        break;
+    }
+
+    if (def.description) {
+      field = field.describe(def.description);
+    }
+    if (def.optional !== false) {
+      field = field.optional();
+    }
+
+    shape[name] = field;
+  }
+
+  return z.object(shape);
+}
+
+/**
+ * Register a single ToolSpec on the MCP server.
+ */
+export default function registerFromSpec(
+  server: McpServer,
+  runtime: PragmaRuntime,
+  spec: ToolSpec,
+): void {
+  const toolConfig: {
+    description: string;
+    inputSchema?: z.ZodObject<Record<string, z.ZodTypeAny>>;
+    annotations: {
+      readOnlyHint: boolean;
+      destructiveHint?: boolean;
+      openWorldHint: boolean;
+    };
+  } = {
+    description: spec.description,
+    annotations: {
+      readOnlyHint: spec.readOnly,
+      openWorldHint: false,
+    },
+  };
+
+  if (spec.params && Object.keys(spec.params).length > 0) {
+    toolConfig.inputSchema = buildZodSchema(spec.params);
+  }
+
+  if (spec.destructive !== undefined) {
+    toolConfig.annotations.destructiveHint = spec.destructive;
+  }
+
+  server.registerTool(
+    spec.name,
+    toolConfig,
+    wrapTool(
+      runtime,
+      spec.execute as (
+        rt: PragmaRuntime,
+        params: Record<string, unknown>,
+      ) => Promise<ToolPayload>,
+    ),
+  );
+}