@skeletiq/mcp 0.1.1 → 0.2.0

package/README.md

@@ -85,7 +85,7 @@ change your provider keys, see billing, or delete your account, whatever scopes
 | Tool | What it does |
 |---|---|
 | `list_projects` | Find a project by name. Returns the candidates rather than guessing between them. |
-| `get_design` | Read a design, in one of six modes: `overview`, `component`, `brief`, `readiness`, `build_order`, `gaps`. |
+| `get_design` | Read a design, in one of six modes: `overview`, `component`, `brief`, `readiness`, `build_order`, `gaps`. `overview` and `component` resolve the design's `R`-ids to the requirements they name, and what became of each. |
 | `generate_architecture` | Design a system from a prompt. Spends credits and takes minutes. |
 | `get_generation_status` | Poll a generation started with `wait: false`. |
 | `critique_architecture` | Check a design against SkeletIQ's rules. Deterministic, free, stores nothing. Tell it the `domain` and the `exposure`. |

package/dist/index.js

@@ -5,7 +5,7 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 
 // src/config.ts
 var SERVER_NAME = "skeletiq";
-var SERVER_VERSION = "0.1.1";
+var SERVER_VERSION = "0.2.0";
 var DEFAULT_API_URL = "https://api.skeletiq.com";
 var TOKEN_PREFIX = "skq_";
 var ConfigError = class extends Error {
@@ -322,6 +322,40 @@ var ArchitectureJsonSchema = z.looseObject({
   assumptions: z.array(GapEntrySchema).nullable().optional(),
   open_questions: z.array(GapEntrySchema).nullable().optional()
 });
+var RequirementLedgerRowSchema = z.looseObject({
+  id: z.string(),
+  text: z.string().optional(),
+  kind: z.string().optional(),
+  source: z.string().optional(),
+  /** `unmet` | `uncited` | `unchecked` | `cited` — deliberately never `met`. Left as a string: a
+   * value added server-side must not stop an older connector parsing the row. */
+  status: z.string().optional(),
+  verifier_checked: z.boolean().optional(),
+  cited_by_components: z.array(z.string()).nullable().optional(),
+  /** Indices into `architecture_json.grounded_decisions`, the raw array — blanks are not compacted. */
+  cited_by_decisions: z.array(z.number()).nullable().optional(),
+  added_in_version: z.number().nullable().optional()
+});
+var RequirementLedgerCountsSchema = z.looseObject({
+  total: z.number().optional(),
+  user_supplied: z.number().optional(),
+  llm_inferred: z.number().optional(),
+  unmet: z.number().optional(),
+  uncited: z.number().optional(),
+  unchecked: z.number().optional(),
+  cited: z.number().optional()
+});
+var RequirementLedgerSchema = z.looseObject({
+  rows: z.array(RequirementLedgerRowSchema).nullable().optional(),
+  analysis_version: z.number().nullable().optional(),
+  analysis_degraded: z.boolean().optional(),
+  /** `grounded` | `not_grounded` | `diverged`. */
+  grounding_state: z.string().optional(),
+  /** `ran` | `partial` | `not_run`. */
+  verification_state: z.string().optional(),
+  verified_version: z.number().nullable().optional(),
+  counts: RequirementLedgerCountsSchema.nullable().optional()
+});
 var ArchitectureSchema = z.looseObject({
   id: z.string(),
   project_id: z.string(),
@@ -332,7 +366,8 @@ var ArchitectureSchema = z.looseObject({
   created_at: z.string().optional(),
   updated_at: z.string().optional(),
   is_released: z.boolean().optional(),
-  released_at: z.string().nullable().optional()
+  released_at: z.string().nullable().optional(),
+  requirement_ledger: RequirementLedgerSchema.nullable().optional()
 });
 var ArchitecturePageSchema = z.looseObject({
   items: z.array(ArchitectureSchema),
@@ -1037,7 +1072,14 @@ function frameDetail(frame) {
 var constraintsInput = z4.strictObject({
   budget: z4.enum(["low", "medium", "high", "unlimited"]).optional(),
   max_latency_ms: z4.number().int().positive().optional(),
-  compliance: z4.array(z4.string()).optional().describe("e.g. HIPAA, SOC2, PCI-DSS, GDPR"),
+  // Free strings, not an enum, and the description has to say why. SkeletIQ assesses five
+  // frameworks; naming anything else is still worth doing, because an unassessed regime is
+  // recorded and reaches the design brief as a requirement the agent still has to satisfy.
+  // The old text read 'e.g. HIPAA, SOC2, PCI-DSS, GDPR' — it omitted SOX, which is the one
+  // an agent is least likely to guess, and said nothing about what happens to the rest.
+  compliance: z4.array(z4.string()).optional().describe(
+    "Regimes the design must satisfy. SOC2, HIPAA, PCI-DSS, GDPR and SOX are checked against requirement catalogues; any other regime is recorded and carried into the design brief as a requirement to satisfy, rather than checked."
+  ),
   preferred_cloud: z4.enum(["aws", "gcp", "azure", "any"]).optional(),
   preferred_technologies: z4.array(z4.string()).optional(),
   max_components: z4.number().int().positive().optional(),
@@ -1362,32 +1404,63 @@ async function describeCreated(resolver, architectureId) {
 import * as z5 from "zod/v4";
 
 // src/lib/slice.ts
-function sliceComponent(design, componentId) {
+function sliceComponent(design, componentId, ledger) {
   const components = design.components ?? [];
   const component = components.find((c) => c.id === componentId) ?? components.find((c) => normalize(c.name) === normalize(componentId));
   if (!component) return null;
   const connections = design.connections ?? [];
+  const related = relatedDecisions(design, component);
   return {
     component,
     outgoing: connections.filter((c) => c.source === component.id),
     incoming: connections.filter((c) => c.target === component.id),
-    related_decisions: relatedDecisions(design, component)
+    related_decisions: related,
+    assumed_decisions: assumedAmong(design, related),
+    ...ledger ? { cited_requirements: citedRequirements(ledger, component.id) } : {}
   };
 }
+function citedRequirements(ledger, componentId) {
+  return orderRequirementRows(
+    (ledger.rows ?? []).filter((row) => (row.cited_by_components ?? []).includes(componentId))
+  );
+}
+var STATUS_ORDER = ["unmet", "uncited", "unchecked", "cited"];
+function orderRequirementRows(rows) {
+  return [...rows].sort((a, b) => statusRank(a) - statusRank(b));
+}
+function statusRank(row) {
+  const index = STATUS_ORDER.indexOf(row.status ?? "");
+  return index === -1 ? STATUS_ORDER.length : index;
+}
 function decisionTexts(design) {
-  const seen = /* @__PURE__ */ new Set();
+  return decisionEntries(design).map((entry) => entry.text);
+}
+function decisionEntries(design) {
+  const byText = /* @__PURE__ */ new Map();
   const out = [];
-  const push2 = (text) => {
+  const push2 = (text, assumption) => {
     if (typeof text !== "string") return;
     const trimmed = text.trim();
-    if (trimmed.length === 0 || seen.has(trimmed)) return;
-    seen.add(trimmed);
-    out.push(trimmed);
+    if (trimmed.length === 0) return;
+    const existing = byText.get(trimmed);
+    if (existing) {
+      existing.assumption = existing.assumption || assumption;
+      return;
+    }
+    const entry = { text: trimmed, assumption };
+    byText.set(trimmed, entry);
+    out.push(entry);
   };
-  for (const decision of design.design_decisions ?? []) push2(decision);
-  for (const decision of design.grounded_decisions ?? []) push2(decision?.text);
+  for (const decision of design.design_decisions ?? []) push2(decision, false);
+  for (const decision of design.grounded_decisions ?? []) push2(decision?.text, decision?.assumption === true);
   return out;
 }
+function assumedAmong(design, texts) {
+  const assumed = new Set(
+    decisionEntries(design).filter((entry) => entry.assumption).map((entry) => entry.text)
+  );
+  return texts.filter((text) => assumed.has(text));
+}
 function relatedDecisions(design, component) {
   const needles = [component.name, component.technology].filter((value) => typeof value === "string" && value.trim().length > 2).map((value) => value.toLowerCase());
   if (needles.length === 0) return [];
@@ -1396,14 +1469,24 @@ function relatedDecisions(design, component) {
     return needles.some((needle) => haystack.includes(needle));
   });
 }
-function overview(design) {
+function overview(design, ledger) {
+  const decisions = decisionTexts(design);
   return {
     title: design.title ?? "Untitled design",
     description: design.description ?? "",
     components: design.components ?? [],
     connections: design.connections ?? [],
-    design_decisions: decisionTexts(design),
-    trade_offs: design.trade_offs ?? []
+    design_decisions: decisions,
+    // A subset of `design_decisions`, not a second list of decisions: which of them the design
+    // marks as resting on no cited source. Additive, so `design_decisions` stays the plain
+    // strings every existing caller reads.
+    assumed_decisions: assumedAmong(design, decisions),
+    trade_offs: design.trade_offs ?? [],
+    // Carried verbatim, rows in the server's order, and only when the version has one. This is
+    // a rebuild from named keys, so anything not named here is dropped without a trace — which
+    // is how `grounded_decisions` went missing for two releases. Re-sorting the rows on the way
+    // past would make "verbatim" untrue; the grouping belongs to the text that prints them.
+    ...ledger ? { requirement_ledger: ledger } : {}
   };
 }
 function normalize(value) {
@@ -1415,7 +1498,7 @@ var MODES = ["overview", "component", "brief", "readiness", "build_order", "gaps
 var input3 = z5.object({
   project_id: z5.string().describe("A SkeletIQ project id, or its exact name."),
   mode: z5.enum(MODES).describe(
-    "overview: the whole design. component: one component, its connections in both directions, and the decisions that mention it. brief: the fenced markdown block to write into AGENTS.md. readiness: what still has to be decided before this design is worth building. build_order: the order to build components in, and why. gaps: the open questions and unconfirmed assumptions in the design."
+    "overview: the whole design, and the requirements it was built from with what became of each. component: one component, its connections in both directions, the decisions that mention it, and the requirements the design cites it for. brief: the fenced markdown block to write into AGENTS.md. readiness: what still has to be decided before this design is worth building. build_order: the order to build components in, and why. gaps: the open questions and unconfirmed assumptions in the design."
   ),
   component_id: z5.string().optional().describe('Required for mode "component". The component id, or its name.'),
   version: z5.number().int().positive().optional().describe("A specific version. Defaults to the latest released version, or the latest version if none is released.")
@@ -1431,12 +1514,19 @@ var output3 = z5.object({
   /** Mode-shaped. Deliberately loose: six modes cannot share one strict schema honestly. */
   data: z5.unknown()
 });
+function decisionsHeading(assumed, settled, withAssumptions) {
+  return assumed.length > 0 ? withAssumptions : settled;
+}
+function decisionLines(decisions, assumed) {
+  const marked = new Set(assumed);
+  return decisions.map((decision) => `- ${decision}${marked.has(decision) ? " (assumption)" : ""}`);
+}
 function registerGetDesign(server, client, resolver) {
   server.registerTool(
     "get_design",
     {
       title: "Read a SkeletIQ design",
-      description: 'Read a SkeletIQ architecture. Start with mode "brief" to orient \u2014 it returns a fenced block to write into AGENTS.md \u2014 then "build_order" for the sequence and "component" for each piece as you build it. Every answer states which version it came from and whether that version is a release.',
+      description: 'Read a SkeletIQ architecture. Start with mode "brief" to orient \u2014 it returns a fenced block to write into AGENTS.md \u2014 then "build_order" for the sequence and "component" for each piece as you build it. "overview" and "component" also resolve the R-ids the design carries to the requirements they name, and say what became of each. Every answer states which version it came from and whether that version is a release.',
       inputSchema: input3,
       outputSchema: output3,
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true }
@@ -1452,7 +1542,7 @@ function registerGetDesign(server, client, resolver) {
       switch (mode) {
         case "overview": {
           const design = await resolver.design(resolved.architectureId);
-          const data = overview(design.architecture_json);
+          const data = overview(design.architecture_json, design.requirement_ledger);
           const facts = factsFrom(resolved);
           return ok({ ...base, ...facts, data }, [
             `# ${data.title}`,
@@ -1462,6 +1552,10 @@ function registerGetDesign(server, client, resolver) {
             ...data.components.map(
               (c) => `- ${c.id} \u2014 ${c.name} (${c.type}${c.technology ? `, ${c.technology}` : ""})`
             ),
+            // Above the decisions because the two answer different questions, in
+            // this order: requirements are what was asked for, decisions are how
+            // the design answered.
+            ...requirementBlock(data.requirement_ledger),
             // The design's own reasoning, which this text used to omit entirely
             // while carrying it in the structured half — so an agent working from
             // what it was shown rebuilt every choice from scratch, and could
@@ -1469,8 +1563,12 @@ function registerGetDesign(server, client, resolver) {
             // like this", and the overview is where that gets asked.
             ...data.design_decisions.length ? [
               "",
-              "Decisions taken \u2014 these are settled, build to them:",
-              ...data.design_decisions.map((decision) => `- ${decision}`)
+              decisionsHeading(
+                data.assumed_decisions,
+                "Decisions taken \u2014 these are settled, build to them:",
+                "Decisions taken \u2014 build to them; confirm the ones marked (assumption) first, they rest on no cited source:"
+              ),
+              ...decisionLines(data.design_decisions, data.assumed_decisions)
             ] : [],
             ...data.trade_offs.length ? [
               "",
@@ -1486,7 +1584,7 @@ function registerGetDesign(server, client, resolver) {
             return failure('mode "component" needs a component_id. Use mode "overview" or "build_order" to see the ids.');
           }
           const design = await resolver.design(resolved.architectureId);
-          const slice = sliceComponent(design.architecture_json, component_id);
+          const slice = sliceComponent(design.architecture_json, component_id, design.requirement_ledger);
           if (!slice) {
             const known = (design.architecture_json.components ?? []).map((c) => c.id).join(", ");
             return failure(
@@ -1502,6 +1600,9 @@ function registerGetDesign(server, client, resolver) {
             "",
             outgoing.length ? `Calls: ${outgoing.map((c) => `${c.target}${c.protocol ? ` (${c.protocol})` : ""}`).join(", ")}` : "Calls nothing.",
             incoming.length ? `Called by: ${incoming.map((c) => c.source).join(", ")}` : "Called by nothing in the design.",
+            // Same order as the overview: what was asked for, then how the design
+            // answered.
+            ...requirementsServed(slice.cited_requirements),
             // Labelled, and only when there are any. These bullets used to be
             // printed bare under "Called by:", so a decision about the component
             // read as a continuation of its edge list — and a design with no
@@ -1509,8 +1610,12 @@ function registerGetDesign(server, client, resolver) {
             // with no reasoning rather than as a decision that names other boxes.
             ...slice.related_decisions.length ? [
               "",
-              "Decisions that mention it:",
-              ...slice.related_decisions.map((decision) => `- ${decision}`)
+              decisionsHeading(
+                slice.assumed_decisions,
+                "Decisions that mention it:",
+                "Decisions that mention it \u2014 confirm the ones marked (assumption) first, they rest on no cited source:"
+              ),
+              ...decisionLines(slice.related_decisions, slice.assumed_decisions)
             ] : [
               "",
               "No decision in this design names this component. That is not the same as",
@@ -1637,6 +1742,49 @@ function registerGetDesign(server, client, resolver) {
     })
   );
 }
+function requirementBlock(ledger) {
+  const rows = orderRequirementRows(ledger?.rows ?? []);
+  if (!ledger || rows.length === 0) return [];
+  const attention = ["unmet", "uncited", "unchecked"].map((status) => [rows.filter((row) => row.status === status).length, status]).filter(([count]) => count > 0).map(([count, status]) => `${count} ${status}`);
+  return [
+    "",
+    `Requirements \u2014 ${rows.length} total${attention.length ? `; ${attention.join(", ")}` : ""}:`,
+    ...rows.map(requirementLine),
+    "Statuses: `unmet` \u2014 the verifier judged the design does not satisfy it; `uncited` \u2014 nothing",
+    "in the design claims to address it; `unchecked` \u2014 something cites it and the verifier did not",
+    "check it; `cited` \u2014 cited with no gap found, which is not the same as proven.",
+    // Two facts about how far the statuses can be trusted, said only when the server states
+    // them. An absent `verification_state` is an older server, not a verifier that did not run,
+    // and claiming the second would be this package inventing a fact about someone's design.
+    ...ledger.grounding_state === "not_grounded" ? [
+      "This version records no citations at all, so `uncited` here means nothing recorded what",
+      "addresses the requirement \u2014 not that nothing in the design does."
+    ] : [],
+    ...ledger.verification_state === "partial" ? [
+      "The verifier did not check every requirement in this set, so an `unchecked` row is",
+      "neither confirmed nor flagged."
+    ] : ledger.verification_state === "not_run" ? [
+      "The verifier did not run on this version, so an `unchecked` row is neither confirmed",
+      "nor flagged."
+    ] : [],
+    ...ledger.analysis_degraded ? ["The requirements analysis for this version ran degraded. Treat the list as incomplete."] : []
+  ];
+}
+function requirementsServed(rows) {
+  if (!rows?.length) return [];
+  return [
+    "",
+    "Requirements the design cites this component for:",
+    ...rows.map(requirementLine),
+    "`unmet` \u2014 the verifier judged the design does not satisfy it; `unchecked` \u2014 the verifier did",
+    "not check it; `cited` \u2014 no gap found, which is not the same as proven."
+  ];
+}
+function requirementLine(row) {
+  const status = row.status ? ` [${row.status}]` : "";
+  const text = (row.text ?? "").replace(/\s+/g, " ").trim();
+  return `- ${row.id}${status} ${text || "(no text recorded for this requirement)"}`;
+}
 function settledAnswer(gap) {
   const note = (gap.note ?? "").trim();
   if (gap.adr_id) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skeletiq/mcp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Design in SkeletIQ, build with your coding agent. MCP server for the SkeletIQ architecture platform.",
   "license": "MIT",
   "author": "Sabhahith Works Private Limited",