@nanisoft/prism-mcp-server 0.3.0 → 0.4.1

package/README.md

@@ -0,0 +1,66 @@
+# @nanisoft/prism-mcp-server
+
+Prism's read-only MCP tool surface. Eight retrieval tools answer over the
+bundled `PrismDocsStore` corpus from the same Cloudflare Worker that serves the
+site, at `https://prism.nanisoft.com/mcp`.
+
+The package is **transport-free**: `createPrismMcpServer(store, options)` returns
+an `McpServer`, and the Worker connects it to `createMcpHandler` from the Agents
+SDK's MCP server entry. There is one implementation and no stdio binary at
+launch; a stdio-only client bridges with `npx mcp-remote
+https://prism.nanisoft.com/mcp`.
+
+## Commands
+
+```sh
+pnpm --filter @nanisoft/prism-mcp-server build   # stamp the corpus, then tsc into dist/
+pnpm --filter @nanisoft/prism-mcp-server test    # the Vitest floor (in-memory round-trips)
+```
+
+`pretest` compiles the package first. The suite reaches the corpus through
+`@nanisoft/prism-llms`'s emitted `data.json`.
+
+## The eight tools
+
+Every tool is self-contained, idempotent, stateless and returns Markdown. A
+lookup miss is an `isError` result with did-you-mean suggestions and a browse
+pointer, never a throw. Every description carries the import rule and the
+surface rule.
+
+| Tool | Arguments | Purpose |
+| --- | --- | --- |
+| `list_items` | `{ kind?, category? }` | The kind-grouped catalogue index; `category` is Component-only. |
+| `get_item_doc` | `{ name, kind? }` | The assembled per-item Markdown plus its footer. |
+| `get_item_props` | `{ name, kind? }` | The `## Props` section, or `## Composition` for a Block or Page. |
+| `get_item_source` | `{ name, kind? }` | The public import line plus the verbatim demo. |
+| `get_theme_doc` | `{ pack?, mode?, group? }` | A pack's resolved values, or one bound scale. |
+| `list_pages` | `{}` | The Overview, Foundation, Content and Changelogs page index. |
+| `get_page` | `{ url }` | One non-item page as Markdown; a catalogue URL points at `get_item_doc`. |
+| `search_docs` | `{ query, kind?, limit? }` | Substring search over names, descriptions and page bodies. |
+
+`kind` is the closed union `component | block | page`; `get_theme_doc`'s `group`
+is `semantic | motion | typography | spacing | shadow | breakpoint | container`.
+
+## The store
+
+`createPrismMcpServer` runs `parsePrismDocsStore` from `@nanisoft/prism-llms` at
+its door, so a raw `data.json` is validated once and every transport inherits the
+same rejection. The Worker bundles `@nanisoft/prism-llms/data.json` as an ESM
+module; there is no `fs`, `fetch`, KV, cache or runtime lookup at isolate scope.
+
+## The build stamp
+
+`scripts/stamp-built.mjs` writes the gitignored `src/generated/built.ts` before
+the build. The stamp is derived from the corpus source commit date plus the
+corpus version, so the same commit rebuilds to the same value. When git or the
+corpus is unavailable it is `undefined`, and `list_items` omits the
+`(built ...)` clause rather than fabricating a date. The stamp lives in this lane,
+never in the corpus `dist`, so corpus build-twice determinism is untouched.
+
+## Auth
+
+Public read-only in version one: the corpus is public and the tools are pure
+reads over an immutable blob. The Cloudflare Access escalation is pre-written in
+`apps/site/worker/access.ts` and inert until enabled. It flips when a tool gains
+anything non-public: org-internal examples, write-back, telemetry or a per-user
+quota.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,48 @@
+# Third-party notices
+
+The Prism packages (`@nanisoft/prism-tokens`, `@nanisoft/prism-ui`,
+`@nanisoft/prism-llms`, `@nanisoft/prism-mcp-server`) are MIT-licensed. See
+[`LICENSE`](./LICENSE). This file covers the third-party works the packages and
+the site depend on or redistribute. It is attribution, not a grant: each work
+remains under its own license.
+
+## Runtime dependencies
+
+The direct runtime dependencies below are MIT-licensed unless noted. License
+texts ship with their packages and are available from the corresponding npm
+package or repository.
+
+| Package | Used by | License |
+| --- | --- | --- |
+| `@base-ui/react` | `@nanisoft/prism-ui` (internal accessibility behaviour) | MIT, copyright the MUI Team and contributors |
+| `@modelcontextprotocol/sdk` | `@nanisoft/prism-mcp-server` | MIT, copyright Anthropic, PBC and contributors |
+| `zod` | `@nanisoft/prism-mcp-server` | MIT, copyright Colin McDonnell |
+| `react`, `react-dom` | `@nanisoft/prism-ui` (peer), the site | MIT, copyright Meta Platforms, Inc. and affiliates |
+| `next` | the site | MIT, copyright Vercel, Inc. |
+| `fumadocs-core`, `fumadocs-mdx` | the site | MIT, copyright Fuma Nama |
+| `agents` | the site (MCP transport) | MIT, copyright Cloudflare, Inc. |
+| `class-variance-authority` | `@nanisoft/prism-ui` (internal variant recipes, not re-exported) | Apache-2.0 |
+| `clsx` | `@nanisoft/prism-ui` (internal class composition) | MIT, copyright Luke Edwards |
+| `tailwind-merge` | `@nanisoft/prism-ui` (internal class composition) | MIT |
+| `lucide-react` | `@nanisoft/prism-ui` and the site (icons) | ISC, copyright the Lucide contributors, with portions copyright Cole Bemis 2013 to 2023 as part of Feather (MIT) |
+| `tailwindcss` | `@nanisoft/prism-ui` and the site (internal build dependency) | MIT, copyright Tailwind Labs, Inc. |
+
+Tailwind 4 is not a consumer dependency. It runs only in Prism's build, and its
+compiled output is part of the component package's precompiled `styles.css`.
+
+## Fonts
+
+The documentation site self-hosts Inter under `apps/site/src/fonts/`, loaded
+through `next/font/local`. The shipped files are `InterVariable.woff2` and
+`InterVariable-Italic.woff2` from the official Inter release 4.1, and the site
+is the only consumer. Inter is licensed under the **SIL Open Font License,
+Version 1.1**; the license text is committed at
+`apps/site/src/fonts/LICENSE.txt`. Inter is copyright The Inter Project Authors
+(rsms.me/inter).
+
+## Build and development toolchain
+
+TypeScript, Vitest, Turbo, pnpm, changesets, oxlint, Style Dictionary, publint
+and Wrangler are development and build dependencies. They are not redistributed
+with Prism artifacts and carry their own package licenses. Style Dictionary is
+Apache-2.0; the rest ship their own license text with their packages.

