Niblet MCP

Name: niblet-skill-mcp
Author: PyModel

Real screen references and a design skill, for coding agents that build UI.

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 catalogue when a specific visual question is still open.

The skill works alone. The server is optional and needs a token.

Install the skill

npx skills add PyModel/niblet-skill-mcp --skill niblet -y

Or copy it yourself, keeping references/, agents/, LICENSE, and NOTICE alongside it:

cp -r skill/niblet ~/.claude/skills/niblet

Then ask for it by name:

Use Niblet to design the checkout empty and error states.

The workflow 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.

Connect the server

Pick one. Hosted, if your host speaks HTTP MCP:

claude mcp add --transport http niblet https://api.niblet.com/mcp \
  --header "Authorization: Bearer $NIBLET_TOKEN"

Local over stdio, via the Claude Code CLI:

claude mcp add niblet --env NIBLET_TOKEN=$NIBLET_TOKEN -- npx -y @pymodel/niblet

Or the equivalent in any host's MCP config file:

{
  "mcpServers": {
    "niblet": {
      "command": "npx",
      "args": ["-y", "@pymodel/niblet"],
      "env": { "NIBLET_TOKEN": "<your Niblet API token>" }
    }
  }
}

Node.js 24.15+; npx fetches the package on first launch. Get a token from niblet.com/docs and keep it in 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:

Token:        present (44 characters, not shown).
Documents:    5/5 readable (niblet://skill, …).
API check:    OK

Tools

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

The two catalogue tools match the hosted service exactly. niblet_help and niblet_status are local-only.

Resources

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.

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

Configuration

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

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 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 has the working agreement for pointing a coding agent at this repository.

License

The skill carries the same licence; keep skill/niblet/NOTICE with it wherever it is installed.