bestax / bestax-mcp
CLAUDE.md14 starsChanged 8 days agoMITView on GitHub
The first-party MCP server for @allxsmith/bestax-bulma. Published unscoped as bestax-mcp, alongside create-bestax and bestax-migrate. It answers questions about the library — components, props, examples, CSS variables — and ships the library's opinions as MCP prompts, one per Agent Skill. Run it with npx bestax-mcp. pnpm gen:mcp (root) runs scripts/gen-mcp-index.mjs, which reuses the same extraction the API docs use — scripts/lib/props-extract.mjs in markdown: false mode, scss-vars.mjs, api-sources.mjs — plus the hand-written ## Usage / ## Accessibility sections of the API pages.
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- bulma-ui/AGENTS.mdAGENTS.md
- bestax-migrate/CLAUDE.mdCLAUDE.md
- bulma-ui/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- create-bestax/CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- eslint-plugin/CLAUDE.mdCLAUDE.md
- .github/CLAUDE.mdCLAUDE.md
- skills/CLAUDE.mdCLAUDE.md
- templates/CLAUDE.mdCLAUDE.md
- bulma-ui/llms.txtllms.txt
- bestax-custom-componentSkill
- bestax-formSkill
- bestax-iconsSkill
- bestax-layout-scaffoldSkill
- bestax-migrateSkill
- bestax-optimizeSkill
- bestax-themingSkill
The file
We split this CLAUDE.md into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 50
Keep both properties if you touch either file, and see the shared file's trailing "Concurrency" note for why the freshness check is …
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
bestax-mcp
The first-party MCP server for @allxsmith/bestax-bulma. Published unscoped as
bestax-mcp, alongside create-bestax and bestax-migrate.
It answers questions about the library — components, props, examples, CSS
variables — and ships the library's opinions as MCP prompts, one per Agent
Skill. Run it with npx bestax-mcp.
Everything in data/ is generated
pnpm gen:mcp (root) runs scripts/gen-mcp-index.mjs, which reuses the same
extraction the API docs use — scripts/lib/props-extract.mjs in
markdown: false mode, scss-vars.mjs, api-sources.mjs — plus the
hand-written ## Usage / ## Accessibility sections of the API pages.
- Never hand-edit
data/. CI fails on staleness (pnpm gen:mcp:check). data/catalog.jsonanddata/components/*.jsonare committed.data/bulma-classes.jsonis committed too, and comes from somewhere else: bestax-migrate'ssrc/sources/bulma-classes/class-map.ts, which the generator imports directly (node strips its types).lookup_bulma_classesanswers from it by following that source's planner class by class, andsrc/__tests__/bulma-classes-agree.test.tsimports the planner itself to hold the two together, so a change to either side of that table shows up here. Beside the table it carries every class in Bulma v1's compiled stylesheet, read fromnode_modules/bulmawith the walk bestax-migrate's vocabulary test uses (e2e/support/bulma-stylesheet.ts), so a lookup can tell a v1 class with no prop from a 0.9 one v1 removed (REMOVED_IN_V1in the class map) and from one v1 has no rule for. Of those, it names what styles one where it can: a root class of bestax's own (ownClasses, each record's root class Bulma 1 lacks, socarouselisCarousel's) and another stylesheet's (ELSEWHEREin the class map: Font Awesome, Material Design Icons, bulma-social, bulma-carousel).BY_HANDthere names the table part that renders a plain<th>or<td>, which the codemod leaves, and the generator lists the props its record has beside the helper props (#1236).- The
useBulmaClassesrecord carries the helper props as rows (helperProps), read fromBulmaClassesPropsand the interfaces it extends, less the breakpoint variants, sosearch_bestaxfinds one by what it does. A part whose helper props go on another element than its attributes carrieshelperPropsNote, from@helperPropson its props type, whichget_propsprints beside the catch-all row (#1273). data/skills/is gitignored and synced from/skillsbyscripts/sync-skills.mjs, which runs onbuild,test,test:coverage,test:watchandprepack. Only the manifest (data/skills.json) is committed — enough for the staleness gate to catch a new or renamed skill, without putting a second copy of ~390 KB of markdown in every skill diff. Several Turbo tasks can invoke that script at the same time, so it takes a lock and no-ops when the tree already matches the source. The copy itself isscripts/lib/sync-skills.mjsat the repo root, shared with create-bestax. Keep both properties if you touch either file, and see the shared file's trailing "Concurrency" note for why the freshness check is required rather than merely an optimisation.gen:mcp:checkrunsgit add --intent-to-addbefore diffing. The output is a directory, andgit diff --exit-codecannot see an untracked file — a newly added component would otherwise pass the gate.
A library change that moves props means pnpm gen in the same PR, exactly like
the API pages and the skill catalog.
Conventions
- Responses are markdown, not JSON. The consumer is a language model: a prop table costs fewer tokens than the same data as nested objects, and it does not tempt the model into echoing JSON structure into the code it writes.
- Progressive disclosure.
search_bestaxandlist_componentsare cheap and every result names the tool to call next. Full prop tables, usage examples and skill references are separate calls. A tool that returns everything up front spends the context the client needs for the actual task. - No hardcoded roster. Prompts, resources and skill lookups are all derived
from
data/skills.json, which the generator builds by reading theskills/directory. The rule repo-wide is derive, don't list (#540); the prose copies that cannot be derived are held to the directory by theskills-rosterconformance check (pnpm check:conformance --only=skills-roster). Do not add a hand-maintained copy here for that check to chase. - Nothing on stdout but JSON-RPC. stdout is the transport. Diagnostics go
to stderr — a stray
console.logsurfaces to the user as an unexplained disconnect. - Version mismatch is reported, not hidden. The index is pinned to the
bestax-bulmarelease it was generated from; the server resolves the version actually installed in the user's project and appends a warning on minor or major drift. Patch drift stays silent on purpose — a note on every response is a note a model learns to skip. Finding no install is said once, on the first answer, since it is also what a server started outside the project looks like;BESTAX_MCP_PROJECT_DIRpoints the probe at the project for a client that does that.BESTAX_MCP_NO_VERSION_CHECK=1disables the check. A server run from this repository's source, at its root, finds the workspace's library beside itself (checkoutVersioninsrc/version.ts); an installed one, under anode_modules, never reads its own copy for the project's. - Unhelpful answers are bugs. A missing component suggests near misses by
edit distance; a bad dot-path lists the real ones; a component with no CSS
variables says so rather than returning blank. An empty response reads as a
failed lookup and costs a retry. A component that renders another component's
element (
RENDERS_ELEMENT_OFinscripts/lib/api-sources.mjs) names that component'sget_css_variablescall too, since "none" alone reads as "can't be themed". - Every name an answer hands out is one the tools answer for. An export
with no page of its own is a part of the record that documents it: the bare
control a convenience component renders (
InputBaseinInput), what a page imports beside its component (CarouselIteminCarousel), and a sub the barrel exports by name too, from a module of its own (Thead, asTable.Thead) or beside its parent (NavbarItem, asNavbar.Item). The catalog'sdocumentedWithresolves each name to its part. A name an import line gives that is no part at all, a hook (useDataTable), a function (toast) or a constant (validColors), has no path there: the tools answer with its record and name the section of the page that documents it (#1465). A dot-path through a part that is a component of its own goes on in that component's record, by the part'scomponent, soStats.Stat.LabelisStat.Label(#1480). A sweep insrc/__tests__/server.test.tsfails on a name from the catalog, a record,lookup_bulma_classesor the library'sindex.tsthatget_propsrefuses (#1150, #1174). It reads that barrel frombulma-ui/src, soturbo.jsonlists the library's source among this package's test inputs.
Dependencies
@modelcontextprotocol/sdk and zod are the ones that are imported (the
SDK's schema types are zod, and pnpm's isolated linker means anything imported
must be declared). The SDK pulls a large tree of transitive packages, most of them
for HTTP transports this server does not use. That footprint was weighed against
what the server needs before adopting it, and pnpm audit --audit-level=high
comes back clean on the result. Re-check both if that ever changes.
@allxsmith/bestax-bulma is declared, not imported (#644): the server is built
for the library and its manifest says so, the way bulma-ui declares bulma.
It is spelled workspace:^, which pnpm publish rewrites to the release
current at pack time (bulma-ui releases first in the same job), and the sibling
rule in check:conformance allows it only because SIBLING_RUNTIME_DEPS
declares this exact pair. Two things follow. npx bestax-mcp installs the
library, bulma, and — npm's automatic peer install — react/react-dom
alongside the server. And the version probe in src/version.ts walks up from
cwd (or BESTAX_MCP_PROJECT_DIR), so under npx the server's own copy in
the npx cache is never on that path; installed as a project devDependency
instead, npm may hoist this
dependency's copy to the project's top-level node_modules, and when the
project has no copy of its own the probe reports that one.
Tests
pnpm --filter bestax-mcp test. Thresholds 95% / 78% branches, matching
create-bestax.
Tests drive the real protocol through the SDK's InMemoryTransport rather than
calling handlers directly: the contract that matters is what a client sees, and
that includes schema validation and the tool/resource/prompt listings. A handler
test would pass while the server advertised nothing.
They run against the committed index, not fixtures. The index is the product; a test that stubs it proves nothing about what ships.
Releases
Released by semantic-release, keyed off the bestax-mcp commit scope (release.config.js, tag
bestax-mcp@x.y.z), and patched with every bulma-ui release so the index ships with the
library (VERSIONING.md, "bestax-mcp releases with bestax-bulma"). It publishes with
pnpm publish, like every package here (#532) — the command, its flags, and the
ways that publish fails quietly are documented in VERSIONING.md and
scripts/lib/pnpm-publish.mjs.
The release job regenerates data/ after bulma-ui's release and before this package's, and
the publish packs that working tree, so the index a release ships is stamped with the
bestax-bulma version released in the same run (#932). The release commit does not take the
change; the job's last step commits it to main. ci.yml has the details, at "Regenerate the MCP
index".
MCP directories and lists describe what the server offers and give npx -y bestax-mcp@1 as
its command. A change to either, to how it starts, or a new major means updating the listings
that docs/docs/guides/distribution.md names under "What goes stale".
The bestax plugin in allxsmith/bestax-skills builds its launch config from server.json,
read and checked by scripts/mcp-registry-publish.mjs: the one npm package over stdio becomes
npx -y <identifier>@<version>, with the version from package.json, each time
skills-publish.yml regenerates it, which it does after every release. Its README lists the
package's environmentVariables and the skills in data/skills.json, so both stay in step with
this package. The generator fails if server.json stops describing an npm package over stdio, or
adds launch arguments or a required variable the plugin cannot carry. The README's prose
(plugin/README.md) says what the server does over the network and what npx downloads, so a
change to either updates it in the same PR.
Its prepack runs the guard and then scripts/sync-skills.mjs, which fills
data/skills/ at pack time. That directory is gitignored while the manifest
data/skills.json is committed, so packing locally does not dirty the tree —
which also keeps it clear of the MCP index restamp in ci.yml, whose diff check
and commit are scoped to bestax-mcp/data.
files carries a "!data/.sync-skills" negation, and it is not cosmetic.
files ships all of data/, and sync-skills.mjs keeps its fingerprint and
lock state in data/.sync-skills/, so without the negation that build state
ships as product.
This is not a pnpm publish behaviour, and an earlier version of this note
said it was. npm and pnpm both include dot-directories under a files
entry; a synthetic package with files: ["data"] and data/.state/x packs
identically under either. The published 1.0.0 tarball has no .sync-skills
only because the state directory did not exist yet — it arrived with #520 on
2026-08-14, two days after 1.0.0 shipped. So this was a latent bug that the
next release would have hit whoever packed it, surfaced by diffing a
pnpm -C bestax-mcp pack against the published tarball while moving
publishers (#532). That diff is the check worth repeating whenever files or
the sync script changes, because nothing asserts tarball contents.
MCP Registry
Each release is also published to the official MCP Registry as
io.github.allxsmith/bestax-mcp, by .github/workflows/mcp-registry.yml (on
release: published, or by dispatch with a tag). The listing is server.json
in this directory. The workflow reads it from main, writes the release
version in, and publishes it with mcp-publisher over GitHub OIDC; the logic
is scripts/mcp-registry-publish.mjs.
mcpNameinpackage.jsonis load-bearing. The registry proves ownership by reading it from the published version on npm, and requires it to equalserver.json'sname. Drop or rename it and every later release becomes unlistable.- Both
versionfields inserver.jsonstay0.0.0-set-from-release-tag. semantic-release bumpspackage.jsonand nothing else, so a real version here would go stale; the workflow writes the release version into the runner's copy only.scripts/mcp-registry-publish.test.mjsfails CI on any other value, and holds the rest of the file topackage.jsonand the schema's description limit. server.jsondoes not ship.filesdoes not name it, and the registry never looks in the tarball.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