package/dist/descriptions.d.ts

@@ -0,0 +1,22 @@
+export declare const DESCRIPTIONS: {
+    readonly list_items: string;
+    readonly get_item_doc: string;
+    readonly get_item_props: string;
+    readonly get_item_source: string;
+    readonly get_theme_doc: string;
+    readonly list_pages: string;
+    readonly get_page: string;
+    readonly search_docs: string;
+    readonly get_changelog: string;
+};
+export type ToolName = keyof typeof DESCRIPTIONS;
+/**
+ * The registration order.
+ *
+ * The first eight are pinned by ticket 13 section 9 and keep their names and
+ * their positions. `get_changelog` is appended rather than inserted, because an
+ * agent holding a tool list from before this ticket finds every tool it knew at
+ * the index it knew it at. A Section joining the Corpus is a parameter on the
+ * existing tools, not a rename of them.
+ */
+export declare const TOOL_ORDER: readonly ["list_items", "get_item_doc", "get_item_props", "get_item_source", "get_theme_doc", "list_pages", "get_page", "search_docs", "get_changelog"];

package/dist/descriptions.js

@@ -0,0 +1,33 @@
+/** The tool descriptions, each composed with the two standing rules. */
+import { describe } from './rules.js';
+export const DESCRIPTIONS = {
+    list_items: describe('List every Prism Component, Block and Page in the catalogue, optionally filtered by kind or by Component category. Use this once to learn the roster, then read an item with `get_item_doc` or `get_item_props`.'),
+    get_item_doc: describe('Read the assembled documentation for one Prism item: its description, import line, prose, demo pointer and generated API section. Accepts a name or slug and an optional kind to disambiguate.'),
+    get_item_props: describe('Read only the generated Props section, or the Composition section for a Block or Page, for the loop that re-queries an API without re-reading the prose. Accepts a name or slug and an optional kind to disambiguate.'),
+    get_item_source: describe('Read the verbatim demo source for one Prism item plus its public import line. Returns copyable source only; use `get_item_doc` for the prose and `get_item_props` for the API.'),
+    get_theme_doc: describe('Read the Prism token contract: a pack\u2019s resolved semantic values for a mode, or one bound scale (motion, typography, spacing, shadow, breakpoint, container). Read the contract here instead of inventing a duration, a curve or a spacing step.'),
+    list_pages: describe('List the non-item Prism documentation pages: the Overview, the Foundation, the Content and the Changelogs. Use `get_page` to read one.'),
+    get_page: describe('Read one non-item Prism documentation page as Markdown by its URL. Only serves the Overview, Foundation, Content and Changelogs lanes; a catalogue item URL is a miss with a pointer to `get_item_doc`.'),
+    search_docs: describe('Substring match over item names, descriptions and page bodies. Returns ranked references, each with its kind, the field that matched, and the follow-up call to make. It does not return page or item contents; use `get_item_doc` or `get_page` for the body.'),
+    get_changelog: describe('Read a published Prism package\u2019s changelog, optionally one version of it. Returns the package\u2019s own file, so the text is the text that shipped. Call this before upgrading, or when behaviour changed under a version you depend on: a breaking change in a published package is here rather than in a guess.'),
+};
+/**
+ * The registration order.
+ *
+ * The first eight are pinned by ticket 13 section 9 and keep their names and
+ * their positions. `get_changelog` is appended rather than inserted, because an
+ * agent holding a tool list from before this ticket finds every tool it knew at
+ * the index it knew it at. A Section joining the Corpus is a parameter on the
+ * existing tools, not a rename of them.
+ */
+export const TOOL_ORDER = [
+    'list_items',
+    'get_item_doc',
+    'get_item_props',
+    'get_item_source',
+    'get_theme_doc',
+    'list_pages',
+    'get_page',
+    'search_docs',
+    'get_changelog',
+];

