@pymodel/niblet 0.1.1 → 0.2.1

package/README.md

@@ -5,8 +5,6 @@
   </picture>
 </p>
 
-<h1 align="center">Niblet MCP</h1>
-
 <p align="center">Real screen references and a design skill, for coding agents that build UI.</p>
 
 <p align="center">
@@ -27,31 +25,44 @@
   By <a href="https://github.com/elkaix">elkaix</a> for <a href="https://github.com/PyModel">PyModel</a>
 </p>
 
-An MCP server that gives a coding agent two things while it builds UI: real screen references from the [Niblet](https://niblet.com) catalogue, and a design skill that keeps the agent working from your product instead of a generic template.
+A coding agent building UI gets two things here: a design skill that keeps it working from your product rather than a generic template, and real screen references from the [Niblet](https://niblet.com) catalogue when a specific visual question is still open.
 
-The skill works on its own. The MCP server is optional, and needs a token.
+The skill works alone. The server is optional and needs a token.
 
-## What you get
+## Install the skill
 
-Two tools, matching the hosted service exactly:
+```sh
+npx skills add PyModel/niblet-skill-mcp --skill niblet -y
+```
 
-| Tool | Use it for |
-| --- | --- |
-| `find_ui_references` | One concrete unresolved question about a layout, state, or interaction. Returns one to three real screens as inline images. |
-| `find_ui_materials` | A named font, icon, or animated icon role your design system does not already cover. Returns the recorded license with each result. |
+Or copy it yourself, keeping `references/`, `agents/`, `LICENSE`, and `NOTICE` alongside it:
+
+```sh
+cp -r skill/niblet ~/.claude/skills/niblet
+```
 
-Plus `niblet://skill`, which serves the bundled design workflow and needs no token.
+Then ask for it by name:
+
+> Use Niblet to design the checkout empty and error states.
 
-## Connect
+The [workflow](skill/niblet/SKILL.md) settles the screen's job, primary action, hierarchy, existing tokens, real states, and acceptance criteria before writing anything. It finishes by rendering the surface and exercising it, so a green build on its own does not count as a pass.
 
-You do not have to run this server. If your host speaks HTTP MCP, point it at the hosted endpoint and skip to [the skill](#the-skill):
+## Connect the server
+
+Pick one. Hosted, if your host speaks HTTP MCP:
 
 ```sh
 claude mcp add --transport http niblet https://api.niblet.com/mcp \
   --header "Authorization: Bearer $NIBLET_TOKEN"
 ```
 
-To run it locally over stdio instead, add this to your host's MCP config. Node.js 24.15 or later is required; npx fetches the package on first launch.
+Local over stdio, via the Claude Code CLI:
+
+```sh
+claude mcp add niblet --env NIBLET_TOKEN=$NIBLET_TOKEN -- npx -y @pymodel/niblet
+```
+
+Or the equivalent in any host's MCP config file:
 
 ```json
 {
@@ -65,40 +76,46 @@ To run it locally over stdio instead, add this to your host's MCP config. Node.j
 }
 ```
 
-Or with the Claude Code CLI:
+Node.js 24.15+; npx fetches the package on first launch. Get a token from [niblet.com/docs](https://niblet.com/docs) and keep it in your host's environment, never in a committed file or a chat message.
 
-```sh
-claude mcp add niblet --env NIBLET_TOKEN=$NIBLET_TOKEN -- npx -y @pymodel/niblet
-```
-
-Saving the config does not register the server — check the tool list your host actually reports.
-
-Get a token from [niblet.com/docs](https://niblet.com/docs). Keep it in `.env` or your host's environment; never in a committed file or a chat message.
+Saving the config does not register the server, so confirm it worked. `niblet_status` reports the configured origins, whether a usable token is present, and whether the API answers:
 
-`NIBLET_API_ORIGIN` and `NIBLET_MEDIA_ORIGIN` retarget the server at a local deployment. Leave them unset for production.
-
-## The skill
+```
+Token:        present (44 characters, not shown).
+Documents:    5/5 readable (niblet://skill, …).
+API check:    OK
+```
 
-<img src="https://raw.githubusercontent.com/PyModel/niblet-skill-mcp/main/assets/niblet-mascot-working.svg" alt="" width="72" height="72" align="right">
+## Tools
 
-Install it straight from the repository:
+| Tool | Use it for | Token |
+| --- | --- | --- |
+| `find_ui_references` | One concrete unresolved question about a layout, state, or interaction. Returns one to three real screens as inline images. | yes |
+| `find_ui_materials` | A font, icon, or animated icon role your design system does not already cover. Returns the recorded license with each result. | yes |
+| `niblet_help` | "What can Niblet do?", or choosing between commands. Lists the four surface modes and every command; pass `command` for one entry. | no |
+| `niblet_status` | Diagnosing the connection before concluding the catalogue is empty. Never prints the token. | no |
 
-```sh
-npx skills add PyModel/niblet-skill-mcp --skill niblet -y
-```
+The two catalogue tools match the hosted service exactly. `niblet_help` and `niblet_status` are local-only.
 
-Or copy [skill/niblet](skill/niblet) into your host's skill directory yourself, keeping `references/`, `agents/`, `LICENSE`, and `NOTICE` alongside it:
+## Resources
 
-```sh
-cp -r skill/niblet ~/.claude/skills/niblet
-```
+The bundled documents, served without a token. Cross-links between them are rewritten to these URIs, so an agent reading one can follow every reference.
 
-Then ask for it by name:
+| URI | Contents |
+| --- | --- |
+| `niblet://skill` | The design workflow: modes, contract, state coverage, finish gate |
+| `niblet://skill/commands` | Every command, its scope, and what completion means |
+| `niblet://skill/connection` | Installing, invoking, and diagnosing the tools |
+| `niblet://skill/evidence` | When to pull an external reference, and how to use one |
+| `niblet://skill/native` | Platform constraints and the native finish gate |
 
-> Use Niblet to design the checkout empty and error states.
-> Run a niblet-skill review of the settings screen.
+## Configuration
 
-The [workflow](skill/niblet/SKILL.md) makes the agent establish the screen's job, primary action, hierarchy, existing tokens, real states, and acceptance criteria before it writes anything. It pulls references only when a specific question is still open, and it finishes by rendering the surface and exercising it. A green build is not a pass.
+| Variable | Purpose |
+| --- | --- |
+| `NIBLET_TOKEN` | Required by the two catalogue tools. |
+| `NIBLET_API_ORIGIN` | Retarget at a local deployment. Unset for production. |
+| `NIBLET_MEDIA_ORIGIN` | Same, for images. Unset for production. |
 
 ## Contributing
 
@@ -107,11 +124,12 @@ git clone https://github.com/PyModel/niblet-skill-mcp
 cd niblet-skill-mcp
 npm ci --ignore-scripts
 cp .env.example .env   # then put your token in NIBLET_TOKEN
+npm test
 ```
 
-`npm test` covers the tool contract and its failure boundaries. For anything touching startup or configuration, also connect a real MCP client and confirm the tool list and `niblet://skill`. For documentation, check that relative links resolve and that `npm pack --dry-run` still ships what you expect.
+`npm test` covers the tool contract and its failure boundaries. For anything touching startup or configuration, also connect a real MCP client and confirm the reported tool list and every `niblet://skill` resource. A resource that registers but never appears in `resources/list` is the failure unit tests cannot catch. For documentation, check that `npm pack --dry-run` still ships what you expect.
 
-[AGENTS.md](AGENTS.md) has the details if you are pointing a coding agent at this repository.
+[AGENTS.md](AGENTS.md) has the working agreement for pointing a coding agent at this repository.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pymodel/niblet",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Niblet MCP server and design skill: real UI screen references for coding agents",
   "keywords": [
     "mcp",

package/skill/niblet/SKILL.md

@@ -3,7 +3,7 @@ name: niblet
 description: Keep interface work anchored to the product it belongs to instead of a generic template. Sets a short design contract, builds from the components and tokens already in the codebase, covers the states a surface can actually reach, and closes by looking at the rendered result. Use when building, reworking, or assessing a web or native interface. Trigger with "niblet", "niblet skill", "niblet designer ui", or "niblet review". Skip backend, CLI, data, and infrastructure work, prose-only tasks, and questions the product's own design system already settles.
 license: Apache-2.0
 metadata:
-  version: "0.1.1"
+  version: "0.2.0"
   author: "Mohamed Elkholy (elkaix)"
   organization: "PyModel"
   source: "https://github.com/PyModel/niblet-skill-mcp"

package/src/server.mjs

@@ -1,7 +1,9 @@
-import { readFile } from 'node:fs/promises';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
+import { SKILL_DOCS, parseCommands, parseModes, readSkillDoc, uriFor } from './skill.mjs';
+// The advertised server version is the package version; nothing else to keep in step.
+import pkg from '../package.json' with { type: 'json' };
 
 const DEFAULT_API_ORIGIN = 'https://api.niblet.com';
 const DEFAULT_MEDIA_ORIGIN = 'https://media.niblet.com';
@@ -138,7 +140,9 @@ function listOf(data, key) {
 }
 
 /**
- * Create a local stdio server exposing the same two tools as the hosted Niblet MCP service.
+ * Create a local stdio server. It exposes the hosted service's two catalogue tools with
+ * identical contracts, plus local-only helpers that read bundled files and need no token:
+ * niblet_help, niblet_status, and every skill document as a resource.
  * Token, origins, and fetch injection are for embedding and tests; they never widen the
  * destination allowlist beyond the configured API and media origins.
  */
@@ -152,8 +156,8 @@ export function createServer({
   const MEDIA_ORIGINS = new Set([originOf(mediaOrigin, DEFAULT_MEDIA_ORIGIN), API_ORIGIN]);
 
   const server = new McpServer(
-    { name: 'niblet', version: '1.0.0', websiteUrl: 'https://niblet.com' },
-    { instructions: `Read niblet://skill for the Niblet design workflow. ${UNTRUSTED_DATA} Both tools require NIBLET_TOKEN; the bundled skill does not. This server only reads ${API_ORIGIN}/v1 and does not provide a remote UI review service.` },
+    { name: 'niblet', version: pkg.version, websiteUrl: 'https://niblet.com' },
+    { instructions: `Read niblet://skill for the Niblet design workflow; its reference documents are served alongside it (niblet://skill/commands, /connection, /evidence, /native). Call niblet_help to list the surface modes and every design command, or when asked what Niblet can do; call niblet_status to diagnose the connection before concluding the catalogue is empty. ${UNTRUSTED_DATA} The two catalogue tools require NIBLET_TOKEN; the bundled skill, niblet_help, and niblet_status do not. This server only reads ${API_ORIGIN}/v1 and does not provide a remote UI review service.` },
   );
 
   function credentialError() {
@@ -328,17 +332,137 @@ export function createServer({
     return textResult([MATERIAL_PREAMBLE, '', ...materials.map(materialText)].join('\n'));
   });
 
-  server.registerResource('niblet-skill', 'niblet://skill', {
-    title: 'Niblet design skill',
-    description: 'The bundled Niblet design workflow. Available without an API token.',
-    mimeType: 'text/markdown',
-  }, async (uri) => {
-    try {
-      const text = await readFile(new URL('../skill/niblet/SKILL.md', import.meta.url), 'utf8');
+  // Every bundled document is served, not just SKILL.md: SKILL.md directs the agent
+  // to the command playbook, the evidence policy, and the native guidance, and over
+  // stdio those relative paths are unresolvable unless each one is also a resource.
+  for (const [slug, { title, description }] of Object.entries(SKILL_DOCS)) {
+    server.registerResource(slug === 'skill' ? 'niblet-skill' : `niblet-skill-${slug}`, uriFor(slug), {
+      title,
+      description,
+      mimeType: 'text/markdown',
+    }, async (uri) => {
+      const text = await readSkillDoc(slug);
+      if (text === null) throw new McpError(ErrorCode.InternalError, 'The bundled Niblet skill could not be read. Reinstall the package.');
       return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text }] };
+    });
+  }
+
+  const localAnnotations = { ...annotations, openWorldHint: false };
+
+  server.registerTool('niblet_help', {
+    title: 'Niblet help',
+    description: 'List everything Niblet offers: the surface modes, every design command with its purpose, and the reference documents available as resources. Use when asked what Niblet can do, which command fits, or to present the choice menu before making changes.',
+    inputSchema: z.object({
+      command: z.string().min(1).max(64).optional().describe('A command name, to locate its section and full playbook entry.'),
+    }).strict(),
+    annotations: localAnnotations,
+  }, async (input) => {
+    let skillDoc;
+    let commandsDoc;
+    try {
+      [skillDoc, commandsDoc] = await Promise.all([readSkillDoc('skill'), readSkillDoc('commands')]);
     } catch {
-      throw new McpError(ErrorCode.InternalError, 'The bundled Niblet skill could not be read. Reinstall the package.');
+      return errorResult('The bundled Niblet documents could not be read. Reinstall the package.');
+    }
+    const sections = parseCommands(commandsDoc ?? '');
+    const all = sections.flatMap((s) => s.commands.map((c) => ({ ...c, section: s.section })));
+
+    if (input.command) {
+      const wanted = input.command.trim().toLowerCase().replace(/^\//, '');
+      const match = all.find((c) => c.names.some((n) => n.toLowerCase() === wanted));
+      if (!match) {
+        return textResult([
+          `No Niblet command named "${input.command}".`,
+          `Available: ${all.flatMap((c) => c.names).join(', ')}.`,
+          `Full playbook: ${uriFor('commands')}`,
+        ].join('\n'));
+      }
+      return textResult([
+        `${match.names.map((n) => `\`${n}\``).join(' / ')} — ${match.purpose}`,
+        `Section: ${match.section}.`,
+        '',
+        `Read ${uriFor('commands')} for the full entry, and ${uriFor('skill')} for the design contract and finish gate every implementation command applies.`,
+      ].join('\n'));
+    }
+
+    // A compact index rather than the whole playbook: SKILL.md's routing rule asks for
+    // a short menu and a choice, not a wall of text.
+    const modes = parseModes(skillDoc ?? '');
+    const lines = ['Niblet keeps interface work anchored to the product it belongs to. Pick a mode and a command, then work under a design contract.'];
+    if (modes.length) {
+      lines.push('', 'Surface modes — choose by the job of the surface:');
+      for (const m of modes) lines.push(`  ${m.mode} — ${m.job} (${m.surfaces})`);
+    }
+    for (const section of sections) {
+      lines.push('', `${section.section}:`);
+      for (const c of section.commands) lines.push(`  ${c.names.join(' / ')} — ${c.purpose}`);
+    }
+    lines.push('', 'Reference documents (read as MCP resources):');
+    for (const [slug, doc] of Object.entries(SKILL_DOCS)) lines.push(`  ${uriFor(slug)} — ${doc.title}`);
+    lines.push('', 'Catalogue tools: find_ui_references (real full-screen references), find_ui_materials (license-recorded fonts and icons). Both need NIBLET_TOKEN; run niblet_status to check. Reference retrieval is optional and never a prerequisite to useful work.');
+    lines.push('With no target or command, present this menu and wait for a choice rather than making changes.');
+    return textResult(lines.join('\n'));
+  });
+
+  server.registerTool('niblet_status', {
+    title: 'Niblet status',
+    description: 'Diagnose this Niblet connection: configured origins, whether a usable token is present, the bundled documents, and whether the catalogue API actually answers. Use before concluding that the catalogue is empty or broken.',
+    inputSchema: z.object({
+      probe: z.boolean().default(true).describe('Contact the configured API to confirm it answers. Set false to report configuration only.'),
+    }).strict(),
+    // The probe is the reported result, so this one does reach the configured origin.
+    annotations,
+  }, async (input, extra) => {
+    const lines = ['Niblet MCP status.', '', `API origin:   ${API_ORIGIN}`, `Media origins: ${[...MEDIA_ORIGINS].join(', ')}`];
+
+    // Presence and shape only — the playbook's doctor entry requires never displaying it.
+    const credential = credentialError();
+    if (typeof token !== 'string' || token.trim() === '') lines.push('Token:        not configured. Set NIBLET_TOKEN in the MCP server environment.');
+    else if (credential) lines.push('Token:        present but malformed for a bearer credential. Check NIBLET_TOKEN.');
+    else lines.push(`Token:        present (${token.trim().length} characters, not shown).`);
+
+    const docs = await Promise.all(Object.keys(SKILL_DOCS).map(async (slug) => {
+      try {
+        return (await readSkillDoc(slug)) ? slug : null;
+      } catch {
+        return null;
+      }
+    }));
+    const readable = docs.filter(Boolean);
+    lines.push(`Documents:    ${readable.length}/${Object.keys(SKILL_DOCS).length} readable (${readable.map(uriFor).join(', ')}).`);
+    lines.push('Tools:        find_ui_references, find_ui_materials, niblet_help, niblet_status.');
+
+    if (!input.probe) {
+      lines.push('', 'API not contacted (probe disabled).');
+      return textResult(lines.join('\n'));
+    }
+    if (credential) {
+      lines.push('', 'API not contacted: no usable token. The bundled documents and niblet_help remain available without one.');
+      return textResult(lines.join('\n'));
+    }
+
+    const result = await requestJson(['stats'], {}, extra.signal);
+    if (!result.ok) {
+      // Any HTTP status means the origin answered, which is what reachability asks.
+      // /v1/stats is not part of the hosted contract, so a 404 is a normal answer
+      // from a healthy deployment, not a failure.
+      if (result.status === 404) {
+        lines.push('', 'API check:    reachable — the configured origin answered. It does not serve catalogue counts; use find_ui_references to confirm the catalogue itself.');
+        return textResult(lines.join('\n'));
+      }
+      if (result.status !== undefined) {
+        lines.push('', `API check:    reachable, but the request was rejected — ${result.message}`);
+        return textResult(lines.join('\n'));
+      }
+      lines.push('', `API check:    FAILED — ${result.message}`);
+      lines.push(`Check that the configured origin is correct and that the service is actually running, then read the connection guide at ${uriFor('connection')}.`);
+      return textResult(lines.join('\n'));
     }
+    const counts = ['apps', 'screens', 'captioned', 'journeys']
+      .map((key) => (typeof result.data[key] === 'number' ? `${key} ${result.data[key]}` : null))
+      .filter(Boolean);
+    lines.push('', `API check:    OK${counts.length ? ` — catalogue holds ${counts.join(', ')}.` : '.'}`);
+    return textResult(lines.join('\n'));
   });
 
   return server;

package/src/skill.mjs

@@ -0,0 +1,103 @@
+/**
+ * Bundled-skill access: reading the documents, making their cross-links usable
+ * over MCP, and deriving the command index from them.
+ *
+ * The same files are also loaded directly as a filesystem skill, where the
+ * relative links between them are correct. They are only wrong for a client that
+ * reads them over stdio and has no access to the package directory, so the
+ * rewrite happens on the way out rather than in the files themselves.
+ */
+import { readFile } from 'node:fs/promises';
+
+/** slug -> { file, title, description }. `skill` is SKILL.md; the rest are its references. */
+export const SKILL_DOCS = {
+  skill: {
+    file: 'SKILL.md',
+    title: 'Niblet design skill',
+    description: 'The bundled Niblet design workflow: modes, design contract, state coverage, and the rendered finish gate. Available without an API token.',
+  },
+  commands: {
+    file: 'references/commands.md',
+    title: 'Niblet command playbook',
+    description: 'Every Niblet command — what it does, its scope, and what completion means. Referenced by the design workflow.',
+  },
+  connection: {
+    file: 'references/connection.md',
+    title: 'Niblet connection guide',
+    description: 'Installing and invoking the MCP tools, diagnosing a connection, and the limits of host-dependent helpers.',
+  },
+  evidence: {
+    file: 'references/evidence.md',
+    title: 'Niblet evidence policy',
+    description: 'When to retrieve an external reference, and how to use one without copying it.',
+  },
+  native: {
+    file: 'references/native.md',
+    title: 'Niblet native platform guidance',
+    description: 'Platform constraints and the native finish-gate batch for iOS and other native work.',
+  },
+};
+
+export const uriFor = (slug) => (slug === 'skill' ? 'niblet://skill' : `niblet://skill/${slug}`);
+
+/** Relative markdown targets in the bundled docs -> the resource URI serving the same document. */
+const LINK_REWRITES = [
+  [/\]\(\.\.\/SKILL\.md\)/g, `](${uriFor('skill')})`],
+  [/\]\(SKILL\.md\)/g, `](${uriFor('skill')})`],
+  ...Object.entries(SKILL_DOCS)
+    .filter(([slug]) => slug !== 'skill')
+    .flatMap(([slug]) => [
+      [new RegExp(`\\]\\(references/${slug}\\.md\\)`, 'g'), `](${uriFor(slug)})`],
+      [new RegExp(`\\]\\(${slug}\\.md\\)`, 'g'), `](${uriFor(slug)})`],
+    ]),
+];
+
+/**
+ * Point a document's cross-links at the resources that serve them. Without this a
+ * client that reads niblet://skill is told to open `references/commands.md`, a path
+ * it has no way to resolve.
+ */
+export function rewriteLinks(text) {
+  return LINK_REWRITES.reduce((acc, [pattern, replacement]) => acc.replace(pattern, replacement), text);
+}
+
+export async function readSkillDoc(slug) {
+  const entry = SKILL_DOCS[slug];
+  if (!entry) return null;
+  const text = await readFile(new URL(`../skill/niblet/${entry.file}`, import.meta.url), 'utf8');
+  return rewriteLinks(text);
+}
+
+/**
+ * The command index, derived from commands.md so it cannot drift from the playbook.
+ * Headings are `## Section` and ``### `name` — purpose``.
+ */
+export function parseCommands(markdown) {
+  const sections = [];
+  let current = null;
+  for (const line of markdown.split('\n')) {
+    const section = /^##\s+(?!#)(.+?)\s*$/.exec(line);
+    if (section) {
+      current = { section: section[1], commands: [] };
+      sections.push(current);
+      continue;
+    }
+    const command = /^###\s+(.+?)\s+—\s+(.+?)\s*$/.exec(line);
+    if (command && current) {
+      // Names arrive as `polish`, or `pin` / `unpin` for a paired helper.
+      const names = [...command[1].matchAll(/`([^`]+)`/g)].map((m) => m[1]);
+      if (names.length) current.commands.push({ names, purpose: command[2] });
+    }
+  }
+  return sections.filter((s) => s.commands.length);
+}
+
+/** The four surface modes, from the table in SKILL.md, for the same no-drift reason. */
+export function parseModes(markdown) {
+  const modes = [];
+  for (const line of markdown.split('\n')) {
+    const row = /^\|\s*\*\*(.+?)\*\*\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*$/.exec(line);
+    if (row) modes.push({ mode: row[1], job: row[2], surfaces: row[4] });
+  }
+  return modes;
+}