ns-ui / docs

ns-ui developer docs.

Every endpoint below is public, needs no key and no account, and is relative to https://design.helpmarq.com. If you want the walkthrough version (per-client MCP config, CLI examples), that is on /connect.

Registry API

/v1/registry.json: Versioned base URL. Every path below also answers under /v1: same handler, so the two can never disagree.The unversioned paths stay supported; /v1 is the one to integrate against.
/registry.json: The shadcn registry index: all 542 items with names, titles, descriptions and tags.Also served at /r/registry.json; both are the same file.
/r/<name>.json: One component's registry item: dependencies, CSS variables, and the real source in files[].content.This is what `npx shadcn add` reads.
/openapi.json: OpenAPI 3.1 description of every endpoint on this page.

Agent surface

/.well-known/mcp: MCP server. POST JSON-RPC (Streamable HTTP) for initialize, tools/list and tools/call; GET returns the manifest.Also answers at /mcp and /.well-known/mcp.json.
/llms.txt: Agent quickstart: install command, token contract, and one block per component.
/llms-full.txt: The long form: a full paragraph of behavioral detail per component.
Accept: text/markdown: Send that header to any page on this site and it answers with a markdown version of itself.acceptmarkdown.com-compliant, including the Vary header and q-values.
/sitemap.xml: Every indexed page, including one per component.

Packages

npx -y @nikolas.sapa/ns-ui-mcp: The same MCP server over stdio, for clients that do not speak HTTP transport.
npx @nikolas.sapa/ns-ui add <name>: CLI: search, inspect and install components from a terminal.

Errors

Every error is an RFC 9457 problem document, served as application/problem+json. Never an HTML page: a client that asked for JSON gets JSON, including on a 404.

{
  "type": "https://design.helpmarq.com/docs#errors",
  "title": "No such component",
  "status": 404,
  "detail": "No component named "acordion-latch" exists in this registry.",
  "code": "component_not_found",
  "resolution": "Check the index at https://design.helpmarq.com/registry.json…",
  "instance": "/r/acordion-latch.json",
  "requestedName": "acordion-latch"
}

code is the field to branch on. It is stable, unlike the prose in title and detail. Current codes: not_found, component_not_found, rate_limited, stream_not_supported.

Rate limits

Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy (RFC 9331 field names), so a client can pace itself instead of discovering the limit by hitting it. Going over returns 429 with Retry-After and the same problem-document shape.

The window is 120 requests per minute per client, counted per serving instance, deliberately generous. It exists so agents can self-throttle, not to meter usage; the registry files themselves are static and CDN-cached.

Versioning and deprecation

Integrate against /v1. Within it, response shapes only ever gain fields; anything that would break an existing client becomes /v2 instead. The unversioned paths are aliases onto the same handlers and stay supported.

If an endpoint is ever retired, its responses carry Deprecation and Sunset headers for at least 180 days before removal, and the change is announced in the changelog. Nothing is deprecated today.

Authentication

There is none. Every endpoint above is public, anonymous and read-only; nothing here accepts a write. Account features (saving components, collections) exist on the site but have no public API. See /privacy for what they store.

Licensing

MIT, components included. Install them, edit them, ship them: the source lands in your repository and there is no runtime package to depend on. More about the project on /about.