@skeletiq/mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,5 +1,10 @@
 # @skeletiq/mcp
 
+[![npm](https://img.shields.io/npm/v/@skeletiq/mcp)](https://www.npmjs.com/package/@skeletiq/mcp)
+[![licence](https://img.shields.io/npm/l/@skeletiq/mcp)](./LICENSE)
+[![node](https://img.shields.io/node/v/@skeletiq/mcp)](https://nodejs.org)
+[![CI](https://github.com/Sabhahith-Works/skeletiq-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Sabhahith-Works/skeletiq-mcp/actions/workflows/ci.yml)
+
 Design in [SkeletIQ](https://skeletiq.com), build with your coding agent.
 
 SkeletIQ turns a prompt into a critiqued system architecture — components, data stores,
@@ -58,11 +63,20 @@ A token grants only what you tick. The server's tools need:
 | Scope | What it unlocks | Tools |
 |---|---|---|
 | `read` | Projects, designs, briefs, build order, readiness, gaps, jobs | `list_projects`, `get_design`, `get_generation_status` |
-| `generate` | Running generations and payload critique. **Spends credits.** | `generate_architecture`, `critique_architecture` |
-| `report` | Recording what got built | `check_drift` |
+| `generate` | Running generations — **that spends credits** — and payload critique, which is free | `generate_architecture`, `critique_architecture` |
+| `report` | Recording what got built. **Needs `read` as well** | `check_drift` |
 
 `read` alone is a good starting point: the agent can orient and build, but cannot spend anything.
 
+Two things the table above cannot say in a cell:
+
+- **`report` on its own does nothing.** `check_drift` looks the project and the version up before it
+  can report against them, and those lookups are `read`. A `report`-only token is refused.
+- **`generate` without `read` still generates**, but the answer is thinner: the tool reads back the
+  design it just created to describe it, and reports that failure as a thinner answer rather than a
+  failed generation — telling an agent the generation failed would invite it to pay for the whole
+  thing again.
+
 Everything else is out of reach by construction — a token cannot mint another token, read or
 change your provider keys, see billing, or delete your account, whatever scopes it carries.
 
@@ -112,7 +126,40 @@ warns when a default was applied. Read those before reporting a score to a perso
 Whichever one the account holder chose under **Settings → Agent access**. The tools take no runtime
 argument, deliberately: the model asking for a design does not get to choose what it costs you.
 
+## Development
+
+This repository is the source of the published `@skeletiq/mcp` package. The connector is developed
+in SkeletIQ's monorepo, alongside the API it talks to, and mirrored here — so the history you see is
+the package's real history, not a squashed snapshot. A pull request opened here cannot be merged,
+because the next sync would overwrite it; [CONTRIBUTING.md](./CONTRIBUTING.md) explains what to do
+instead.
+
+Node 20 or newer.
+
+```bash
+npm install
+npm test          # vitest — hermetic: no network, no services, nothing to seed
+npm run build     # tsup, to dist/index.js
+npm run typecheck
+npm run lint
+```
+
+The tests mock the SkeletIQ API rather than calling it, so a clean clone runs them without a token
+and without an account.
+
+**If `npm install` fails with `Cannot read properties of null (reading 'edgesOut')`,** you are on npm
+10.9.x — the version Node 22 ships — which cannot resolve this tree; `vitest@4` alone triggers it.
+`npm install -g npm@11` fixes it. This affects cloning and building only: installing the published
+package with `npx` works on that npm.
+
 ## Licence
 
-MIT — see [LICENSE](./LICENSE). The rest of the SkeletIQ repository is AGPL-3.0-or-later; this
-connector is MIT so it can be embedded, vendored and forked freely.
+MIT — see [LICENSE](./LICENSE). Source:
+[Sabhahith-Works/skeletiq-mcp](https://github.com/Sabhahith-Works/skeletiq-mcp) — issues and questions
+go [there](https://github.com/Sabhahith-Works/skeletiq-mcp/issues).
+
+The SkeletIQ platform is AGPL-3.0-or-later; this connector is MIT so it can be embedded, vendored
+and forked freely.
+
+"SkeletIQ" is a mark of Sabhahith Works Private Limited — see [NOTICE](./NOTICE). Security reports go
+to security@skeletiq.com, not to the issue tracker: [SECURITY.md](./SECURITY.md).

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.0";
+var SERVER_VERSION = "0.1.1";
 var DEFAULT_API_URL = "https://api.skeletiq.com";
 var TOKEN_PREFIX = "skq_";
 var ConfigError = class extends Error {
@@ -303,12 +303,20 @@ var GapEntrySchema = z.union([
     impact: z.string().nullable().optional()
   })
 ]);
+var GroundedDecisionSchema = z.looseObject({
+  text: z.string(),
+  source_ids: z.array(z.string()).nullable().optional(),
+  requirement_ids: z.array(z.string()).nullable().optional(),
+  assumption: z.boolean().optional(),
+  confidence: z.string().optional()
+});
 var ArchitectureJsonSchema = z.looseObject({
   title: z.string().optional(),
   description: z.string().optional(),
   components: z.array(ComponentSchema).optional(),
   connections: z.array(ConnectionSchema).optional(),
   design_decisions: z.array(z.string()).nullable().optional(),
+  grounded_decisions: z.array(GroundedDecisionSchema).nullable().optional(),
   trade_offs: z.array(z.string()).nullable().optional(),
   scalability_notes: z.string().nullable().optional(),
   assumptions: z.array(GapEntrySchema).nullable().optional(),
@@ -387,7 +395,15 @@ var ReadinessSchema = z.looseObject({
   /** Keys of advisory rows whose check never ran. Named, never counted. */
   unrun_checks: z.array(z.string()).optional(),
   rows: z.array(ReadinessRowSchema),
-  release: ReleaseFactsSchema
+  release: ReleaseFactsSchema,
+  /**
+   * What releasing this version would be carrying, one sentence each. A warning, never a refusal.
+   *
+   * The same list the app shows beside its Release button, under the heading "It will carry:".
+   * Optional here only so a server that predates the field still parses — it is required on the
+   * wire, and an empty array is the server saying it looked and found nothing.
+   */
+  release_warnings: z.array(z.string()).optional()
 });
 var DesignGapSchema = z.looseObject({
   gap_id: z.string(),
@@ -398,12 +414,21 @@ var DesignGapSchema = z.looseObject({
   note: z.string().nullable().optional(),
   adr_id: z.string().nullable().optional()
 });
+var OrphanedAnswerSchema = z.looseObject({
+  gap_id: z.string(),
+  kind: z.string(),
+  action: z.string(),
+  note: z.string().nullable().optional(),
+  adr_id: z.string().nullable().optional()
+});
 var DesignGapListSchema = z.looseObject({
   project_id: z.string(),
   architecture_id: z.string().nullable().optional(),
   version: z.number().nullable().optional(),
   gaps: z.array(DesignGapSchema),
-  unresolved_count: z.number()
+  unresolved_count: z.number(),
+  /** Answers whose question is not in this version — recorded, not silently dropped. */
+  orphaned_answers: z.array(OrphanedAnswerSchema).optional()
 });
 var ComponentRefSchema = z.looseObject({
   id: z.string(),
@@ -1349,10 +1374,24 @@ function sliceComponent(design, componentId) {
     related_decisions: relatedDecisions(design, component)
   };
 }
+function decisionTexts(design) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  const push2 = (text) => {
+    if (typeof text !== "string") return;
+    const trimmed = text.trim();
+    if (trimmed.length === 0 || seen.has(trimmed)) return;
+    seen.add(trimmed);
+    out.push(trimmed);
+  };
+  for (const decision of design.design_decisions ?? []) push2(decision);
+  for (const decision of design.grounded_decisions ?? []) push2(decision?.text);
+  return out;
+}
 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 [];
-  return (design.design_decisions ?? []).filter((decision) => {
+  return decisionTexts(design).filter((decision) => {
     const haystack = decision.toLowerCase();
     return needles.some((needle) => haystack.includes(needle));
   });
@@ -1363,7 +1402,7 @@ function overview(design) {
     description: design.description ?? "",
     components: design.components ?? [],
     connections: design.connections ?? [],
-    design_decisions: design.design_decisions ?? [],
+    design_decisions: decisionTexts(design),
     trade_offs: design.trade_offs ?? []
   };
 }
@@ -1423,6 +1462,21 @@ function registerGetDesign(server, client, resolver) {
             ...data.components.map(
               (c) => `- ${c.id} \u2014 ${c.name} (${c.type}${c.technology ? `, ${c.technology}` : ""})`
             ),
+            // 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
+            // silently undo one. Said here because it is the answer to "why is it
+            // 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}`)
+            ] : [],
+            ...data.trade_offs.length ? [
+              "",
+              "Trade-offs the design accepts:",
+              ...data.trade_offs.map((tradeOff) => `- ${tradeOff}`)
+            ] : [],
             "",
             versionLine(facts)
           ].join("\n"));
@@ -1448,7 +1502,20 @@ 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.",
-            ...slice.related_decisions.map((decision) => `- ${decision}`),
+            // 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
+            // matching decision printed nothing at all, which reads as a design
+            // 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}`)
+            ] : [
+              "",
+              "No decision in this design names this component. That is not the same as",
+              `no reason \u2014 use mode "overview" for the design's decisions in full.`
+            ],
             "",
             versionLine(facts)
           ].join("\n"));
@@ -1500,6 +1567,16 @@ function registerGetDesign(server, client, resolver) {
             ...advisories.map(
               (row) => `- ${row.label}: ${describeRow(row)}${unrun.has(row.key) ? " (never run on this version)" : ""}`
             ),
+            // The same list, under the same heading, as the app shows beside its
+            // Release button. A person clicking Release is told what the release
+            // takes with it; an agent asking the same question of the same version
+            // was told nothing at all. A warning, never a refusal — it does not
+            // move the verdict and it does not stop anyone.
+            ...readiness.release_warnings?.length ? [
+              "",
+              "It will carry:",
+              ...readiness.release_warnings.map((warning) => `- ${warning}`)
+            ] : [],
             "",
             "Only a person can clear a gate. Ask; do not decide on their behalf.",
             versionLine(facts)
@@ -1530,6 +1607,7 @@ function registerGetDesign(server, client, resolver) {
           const facts = factsFrom(resolved);
           const unresolved = gaps.gaps.filter((gap) => !gap.resolved);
           const settled = gaps.gaps.filter((gap) => gap.resolved && gap.action !== "dismissed");
+          const orphaned = gaps.orphaned_answers ?? [];
           return ok({ ...base, ...facts, data: gaps }, [
             unresolved.length === 0 ? "Every open question and assumption in this design has been dealt with." : `${unresolved.length} unresolved:`,
             ...unresolved.map((gap) => `- [${gap.kind}] ${gap.text}`),
@@ -1538,6 +1616,16 @@ function registerGetDesign(server, client, resolver) {
               `${settled.length} settled during review \u2014 treat these as decided:`,
               ...settled.map((gap) => `- [${gap.kind}] ${gap.text} \u2192 ${settledAnswer(gap)}`)
             ] : [],
+            // A gap is identified by a hash of its own text, so a regeneration that
+            // re-words a question strands the answer that settled it. The server
+            // reports those rather than dropping them, and then this dropped them.
+            // A count and a sentence, not rows: the stored answer has no text to
+            // show, and it is not work anyone can pick up.
+            ...orphaned.length ? [
+              "",
+              `${orphaned.length} earlier answer(s) do not match any question in this version \u2014 re-worded or dropped when it was generated, or asked only in a different version. Any Decision they minted still stands.`,
+              ...orphaned.filter((answer) => answer.adr_id).map((answer) => `- [${answer.kind}] ${answer.action} \u2192 Decision ${answer.adr_id}`)
+            ] : [],
             "",
             "The unresolved ones are questions for a person, not for you to answer. Raise",
             "them; do not guess and build on the guess. An API token cannot resolve them \u2014",

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "@skeletiq/mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Design in SkeletIQ, build with your coding agent. MCP server for the SkeletIQ architecture platform.",
   "license": "MIT",
   "author": "Sabhahith Works Private Limited",
   "homepage": "https://skeletiq.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sabhahith-Works/skeletiq-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Sabhahith-Works/skeletiq-mcp/issues"
+  },
   "keywords": [
     "mcp",
     "modelcontextprotocol",