@pymodel/niblet 0.1.1 → 0.2.0

package/README.md

@@ -40,7 +40,10 @@ Two tools, matching the hosted service exactly:
 | `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. |
 
-Plus `niblet://skill`, which serves the bundled design workflow and needs no token.
+| `niblet_help` | “What can Niblet do?”, or choosing between commands. Lists the four surface modes and every command with its purpose; pass `command` for one entry. |
+| `niblet_status` | Diagnosing the connection. Reports the configured origins, whether a usable token is present (never the token), which bundled documents are readable, and whether the API actually answers. |
+
+The bundled documents are served as resources and need no token: `niblet://skill` for the workflow, plus `niblet://skill/commands`, `niblet://skill/connection`, `niblet://skill/evidence`, and `niblet://skill/native`. Their cross-links are rewritten to these URIs on the way out, so an agent reading them over MCP can follow every reference.
 
 ## Connect
 
@@ -109,7 +112,7 @@ npm ci --ignore-scripts
 cp .env.example .env   # then put your token in NIBLET_TOKEN
 ```
 
-`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 tool list and every `niblet://skill` resource — a resource that registers but never appears in `resources/list` is the failure the unit tests cannot catch. For documentation, check that relative links resolve and 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pymodel/niblet",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "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;
+}