package/dist/generated/built.d.ts

@@ -0,0 +1,2 @@
+export declare const BUILT: string | undefined;
+export declare const BUILT_CORPUS: string | undefined;

package/dist/generated/built.js

@@ -0,0 +1,6 @@
+// Generated by scripts/stamp-built.mjs. Gitignored; do not edit.
+// Derived from the corpus source commit date plus the corpus version. The
+// fallback is undefined (git or the corpus unavailable), which makes
+// list_items omit the (built ...) clause rather than fabricate a date.
+export const BUILT = "2026-09-28";
+export const BUILT_CORPUS = "0.7.0";

package/dist/generated/server-version.d.ts

@@ -0,0 +1 @@
+export declare const SERVER_VERSION: string;

package/dist/generated/server-version.js

@@ -0,0 +1,5 @@
+// Generated by scripts/stamp-built.mjs. Gitignored; do not edit.
+// Derived from this package's own package.json, which is the single place a
+// release writes a version. There is no fallback value: an unreadable manifest
+// throws in the step above rather than stamping a version this package is not.
+export const SERVER_VERSION = "0.4.1";

package/dist/index.d.ts

@@ -1,13 +1,14 @@
 /**
- * `@nanisoft/prism-mcp-server` — the Prism MCP tool surface (ADR-0004).
+ * @nanisoft/prism-mcp-server public surface.
  *
- * Transport-free: this package exports the pure `createPrismMcpServer(docs)`
- * factory plus the `PrismDocsStore` corpus contract it reads (this package is
- * that interface's canonical home — the consumer). It imports nothing from any
- * other workspace package at runtime; apps/site bundles the factory together
- * with `@nanisoft/prism-llms`' `data.json` at build time.
+ * One factory, the read-only tools, no transport: the Worker connects it to
+ * `createMcpHandler`, and the protocol tests connect it to an in-memory
+ * transport. The build stamp ships beside the factory so `list_items` can echo
+ * how fresh the bundled corpus is.
  */
