@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/mcp/resources/readEntity.ts

@@ -0,0 +1,169 @@
+import type { Store } from "@canonical/ke";
+import { PragmaError } from "#error";
+import findNamespace from "../../domains/ontology/helpers/findNamespace.js";
+import { buildQuery } from "../../domains/shared/buildQuery.js";
+import compactUri from "../../domains/shared/compactUri.js";
+import classifyEntity from "./classifyEntity.js";
+import { RDF_TYPE, RDFS_DOMAIN, RDFS_SUBCLASS_OF } from "./constants.js";
+import {
+  resolveDescriptionPredicates,
+  resolveLabelPredicates,
+} from "./displayPredicates.js";
+import pickFirstValue from "./pickFirstValue.js";
+import pickPrimaryType from "./pickPrimaryType.js";
+import type {
+  GraphIndex,
+  PropertyGroup,
+  PropertyValue,
+  ResourceEntity,
+} from "./types.js";
+
+/** Query the compacted subjects of `?x <predicate> <object>`. */
+async function fetchReferencingSubjects(
+  store: Store,
+  predicate: string,
+  object: string,
+  prefixes: Readonly<Record<string, string>>,
+): Promise<string[]> {
+  const result = await store.query(
+    buildQuery(`SELECT ?x WHERE { ?x <${predicate}> <${object}> } ORDER BY ?x`),
+  );
+  if (result.type !== "select") return [];
+  return result.termBindings
+    .filter((t) => t.x?.termType === "NamedNode")
+    .map((t) => compactUri(t.x?.value ?? "", prefixes));
+}
+
+/**
+ * Read a single entity into a box-aware payload.
+ *
+ * Object values are classified by RDF term type (via `termBindings`), so a
+ * URL-shaped literal stays a literal and a foreign IRI is recognised as a URI.
+ * A class read is enriched with its superclasses, direct subclasses, asserted
+ * instance count, and declared properties; an individual read carries a
+ * pointer to its primary class. Object URIs are labelled from the prebuilt
+ * index — no per-object query.
+ *
+ * @param store - The ke store to query.
+ * @param fullUri - The fully resolved subject URI.
+ * @param prefixes - The store's merged prefix map.
+ * @param index - The prebuilt graph index for label and count lookups.
+ * @returns The entity payload.
+ * @throws PragmaError.notFound when the subject has no triples.
+ *
+ * @note Queries ke store
+ */
+export default async function readEntity(
+  store: Store,
+  fullUri: string,
+  prefixes: Readonly<Record<string, string>>,
+  index: GraphIndex,
+): 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 fullTypes: string[] = [];
+  const types: string[] = [];
+  const groupMap = new Map<string, PropertyValue[]>();
+  const valuesByPredicate = new Map<string, string[]>();
+
+  for (const term of result.termBindings) {
+    const predicate = term.p?.value ?? "";
+    const objectTerm = term.o;
+    if (objectTerm === undefined) continue;
+
+    const rawValues = valuesByPredicate.get(predicate) ?? [];
+    rawValues.push(objectTerm.value);
+    valuesByPredicate.set(predicate, rawValues);
+
+    if (predicate === RDF_TYPE) {
+      fullTypes.push(objectTerm.value);
+      types.push(compactUri(objectTerm.value, prefixes));
+      continue;
+    }
+
+    const compactPred = compactUri(predicate, prefixes);
+    const existing = groupMap.get(compactPred) ?? [];
+    if (objectTerm.termType === "NamedNode") {
+      existing.push({
+        type: "uri",
+        uri: objectTerm.value,
+        prefixed: compactUri(objectTerm.value, prefixes),
+        label: index.labelByUri.get(objectTerm.value) ?? null,
+      });
+    } else if (objectTerm.termType === "BlankNode") {
+      existing.push({ type: "bnode", id: objectTerm.value });
+    } else {
+      existing.push({ type: "literal", value: objectTerm.value });
+    }
+    groupMap.set(compactPred, existing);
+  }
+
+  const classification = classifyEntity(fullTypes) ?? {
+    box: "abox" as const,
+    category: "individual" as const,
+  };
+  const prefix = findNamespace(fullUri, Object.entries(prefixes))?.prefix;
+  const label = pickFirstValue(
+    valuesByPredicate,
+    resolveLabelPredicates(prefix),
+  );
+  const description = pickFirstValue(
+    valuesByPredicate,
+    resolveDescriptionPredicates(prefix),
+  );
+
+  const properties: PropertyGroup[] = [...groupMap.entries()].map(
+    ([predicate, values]) => ({ predicate, values }),
+  );
+
+  const base: ResourceEntity = {
+    uri: fullUri,
+    prefixed: compactUri(fullUri, prefixes),
+    box: classification.box,
+    category: classification.category,
+    types,
+    label,
+    description,
+    properties,
+  };
+
+  if (classification.category === "class") {
+    const [subClasses, declaredProperties] = await Promise.all([
+      fetchReferencingSubjects(store, RDFS_SUBCLASS_OF, fullUri, prefixes),
+      fetchReferencingSubjects(store, RDFS_DOMAIN, fullUri, prefixes),
+    ]);
+    return {
+      ...base,
+      superClasses: (valuesByPredicate.get(RDFS_SUBCLASS_OF) ?? []).map((u) =>
+        compactUri(u, prefixes),
+      ),
+      subClasses,
+      instanceCount: index.instanceCountByType.get(fullUri) ?? 0,
+      declaredProperties,
+    };
+  }
+
+  if (classification.category === "individual") {
+    const primaryTypeFull = pickPrimaryType(fullTypes);
+    return {
+      ...base,
+      instanceOf:
+        primaryTypeFull === null ? null : compactUri(primaryTypeFull, prefixes),
+    };
+  }
+
+  return base;
+}

