@pymodel/niblet 0.2.0 → 0.3.0

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,34 +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:
 
-| `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. |
+```sh
+cp -r skill/niblet ~/.claude/skills/niblet
+```
 
-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.
+Then ask for it by name:
 
-## Connect
+> Use Niblet to design the checkout empty and error states.
+
+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
 {
@@ -68,40 +76,49 @@ 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, so confirm it worked. `niblet_status` reports the configured origins, whether a usable token is present, and whether the API answers:
 
-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.
+```
+Token:        present (44 characters, not shown).
+Documents:    5/5 readable (niblet://skill, …).
+API check:    OK
+```
 
-`NIBLET_API_ORIGIN` and `NIBLET_MEDIA_ORIGIN` retarget the server at a local deployment. Leave them unset for production.
+## Tools
 
-## The skill
+| 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 |
+| `get_design_reference` | The colours, typography, and components recorded for a web screen you already picked. Pass the `screenId` from a reference, or a pack slug. | 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 |
 
-<img src="https://raw.githubusercontent.com/PyModel/niblet-skill-mcp/main/assets/niblet-mascot-working.svg" alt="" width="72" height="72" align="right">
+The three catalogue tools match the hosted service exactly. `niblet_help` and `niblet_status` are local-only.
 
-Install it straight from the repository:
+Only web screens carry a design reference, and a web result says so in its own text, so an agent that finds a screen worth borrowing from can read the system behind it in one follow-up call.
 
-```sh
-npx skills add PyModel/niblet-skill-mcp --skill niblet -y
-```
+## Resources
 
-Or copy [skill/niblet](skill/niblet) into your host's skill directory yourself, keeping `references/`, `agents/`, `LICENSE`, and `NOTICE` alongside it:
+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.
 
-```sh
-cp -r skill/niblet ~/.claude/skills/niblet
-```
-
-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
 
@@ -110,11 +127,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 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.
+`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.2.0",
+  "version": "0.3.0",
   "description": "Niblet MCP server and design skill: real UI screen references for coding agents",
   "keywords": [
     "mcp",

package/src/server.mjs

@@ -157,7 +157,7 @@ export function createServer({
 
   const server = new McpServer(
     { 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.` },
+    { 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} After picking a web reference, call get_design_reference with its screenId for the recorded colors, typography, and components. The 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() {
@@ -296,7 +296,11 @@ export function createServer({
     // The API treats `limit` as advisory, so bound the fan-out here: one image fetch per ref.
     const refs = all.slice(0, input.limit);
 
-    const content = [{ type: 'text', text: [REFERENCE_PREAMBLE, '', ...refs.map(refText)].join('\n') }];
+    // Only web screens belong to a design pack, so only they get the follow-up pointer.
+    const pointer = refs.some((ref) => ref.platform === 'web')
+      ? ['', 'A full style reference is recorded for the web screens above. Call get_design_reference with the screenId to read its colors, typography, and components.']
+      : [];
+    const content = [{ type: 'text', text: [REFERENCE_PREAMBLE, '', ...refs.map(refText), ...pointer].join('\n') }];
     for (const [index, ref] of refs.entries()) {
       const image = await fetchImage(ref.thumbUrl, extra.signal);
       // Keep one block per reference so position still identifies which screen an image belongs to.
@@ -349,6 +353,37 @@ export function createServer({
 
   const localAnnotations = { ...annotations, openWorldHint: false };
 
+  server.registerTool('get_design_reference', {
+    title: 'Get design reference',
+    description: 'Read the recorded style reference for a web screen returned by find_ui_references, or for a design pack by slug: colors with their roles, typography, and component inventory, as markdown. Only web screens have one.',
+    inputSchema: z.object({
+      screenId: screenId.optional().describe('A screen ID from find_ui_references.'),
+      packSlug: z.string().min(1).max(160).optional().describe('A design pack slug, when the pack is already known.'),
+      clientSkillVersion: clientSkillVersion.optional(),
+    }).strict().refine((value) => value.screenId !== undefined || value.packSlug !== undefined, 'Pass screenId or packSlug.'),
+    annotations,
+  }, async (input, extra) => {
+    const credential = credentialError();
+    if (credential) return errorResult(credential);
+
+    const result = await requestJson(['design-reference'], { screenId: input.screenId, slug: input.packSlug }, extra.signal);
+    if (!result.ok) {
+      if (result.status === 404) {
+        return textResult(
+          input.screenId
+            ? 'No style reference is recorded for that screen. Only web screens have one; continue with the local design system.'
+            : 'No design pack with that slug. Continue with the local design system.',
+        );
+      }
+      return errorResult(result.message);
+    }
+    const markdown = result.data?.markdown;
+    if (typeof markdown !== 'string' || markdown.trim() === '') return errorResult('Niblet API returned an invalid response.');
+    const slug = field(result.data.slug ?? '', 160);
+    const source = slug ? `\n\nSource: https://niblet.com/packs/${slug}` : '';
+    return { content: [{ type: 'text', text: `${REFERENCE_PREAMBLE}${source}` }, { type: 'text', text: field(markdown, 40_000) }] };
+  });
+
   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.',