-export { createPrismMcpServer, type PrismMcpServerOptions } from './factory.js';
-export { parsePrismDocsStore } from './store.js';
-export type { PrismDocsStore, PrismDocsItem, PrismDocsPage, PrismDocsTheme } from './store.js';
-//# sourceMappingURL=index.d.ts.map
+export { createPrismMcpServer } from './server.js';
+export type { PrismMcpServerOptions } from './server.js';
+export { BUILT, BUILT_CORPUS } from './generated/built.js';
+export { IMPORT_RULE, NO_INVENTION_RULE, SURFACE_RULE, describe } from './rules.js';
+export { SERVER_NAME, SERVER_VERSION } from './version.js';
+export { TOOL_ORDER } from './descriptions.js';

package/dist/index.js

@@ -1,12 +1,13 @@
 /**
- * `@nanisoft/prism-mcp-server` — the Prism MCP tool surface (ADR-0004).
+ * @nanisoft/prism-mcp-server public surface.
  *
- * Transport-free: this package exports the pure `createPrismMcpServer(docs)`
- * factory plus the `PrismDocsStore` corpus contract it reads (this package is
- * that interface's canonical home — the consumer). It imports nothing from any
- * other workspace package at runtime; apps/site bundles the factory together
- * with `@nanisoft/prism-llms`' `data.json` at build time.
+ * One factory, the read-only tools, no transport: the Worker connects it to
+ * `createMcpHandler`, and the protocol tests connect it to an in-memory
+ * transport. The build stamp ships beside the factory so `list_items` can echo
+ * how fresh the bundled corpus is.
  */
-export { createPrismMcpServer } from './factory.js';
-export { parsePrismDocsStore } from './store.js';
-//# sourceMappingURL=index.js.map
+export { createPrismMcpServer } from './server.js';
+export { BUILT, BUILT_CORPUS } from './generated/built.js';
+export { IMPORT_RULE, NO_INVENTION_RULE, SURFACE_RULE, describe } from './rules.js';
+export { SERVER_NAME, SERVER_VERSION } from './version.js';
+export { TOOL_ORDER } from './descriptions.js';

package/dist/render.d.ts

@@ -1,48 +1,73 @@
 /**
- * The markdown every tool answers with — the corpus is Markdown, so JSON
- * envelopes would only add tokens and quoting (ADR-0004 §2). All of these are
- * pure string builders over already-resolved data; lookup/search logic lives
- * elsewhere. Result text always prints the next call to make (§7).
+ * The pure renderers behind the tools.
+ *
+ * Every tool returns markdown and never touches I/O: the store is the whole
+ * input. A lookup miss is an `isError` result with did-you-mean suggestions and
+ * a browse pointer, never a throw, so a client sees the same contract on every
+ * transport.
  */