package/src/mcp/resources/registerResources.ts

@@ -0,0 +1,126 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { PragmaError } from "#error";
+import resolveUri from "../../domains/graph/helpers/resolveUri.js";
+import type { PragmaRuntime } from "../../domains/shared/runtime.js";
+import buildGraphIndex from "./buildGraphIndex.js";
+import buildResourceList from "./buildResourceList.js";
+import { COMPLETION_LIMIT } from "./constants.js";
+import rankUriCompletions from "./rankUriCompletions.js";
+import readEntity from "./readEntity.js";
+import type { GraphIndex, ListingTruncation } from "./types.js";
+
+/** RFC 6570 template capturing the whole (prefixed or full) URI as `uri`. */
+const URI_TEMPLATE = "{+uri}";
+
+const TEMPLATE_DESCRIPTION =
+  "Knowledge-graph entities from the ke store. TBox schema (owl:Class / property " +
+  "definitions) is listed first and in full; ABox individuals follow, grouped by " +
+  "class and capped per class. Category and box are carried in each entry's name, " +
+  "annotations.priority, and _meta. Read any entry by its prefixed URI " +
+  "(e.g. ds:global.component.button); autocomplete matches URI or label substrings.";
+
+/**
+ * Report capped individuals to stderr so truncation is never silent.
+ *
+ * @note Impure — writes to stderr.
+ */
+function warnTruncation(truncation: ListingTruncation): void {
+  const parts = [...truncation.droppedByType.entries()]
+    .filter(([, dropped]) => dropped > 0)
+    .map(([type, dropped]) => `${type}: ${dropped}`);
+  process.stderr.write(
+    `pragma MCP resources: capped ${truncation.totalDropped} individual(s) ` +
+      `from the listing (${parts.join(", ")}); reach them via URI autocomplete ` +
+      "or the graph_query tool.\n",
+  );
+}
+
+/** Read the single `uri` template variable, tolerating array expansion. */
+function readUriVariable(value: string | string[] | undefined): string {
+  const uri = Array.isArray(value) ? value.at(0) : value;
+  if (uri === undefined) {
+    throw PragmaError.invalidInput("uri", String(value), {
+      recovery: { message: "Provide a prefixed or full entity URI." },
+    });
+  }
+  return uri;
+}
+
+/**
+ * Register the graph-driven MCP resource surface on the server.
+ *
+ * One `{+uri}` template backs listing, autocomplete, and reads. The graph
+ * index is built once per runtime (the store is immutable after boot) and
+ * reused across calls, so autocomplete stays cheap. Listing separates TBox
+ * schema from ABox individuals and caps the instance long tail; reads return
+ * a box-aware payload.
+ *
+ * @param server - The MCP server to register resources on.
+ * @param runtime - The pragma runtime providing the ke store and prefixes.
+ *
+ * @note Impure — registers handlers and queries the store lazily.
+ */
+export default function registerResources(
+  server: McpServer,
+  runtime: PragmaRuntime,
+): void {
+  const { store } = runtime;
+  const prefixes = store.prefixes;
+
+  let indexPromise: Promise<GraphIndex> | undefined;
+  const getIndex = (): Promise<GraphIndex> => {
+    indexPromise ??= buildGraphIndex(store, prefixes);
+    return indexPromise;
+  };
+
+  const template = new ResourceTemplate(URI_TEMPLATE, {
+    list: async () => {
+      const index = await getIndex();
+      const { resources, truncation } = buildResourceList(index);
+      if (truncation.totalDropped > 0) warnTruncation(truncation);
+      return { resources };
+    },
+    complete: {
+      uri: async (value) => {
+        const index = await getIndex();
+        const candidates = index.entities.map((entity) => ({
+          prefixed: entity.prefixed,
+          label: entity.label,
+        }));
+        return rankUriCompletions(candidates, value, COMPLETION_LIMIT);
+      },
+    },
+  });
+
+  server.registerResource(
+    "graph-entity",
+    template,
+    { description: TEMPLATE_DESCRIPTION, mimeType: "application/json" },
+    async (url, variables) => {
+      try {
+        const prefixedUri = readUriVariable(variables.uri);
+        const fullUri = resolveUri(prefixedUri, prefixes);
+        const index = await getIndex();
+        const entity = await readEntity(store, fullUri, prefixes, index);
+        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/resources/types.ts

@@ -0,0 +1,128 @@
+/**
+ * Shared types for the MCP resource surface.
+ *
+ * These shapes flow from the bulk graph index (`buildGraphIndex`) through
+ * listing (`buildResourceList`), autocomplete (`rankUriCompletions`), and
+ * entity reads (`readEntity`). They live together because each stage
+ * consumes the previous stage's output — the box/category vocabulary is the
+ * spine that keeps TBox schema and ABox individuals distinguishable end to end.
+ */
+
+/** Whether an entity is schema (TBox) or an individual (ABox). */
+export type EntityBox = "tbox" | "abox";
+
+/** Fine-grained entity kind within its box. */
+export type EntityCategory = "class" | "property" | "individual";
+
+/** A literal object value in an entity read. */
+export interface PropertyValueLiteral {
+  readonly type: "literal";
+  readonly value: string;
+}
+
+/** A URI object value in an entity read, resolved to a summary. */
+export interface PropertyValueUri {
+  readonly type: "uri";
+  readonly uri: string;
+  readonly prefixed: string;
+  readonly label: string | null;
+}
+
+/** A blank-node object value in an entity read. */
+export interface PropertyValueBlank {
+  readonly type: "bnode";
+  readonly id: string;
+}
+
+/** One object value of a predicate in an entity read. */
+export type PropertyValue =
+  | PropertyValueLiteral
+  | PropertyValueUri
+  | PropertyValueBlank;
+
+/** All object values asserted for a single predicate. */
+export interface PropertyGroup {
+  readonly predicate: string;
+  readonly values: PropertyValue[];
+}
+
+/** One classified subject in the graph index. */
+export interface GraphEntity {
+  readonly uri: string;
+  readonly prefixed: string;
+  readonly box: EntityBox;
+  readonly category: EntityCategory;
+  /** Compacted `rdf:type` values. */
+  readonly types: string[];
+  /** Compacted primary type used for grouping and naming (individuals). */
+  readonly primaryType: string | null;
+  /** Compacted primary type label, or the type's local name. */
+  readonly primaryTypeLabel: string | null;
+  readonly label: string | null;
+  readonly description: string | null;
+}
+
+/** The in-memory index of all named-node subjects, built via bulk queries. */
+export interface GraphIndex {
+  readonly entities: GraphEntity[];
+  /** Full URI → resolved label, for cheap type-label and object-label joins. */
+  readonly labelByUri: ReadonlyMap<string, string>;
+  /** Full URI → count of subjects declaring it as an `rdf:type`. */
+  readonly instanceCountByType: ReadonlyMap<string, number>;
+}
+
+/** MCP resource annotations we emit (schema-valid subset). */
+export interface ResourceAnnotations {
+  readonly audience: ("assistant" | "user")[];
+  readonly priority: number;
+}
+
+/** A single resource entry returned from the `list` callback. */
+export interface ListedResource {
+  readonly uri: string;
+  readonly name: string;
+  readonly description?: string;
+  readonly mimeType: "application/json";
+  readonly annotations: ResourceAnnotations;
+  readonly _meta: Record<string, unknown>;
+}
+
+/** How many individuals a listing dropped, per capped class. */
+export interface ListingTruncation {
+  readonly totalDropped: number;
+  readonly droppedByType: ReadonlyMap<string, number>;
+}
+
+/** Result of building a resource listing from the graph index. */
+export interface ResourceListing {
+  readonly resources: ListedResource[];
+  readonly truncation: ListingTruncation;
+}
+
+/** A candidate for URI autocomplete: its compacted form and human label. */
+export interface UriCompletionCandidate {
+  readonly prefixed: string;
+  readonly label: string | null;
+}
+
+/** A read entity payload, shaped by its box. */
+export interface ResourceEntity {
+  readonly uri: string;
+  readonly prefixed: string;
+  readonly box: EntityBox;
+  readonly category: EntityCategory;
+  readonly types: string[];
+  readonly label: string | null;
+  readonly description: string | null;
+  readonly properties: PropertyGroup[];
+  /** Class read: compacted superclasses. */
+  readonly superClasses?: string[];
+  /** Class read: compacted direct subclasses. */
+  readonly subClasses?: string[];
+  /** Class read: number of asserted individuals. */
+  readonly instanceCount?: number;
+  /** Class read: compacted properties declaring this class as their domain. */
+  readonly declaredProperties?: string[];
+  /** Individual read: compacted primary class this individual belongs to. */
+  readonly instanceOf?: string | null;
+}

package/src/mcp/tools/index.ts

@@ -18,19 +18,26 @@ 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 {
+  compilePackToolSpecs,
+  deriveReservedVerbs,
+  nounVerbFromToolName,
+} from "../../domains/shared/stories/pack/index.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[] = [
+/**
+ * The full built-in MCP tool surface, in registration order.
+ *
+ * Exported so tests can derive the reserved-verb map from the identical
+ * array production consumes (see the cross-surface reservation invariant).
+ */
+export const allSpecs: readonly ToolSpec[] = [
   ...blockSpecs,
-  ...standardSpecs,
   ...modifierSpecs,
   ...tokenSpecs,
-  ...tierSpecs,
   ...configSpecs,
   ...ontologySpecs,
   ...graphSpecs,
@@ -54,4 +61,14 @@ export default function registerAllTools(
   for (const spec of allSpecs) {
     registerFromSpec(server, runtime, spec);
   }
+
+  // Story packs project onto the same surface. Leaf read nouns reserve only
+  // the (noun, verb) pairs they own, so a pack can add a verb no built-in
+  // owns; operational nouns (config, graph, …) stay reserved wholesale.
+  const reserved = deriveReservedVerbs(
+    allSpecs.map((spec) => nounVerbFromToolName(spec.name)),
+  );
+  for (const spec of compilePackToolSpecs(runtime, reserved)) {
+    registerFromSpec(server, runtime, spec);
+  }
 }