@dapplelight/signet-mcp
v0.1.8
Published
MCP server that gives AI agents all of Signet: docs, exports, components, themes, scaffolding, convention checks, recipes and migrations.
Maintainers
Readme
@dapplelight/signet-mcp
An MCP server that gives an AI agent (Claude Code, Cursor, Claude Desktop, any MCP client) everything in Signet: the docs, every export with its signature, the components, the themes and their contract, scaffolding, convention checks, recipes and migration notes. With it, an agent can build, check and fix a Signet app without reading the repo.
Everything it answers comes from an index built from this repo when the package is built, and that index ships inside the package. It makes no network calls and cannot fall behind the version it was built with.
Install
Published on npm as @dapplelight/signet-mcp. The server runs on Node 20+ or
Bun; bunx needs Bun installed, npx needs only Node. Pick the runner you
have; each client below shows both.
Claude Code:
claude mcp add signet -- bunx @dapplelight/signet-mcp
# Node only:
claude mcp add signet -- npx -y @dapplelight/signet-mcpCursor, in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):
{
"mcpServers": {
"signet": { "command": "bunx", "args": ["@dapplelight/signet-mcp"] }
}
}Node only, the same file with npx:
{
"mcpServers": {
"signet": { "command": "npx", "args": ["-y", "@dapplelight/signet-mcp"] }
}
}Claude Desktop, in claude_desktop_config.json (Settings, Developer, Edit
Config). Desktop does not always see a shell's PATH, so npx is the safer
choice there (use bunx with "args": ["@dapplelight/signet-mcp"] if Bun is
on the PATH Desktop sees):
{
"mcpServers": {
"signet": { "command": "npx", "args": ["-y", "@dapplelight/signet-mcp"] }
}
}Its peers, @modelcontextprotocol/server and zod, are installed alongside it
by npm and bun.
Tools
All read-only.
| Tool | What it returns |
|---|---|
| search_docs(query, limit?) | Doc sections, exports, components and recipes that match, each with a ref to follow |
| read_doc(name, section?) | A doc, whole or one section; the same text as the signet://docs/<name> resource |
| list_exports(package?) | Every import path, its summary and its symbol names |
| get_export(path, symbol) | The symbol's declaration signature, its JSDoc, its source file, and every other path that exports it |
| list_components() | Each @dapplelight/signet-ui component, its import path and exports |
| get_component(name) | Props (parameter list and …Props types), cva variants and defaults, a usage example, the contract variables its classes read |
| plan_page({ description, target? }) | Blocks, components, server modules, recipe, data and files to create for a page described in words |
| list_themes() / get_theme(name, include_css?) | Shipped themes, how to import one, and the CSS to copy |
| list_tokens(kind?) | The theme contract: 78 required and 16 optional variables, grouped |
| check_theme(css) | Findings against CONTRACT.md: missing variables, optional slots not set in both modes, a repainted stock palette, @source in a theme, and WCAG contrast in light and dark |
| scaffold_app({ name, template, theme }) | The exact create-signet-app command, the files it will create, and the next steps |
| scaffold_files({ name, template, theme }) | Every file create-signet-app would write, with contents, for an agent without a shell |
| check_app({ files } or { path }) | Findings with fixes: env read at module scope in a server module, rate limiting and its trust, signet-doctor's Durable Object checks, CSRF, the error handler, the env schema against wrangler vars, Tailwind @source for the components, domain vocabulary in base packages |
| recipe(task) | Install line, the doc sections that do the job (with their code), and how to verify. Tasks: add-auth, add-rate-limit, add-csrf, add-error-envelope, add-env, add-api-client, add-web-push, add-ai-extraction, add-analytics, add-portability-adapters, add-db, add-mcp-tools, mcp-by-default, add-oauth, add-logging, add-theme |
| migration(from, to?, package?) | CHANGELOG entries in the range with the breaking bullets pulled out, the README's "Migrating from" notes, and current versions |
check_app({ path }) reads a directory from disk, so it is offered only by the
stdio bin, which runs on your machine as you. A hosted HTTP server offers
files alone.
Resources and prompts
Every doc is a resource at signet://docs/<name>: signet (the root README),
api, conventions, migration, changelog, contributing, publishing,
repo-guide, contract, analytics, and one per package README (tokens,
ui, lib, server, ai, config, create-signet-app, mcp, ...).
Prompts: build-signet-app (idea, template), review-against-signet
(target), add-signet-feature (feature, app).
Host it over HTTP
On any fetch host (Workers, Bun, Deno):
import { signetMcpFetch } from "@dapplelight/signet-mcp"
export default { fetch: signetMcpFetch() }Or as a route on a Hono app, with Signet's own MCP kit:
import { signetMcpOptions } from "@dapplelight/signet-mcp"
import { mountMcp } from "@dapplelight/signet-server/mcp/hono"
mountMcp(app, "/mcp", signetMcpOptions())Both serve 2026-07-28 and 2025-era clients. signetMcpOptions({ tools,
resources, prompts }) adds your own beside Signet's.
Your database, as tools
Pass a signet-db instance and the tables an agent may reach (each needs a
userId column) and the server adds <table>_list, <table>_get and
<table>_search after Signet's own tools:
import { agentTools } from "@dapplelight/signet-db/agent"
mountMcp(app, "/mcp", {
...signetMcpOptions({ db: { db, agentTools, tables: [orders, notes] } }),
middleware: [requireToken({ verifier, resourceMetadataUrl })],
})The tools are built per request for the caller, so each user sees only their
own rows. The user is the verified token's sub (userId: (caller) => … picks
another); with no identity there are no db tools at all. Writes are off:
allowWrites: true adds <table>_insert and <table>_update, which take
dryRun: true. maxRows caps rows per call (default 100). Scopes are not
checked unless you set scopes: { read: ["db:read"], write: ["db:write"] }:
read gates the read-only tools, write the insert and update tools, so
without it any caller with a verified sub can run every db tool. Once you set
scopes, name each group explicitly: read always, and write when
allowWrites is true. signetMcpOptions throws if one is missing or empty,
so a half-configured gate cannot leave the writes open. A table without a
userId column throws when signetMcpOptions is called. agentTools is
passed in because signet-db is not a dependency of this package. Because the
list depends on the caller, use mountMcp or resolveMcpServer, not
signetMcpFetch.
How it is built
The server is built with Signet's own toolkit (defineTool,
defineResource, definePrompt, createMcpServer from
@dapplelight/signet-server/mcp), served over stdio by the SDK's
serveStdio.
bun run gen runs scripts/build-index.ts, which writes src/generated/:
index.ts: the docs, every export path with symbol signatures and JSDoc (read from source, following barrels), components with their cva variants and the contract variables they use, themes, contract tokens, recipes cut from doc sections, andcreate-signet-app's templates and package.json.doctor-check.ts,contrast.ts: verbatim copies ofpackages/server/src/doctor/check.tsandpackages/tokens/test/contrast.ts, socheck_appandcheck_themerun the repo's own logic.
src/generated/ is gitignored. build, test and typecheck regenerate it
first, so it always matches the repo and never shows up in a diff; the
published tarball carries it compiled into dist/. A recipe whose doc heading
was renamed fails the generator.
Test
bun run build && bun run testThe end-to-end test spawns the built bin under Node and talks to it over stdio
with signet-server's MCP client (every tool, resources, prompts), calls the
HTTP handler, then serves signet-db's agent tools for two users and checks
neither sees the other's rows and that writes stay off by default. The unit tests check check_theme and check_app against the
shipped themes and the scaffolder's own output, mutated to break each rule,
and check that scaffold_files matches running create-signet-app byte for
byte.
License
MIT