-import type { PrismDocsItem, PrismDocsPage, PrismDocsStore, PrismDocsTheme } from './store.js';
-import { type ItemKind } from './lookup.js';
-import type { SearchHit } from './search.js';
-/** The one import rule every description and every miss carries. */
-export declare const IMPORT_RULE = "Always import from '@nanisoft/prism-ui', never from antd directly.";
+import type { CallToolResult } from '@modelcontextprotocol/server';
+import { type PrismDocsStore, type PrismDocsStoreEntry } from '@nanisoft/prism-llms';
+import type { ComponentCategory, ItemKind, SearchKind } from './vocab.js';
+/** Every exact name or slug match in the optional kind, case-insensitively. */
+export declare function matchesFor(store: PrismDocsStore, name: string, kind?: ItemKind): PrismDocsStoreEntry[];
+export interface ListItemsArgs {
+    kind?: ItemKind;
+    category?: ComponentCategory;
+}
+export declare function renderListItems(store: PrismDocsStore, args: ListItemsArgs, built?: string): CallToolResult;
+export interface ItemArgs {
+    name: string;
+    kind?: ItemKind;
+}
+export declare function renderItemDoc(store: PrismDocsStore, args: ItemArgs): CallToolResult;
+export declare function renderItemProps(store: PrismDocsStore, args: ItemArgs): CallToolResult;
+export declare function renderItemSource(store: PrismDocsStore, args: ItemArgs): CallToolResult;
+export interface ThemeDocArgs {
+    pack?: string;
+    mode?: string;
+    group?: string;
+}
+export declare function renderThemeDoc(store: PrismDocsStore, args: ThemeDocArgs): CallToolResult;
+export declare function renderListPages(store: PrismDocsStore): CallToolResult;
+export interface PageArgs {
+    url: string;
+}
+export declare function renderPage(store: PrismDocsStore, args: PageArgs): CallToolResult;
+export interface SearchArgs {
+    query: string;
+    kind?: SearchKind;
+    limit?: number;
+}
+interface Candidate {
+    title: string;
+    kind: SearchKind;
+    url: string;
+    snippet: string;
+    content: string;
+    followUp: string;
+}
+export declare function searchCandidates(store: PrismDocsStore, kind?: SearchKind): Candidate[];
+export declare function searchDocs(store: PrismDocsStore, args: SearchArgs): CallToolResult;
+export interface ChangelogArgs {
+    package: string;
+    version?: string;
+}
 /**
- * `list_items` — the cold-start catalog. The header line carries the corpus
- * version (mismatch detection) and, when the bundler supplies one, the build
- * date; pass-throughs are marked with their antd base so the delegation seam
- * is visible before any per-item call.
+ * One published package's changelog, or one version entry of it.
+ *
+ * The text is the package's own file, byte for byte, because the Store carries
+ * the bytes rather than a summary of them. A generated summary would drift the
+ * moment a release was published, which is the one thing a changelog cannot do:
+ * a breaking change in a published package has to be discoverable by an agent
+ * that never saw the release notes anywhere else. The reference design system
+ * shipped a breaking module-system change that no agent using it could find, and
+ * the reason is precisely that its corpus had no changelog and no tool to return
+ * one.
+ *
+ * The footers state where the text is published, so an agent holding an older
+ * corpus can still fetch the same bytes over HTTP, and which versions exist, so
+ * one call can pick the next `version` to ask for.
  */
-export declare function catalogMarkdown(docs: PrismDocsStore, kind?: ItemKind, built?: string): string;
-/**
- * `get_item_doc` — the generator's page verbatim (usage rules, props, example,
- * the `> Extends:` seam), plus at most one steering footer built from the data.
- */
-export declare function itemDocMarkdown(item: PrismDocsItem): string;
-/**
- * `get_item_props` — only the Prism-added delta. A pass-through's answer *is*
- * the routing instruction (ADR-0004 §4: plasma's `_No additional props…_` line
- * is the switch-servers signal).
- */
-export declare function itemPropsMarkdown(item: PrismDocsItem): string;
-/** `get_item_source` — the documented example, verbatim, in one fenced block. */
-export declare function itemSourceMarkdown(item: PrismDocsItem, example: {
-    readonly slug: string;
-    readonly title?: string;
-    readonly code: string;
-}): string;
-/** `get_theme_doc` — the pack × mode atom verbatim, plus the sibling slugs. */
-export declare function themeMarkdown(theme: PrismDocsTheme, all: readonly PrismDocsTheme[]): string;
-/** `list_pages` — the site's llms.txt body as an index. */
-export declare function pagesIndexMarkdown(pages: readonly PrismDocsPage[], baseUrl: string): string;
-/** `get_page` — the prerendered page verbatim, cited back to the site. */
-export declare function pageMarkdown(page: PrismDocsPage, baseUrl: string): string;
-/** `search_docs` — ranked hits, each printing its own next call. */
-export declare function searchResultsMarkdown(query: string, hits: readonly SearchHit[]): string;
-/** A lookup miss: the closest names plus the browse pointer, as an error. */
-export declare function missMarkdown(target: string, suggestions: readonly string[], browseHint: string): string;
-/** A name hit whose `kind` argument pointed somewhere else. */
-export declare function kindMismatchMarkdown(item: PrismDocsItem, requested: ItemKind): string;
-//# sourceMappingURL=render.d.ts.map
+export declare function renderChangelog(store: PrismDocsStore, args: ChangelogArgs): CallToolResult;
+export {};