@pymodel/niblet 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +57 -42
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -5,8 +5,6 @@
5
5
  </picture>
6
6
  </p>
7
7
 
8
- <h1 align="center">Niblet MCP</h1>
9
-
10
8
  <p align="center">Real screen references and a design skill, for coding agents that build UI.</p>
11
9
 
12
10
  <p align="center">
@@ -27,34 +25,44 @@
27
25
  By <a href="https://github.com/elkaix">elkaix</a> for <a href="https://github.com/PyModel">PyModel</a>
28
26
  </p>
29
27
 
30
- 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.
28
+ 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.
31
29
 
32
- The skill works on its own. The MCP server is optional, and needs a token.
30
+ The skill works alone. The server is optional and needs a token.
33
31
 
34
- ## What you get
32
+ ## Install the skill
35
33
 
36
- Two tools, matching the hosted service exactly:
34
+ ```sh
35
+ npx skills add PyModel/niblet-skill-mcp --skill niblet -y
36
+ ```
37
37
 
38
- | Tool | Use it for |
39
- | --- | --- |
40
- | `find_ui_references` | One concrete unresolved question about a layout, state, or interaction. Returns one to three real screens as inline images. |
41
- | `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. |
38
+ Or copy it yourself, keeping `references/`, `agents/`, `LICENSE`, and `NOTICE` alongside it:
39
+
40
+ ```sh
41
+ cp -r skill/niblet ~/.claude/skills/niblet
42
+ ```
42
43
 
43
- | `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. |
44
- | `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. |
44
+ Then ask for it by name:
45
+
46
+ > Use Niblet to design the checkout empty and error states.
45
47
 
46
- 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.
48
+ 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.
47
49
 
48
- ## Connect
50
+ ## Connect the server
49
51
 
50
- 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):
52
+ Pick one. Hosted, if your host speaks HTTP MCP:
51
53
 
52
54
  ```sh
53
55
  claude mcp add --transport http niblet https://api.niblet.com/mcp \
54
56
  --header "Authorization: Bearer $NIBLET_TOKEN"
55
57
  ```
56
58
 
57
- 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.
59
+ Local over stdio, via the Claude Code CLI:
60
+
61
+ ```sh
62
+ claude mcp add niblet --env NIBLET_TOKEN=$NIBLET_TOKEN -- npx -y @pymodel/niblet
63
+ ```
64
+
65
+ Or the equivalent in any host's MCP config file:
58
66
 
59
67
  ```json
60
68
  {
@@ -68,40 +76,46 @@ To run it locally over stdio instead, add this to your host's MCP config. Node.j
68
76
  }
69
77
  ```
70
78
 
71
- Or with the Claude Code CLI:
79
+ 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.
72
80
 
73
- ```sh
74
- claude mcp add niblet --env NIBLET_TOKEN=$NIBLET_TOKEN -- npx -y @pymodel/niblet
75
- ```
76
-
77
- Saving the config does not register the server — check the tool list your host actually reports.
81
+ 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:
78
82
 
79
- 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.
80
-
81
- `NIBLET_API_ORIGIN` and `NIBLET_MEDIA_ORIGIN` retarget the server at a local deployment. Leave them unset for production.
83
+ ```
84
+ Token: present (44 characters, not shown).
85
+ Documents: 5/5 readable (niblet://skill, …).
86
+ API check: OK
87
+ ```
82
88
 
83
- ## The skill
89
+ ## Tools
84
90
 
85
- <img src="https://raw.githubusercontent.com/PyModel/niblet-skill-mcp/main/assets/niblet-mascot-working.svg" alt="" width="72" height="72" align="right">
91
+ | Tool | Use it for | Token |
92
+ | --- | --- | --- |
93
+ | `find_ui_references` | One concrete unresolved question about a layout, state, or interaction. Returns one to three real screens as inline images. | yes |
94
+ | `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 |
95
+ | `niblet_help` | "What can Niblet do?", or choosing between commands. Lists the four surface modes and every command; pass `command` for one entry. | no |
96
+ | `niblet_status` | Diagnosing the connection before concluding the catalogue is empty. Never prints the token. | no |
86
97
 
87
- Install it straight from the repository:
98
+ The two catalogue tools match the hosted service exactly. `niblet_help` and `niblet_status` are local-only.
88
99
 
89
- ```sh
90
- npx skills add PyModel/niblet-skill-mcp --skill niblet -y
91
- ```
100
+ ## Resources
92
101
 
93
- Or copy [skill/niblet](skill/niblet) into your host's skill directory yourself, keeping `references/`, `agents/`, `LICENSE`, and `NOTICE` alongside it:
102
+ 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.
94
103
 
95
- ```sh
96
- cp -r skill/niblet ~/.claude/skills/niblet
97
- ```
98
-
99
- Then ask for it by name:
104
+ | URI | Contents |
105
+ | --- | --- |
106
+ | `niblet://skill` | The design workflow: modes, contract, state coverage, finish gate |
107
+ | `niblet://skill/commands` | Every command, its scope, and what completion means |
108
+ | `niblet://skill/connection` | Installing, invoking, and diagnosing the tools |
109
+ | `niblet://skill/evidence` | When to pull an external reference, and how to use one |
110
+ | `niblet://skill/native` | Platform constraints and the native finish gate |
100
111
 
101
- > Use Niblet to design the checkout empty and error states.
102
- > Run a niblet-skill review of the settings screen.
112
+ ## Configuration
103
113
 
104
- 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.
114
+ | Variable | Purpose |
115
+ | --- | --- |
116
+ | `NIBLET_TOKEN` | Required by the two catalogue tools. |
117
+ | `NIBLET_API_ORIGIN` | Retarget at a local deployment. Unset for production. |
118
+ | `NIBLET_MEDIA_ORIGIN` | Same, for images. Unset for production. |
105
119
 
106
120
  ## Contributing
107
121
 
@@ -110,11 +124,12 @@ git clone https://github.com/PyModel/niblet-skill-mcp
110
124
  cd niblet-skill-mcp
111
125
  npm ci --ignore-scripts
112
126
  cp .env.example .env # then put your token in NIBLET_TOKEN
127
+ npm test
113
128
  ```
114
129
 
115
- `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.
130
+ `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.
116
131
 
117
- [AGENTS.md](AGENTS.md) has the details if you are pointing a coding agent at this repository.
132
+ [AGENTS.md](AGENTS.md) has the working agreement for pointing a coding agent at this repository.
118
133
 
119
134
  ## License
120
135
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pymodel/niblet",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "Niblet MCP server and design skill: real UI screen references for coding agents",
5
5
  "keywords": [
6
6
  "mcp",