@savvy-web/mcp 1.3.3 → 1.3.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Savvy Web Strategy, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -42,7 +42,7 @@ npx @modelcontextprotocol/inspector savvy-mcp .
 ## Tools
 
 - `workspace_info` — returns a flat, structured projection of the workspace analysis: linked and fixed package groups as name arrays plus resolved registry targets. Backed by the same `silk-effects` analyzer the `savvy` CLI uses.
-- `silk_docs_search` — ranks documents in the corpus against a plain keyword or phrase query and returns hits with a normalized confidence score plus a high/medium/low label. It never returns empty: when nothing matches, it falls back to the priority-ordered top results.
+- `silk_docs_search` — ranks documents in the corpus against a plain keyword or phrase query and returns hits with a normalized confidence score plus a high/medium/low label. A query that matches nothing returns an empty result set, pointing the agent at `silk://catalog` to choose a doc by reasoning.
 - `turbo_inspect` — read-only Turborepo inspection over `turbo --dry`: diagnose a task's per-package cache hits, derive the task graph or list the packages affected by recent changes. It never runs a task. Backed by the same `silk-effects` `Turbo` inspector an agent would otherwise drive by hand.
 - `changeset_inspect` — read-only changeset analysis for release work: `mode=branch` diffs the current branch against its base and attributes every changed file to its owning package, `mode=config` surfaces the resolved `.changeset/config.json` with its release surfaces, version files and ignore list, and `mode=classify` reports how the branch's pending changesets classify each package's bump. It never writes a changeset. Backed by the same `silk-effects` changeset services the `savvy` CLI uses.
 - `changeset_validate` — read-only validation of the files in a changeset directory against the section-aware rules, returning typed diagnostics (file, rule, line, column, message) plus an ok flag and error count. Use it instead of shelling out to `savvy changeset lint`.
@@ -56,7 +56,7 @@ The server exposes a curated markdown corpus behind the `silk://` URI scheme:
 - `silk://catalog` — a single fixed resource listing every document grouped by tier with a "load when …" hint. The agent's mandated first read.
 - `silk://{+path}` — a template resolving any document by its stable id, covering Silk development standards (`silk://standards/<topic>`), per-package API and usage docs (`silk://packages/<pkg>/<topic>`) and conceptual guides (`silk://guides/<slug>`).
 
-Per-package API-reference docs under `silk://packages/<pkg>/api/*` are generated from API Extractor models and shipped with the package.
+Per-package API-reference docs under `silk://packages/<pkg>/api/*` are generated from API Extractor models and shipped with the package, with a bare `silk://packages/<pkg>/api` index page listing each package's symbols.
 
 ## License
 

package/{public/content → content}/guides/api-docs-from-api-extractor.md

@@ -1,12 +1,12 @@
 ---
 id: guides/api-docs-from-api-extractor
 title: Generating API docs from API Extractor
-summary: Configure apiModel, build the model, and render LLM-lean markdown with api-extractor-llms.
+summary: Configure the meta option, build the model, and render LLM-lean markdown with api-extractor-llms.
 tier: guides
 source: hand
 tags: [api, build]
 priority: 0.5
-related: [standards/api-model-pipeline, packages/rslib-builder/overview]
+related: [standards/api-model-pipeline, packages/bundler/overview]
 ---
 
 ## Overview
@@ -19,30 +19,38 @@ This guide walks through each stage as implemented in this repo.
 For the policy contract (what is generated, what must not be edited, where docs
 land), see `silk://standards/api-model-pipeline`.
 
-## Step 1 — Enable the API model in `rslib.config.ts`
+## Step 1 — Emit the API model from the build
 
-A library package opts in by passing an `apiModel` option to `NodeLibraryBuilder.create()`:
+A library built by `@savvy-web/bundler` emits an API Extractor model on its
+production build by default — there is nothing to enable. The model is controlled
+by the `meta` option in `savvy.build.ts`:
 
 ```typescript
-import { NodeLibraryBuilder } from "@savvy-web/rslib-builder";
+import { defineBuild, runBuild } from "@savvy-web/bundler";
 
-export default NodeLibraryBuilder.create({
-  apiModel: {
+const config = defineBuild({
+  // meta omitted → API model is generated with default options on --target prod.
+  // Pass an object only to override defaults, e.g. to register custom TSDoc tags:
+  meta: {
     tsdoc: {
       tagDefinitions: [{ tagName: "@since", syntaxKind: "block" }],
     },
   },
 });
-```
 
-Passing any truthy value for `apiModel` enables model emission. Options under
-`apiModel` are forwarded to the API Extractor TSDoc runner. A plain `apiModel: true`
-works when no custom tag definitions are needed.
+export default config;
 
-The entry point and package name are derived from the package's `exports` field.
-Only public API surfaces are captured; members annotated `@internal` are excluded.
+if (import.meta.main) {
+  await runBuild(config, { cwd: import.meta.dirname, argv: process.argv.slice(2) });
+}
+```
 
-See `silk://packages/rslib-builder/overview` for full builder configuration.
+Omitting `meta` generates the model with defaults; pass `false` to opt out
+entirely (the MCP server itself does this — it is an executable host, not a
+documented API). The entry point and package name are derived from `exports`.
+Only public surfaces are captured; members annotated `@internal` are excluded.
+
+See `silk://packages/bundler/overview` for the full builder surface.
 
 ## Step 2 — Build the model
 
@@ -50,12 +58,12 @@ See `silk://packages/rslib-builder/overview` for full builder configuration.
 pnpm --filter @savvy-web/your-package run build:prod
 ```
 
-The production build writes `dist/npm/<unscoped-name>.api.json`. For example,
-`@savvy-web/silk-effects` emits `dist/npm/silk-effects.api.json`. The filename
-is the unscoped package name with an `.api.json` suffix.
-
-`dist/dev/` may also contain a model depending on the build configuration.
-The generator script probes `dist/dev/` first, then `dist/npm/`.
+The production build writes `dist/prod/npm/meta/<unscoped-name>.api.json` and
+stages a copy into each consumer declared in `meta.localPaths` — for the MCP
+corpus that is `packages/mcp/lib/models/<dir>/<unscoped-name>.api.json`. For
+example, `@savvy-web/silk-effects` emits `silk-effects.api.json`. The generator
+reads the staged copy under `lib/models/`, so its inputs stay inside the mcp
+package and Turborepo can cache it.
 
 ## Step 3 — Render with `api-extractor-llms`
 
@@ -103,11 +111,13 @@ across all consumers.
 
 ## Step 4 — The MCP generator script
 
-`packages/mcp/scripts/generate-api-docs.ts` is the reference implementation of
+`packages/mcp/lib/scripts/generate-api-docs.ts` is the reference implementation of
 steps 3 and 4 for the MCP resource corpus. It iterates `API_TARGETS` (defined in
-`packages/mcp/scripts/api-targets.ts`), loads each model, injects silk-specific
-frontmatter and `silk://` crosslink routes, and writes output under
-`content/packages/<dir>/api/<kind>/<slug>.md` (gitignored).
+`packages/mcp/lib/scripts/api-targets.ts`), loads each model, injects silk-specific
+frontmatter and `silk://` crosslink routes, writes one page per symbol under
+`public/content/packages/<dir>/api/<kind>/<slug>.md`, and writes a per-package
+index page at `public/content/packages/<dir>/api.md` (served at the bare
+`silk://packages/<dir>/api` URI).
 
 ```typescript
 // The silk crosslink scheme
@@ -125,20 +135,24 @@ const docs = renderPackage(pkg, {
 ```
 
 Current targets (from `api-targets.ts`): `silk-effects`, `templates`,
-`github-action-effects`, `github-action-builder`. The MCP package itself and `cli`/`silk`
-are excluded (a generate→mcp build dependency would create a Turborepo cycle; cli
-and silk are not library APIs).
+`github-action-effects`, `github-action-builder`, `bundler`, `tsdown-plugins`,
+`rspress-builder`. The MCP package itself and `cli`/`silk` are excluded (a
+generate→mcp build dependency would create a Turborepo cycle; cli and silk are
+not library APIs).
 
 ## Step 5 — Compile into the corpus
 
 After `generate-api-docs.ts` writes the markdown files, `build:catalog` picks them
 up along with hand-authored docs and compiles the unified manifest. Generated docs
-appear in `silk://catalog` marked `(generated)`.
+appear in `silk://catalog` marked `(generated)`. The rendered markdown and the
+inflated manifest are committed tracked source — only the raw `.api.json` models
+under `lib/models/` are gitignored — so the published package ships the corpus
+even though a release machine does not regenerate it.
 
 In Turborepo the pipeline is:
 
 ```text
-build:prod (each library) → generate-api-docs → build:catalog
+build:prod (each library) → generate-api-docs → build:catalog → mcp build:prod
 ```
 
 ## Authoring notes
@@ -149,12 +163,12 @@ build:prod (each library) → generate-api-docs → build:catalog
   `silk://packages/foo/api/class/myservice`.
 - Cross-links in prose (`{@link OtherClass}`) resolve only if `OtherClass` is in
   the same package's rendered set.
-- Do not edit generated files under `content/packages/*/api/` — changes are
-  overwritten on the next `generate-api-docs` run.
+- Do not hand-edit files under `public/content/packages/*/api/` (or the `api.md`
+  index) — they are overwritten on the next `generate-api-docs` run; change the
+  source TSDoc instead.
 
 ## See also
 
 - `silk://standards/api-model-pipeline` — policy: what is generated, provenance
   markers, coverage scope
-- `silk://packages/rslib-builder/overview` — configuring the builder that emits
-  the model
+- `silk://packages/bundler/overview` — configuring the builder that emits the model

package/{public/content → content}/guides/building-a-github-action.md

@@ -24,8 +24,8 @@ Neither package depends on the other at build time. The builder bundles whatever
 action code you write; the effects library provides the services that code uses.
 
 For choosing the right builder, see `silk://guides/choosing-a-builder`. The
-github-action-builder is separate from rslib-builder and bun-builder — it targets
-a different output shape (single-file committed ESM bundles, not npm-published
+github-action-builder is separate from the library bundler — it targets a
+different output shape (single-file committed ESM bundles, not npm-published
 libraries).
 
 ## Step 1 — Project structure

package/content/guides/choosing-a-builder.md

@@ -0,0 +1,93 @@
+---
+id: guides/choosing-a-builder
+title: Choosing a builder
+summary: When to reach for @savvy-web/bundler, @savvy-web/rspress-builder, or @savvy-web/github-action-builder for a Silk package.
+tier: guides
+source: hand
+tags: [build]
+priority: 0.5
+related: [packages/bundler/overview, guides/building-a-github-action]
+---
+
+## Overview
+
+The Silk Suite has three zero-config build tools, each targeting a different
+output shape. Pick by what the package produces, not by personal preference.
+
+| Package | Builds | Output |
+| --- | --- | --- |
+| `@savvy-web/bundler` | TypeScript libraries | npm-published `dist/dev` + `dist/prod` |
+| `@savvy-web/rspress-builder` | RSPress doc-site plugins | npm-published plugin package |
+| `@savvy-web/github-action-builder` | Node.js 24 GitHub Actions | committed single-file ESM bundles |
+
+All three auto-detect their inputs, emit a transformed publish-ready
+`package.json` where applicable, and resolve `catalog:` and `workspace:` protocol
+references. They differ in what they emit and how it is consumed.
+
+## `@savvy-web/bundler`
+
+The **default** for any TypeScript library inside `savvy-web/systems` (or any
+pnpm-managed Silk Suite package). It is the tsdown-based build orchestrator: it
+reads `exports` to discover entry points, builds `dist/dev/` and per-target
+`dist/prod/<target>/`, emits a bundled self-contained `.d.ts` per public entry,
+and on `--target prod` emits an API Extractor model for MCP and website doc
+generation.
+
+A package opts in with a self-executing `savvy.build.ts` that calls `defineBuild`
+and `runBuild`, with `node savvy.build.ts --target dev` / `--target prod` build
+scripts. See `silk://packages/bundler/overview` for the full surface.
+
+### When to use it
+
+- You are building a library inside `savvy-web/systems` (or a pnpm-based Silk repo)
+- You publish to npm and want bundled type declarations
+- You want API Extractor model emission for MCP doc generation
+- The package uses `pnpm catalog:` or `workspace:` protocol in its dependencies
+
+## `@savvy-web/rspress-builder`
+
+A thin sibling to the bundler for **RSPress documentation-site plugins**. It
+applies the same entry-point discovery and publish transform, tuned for the
+shape an RSPress plugin package ships. Reach for it only when the package is an
+RSPress plugin; for every other library, use the bundler.
+
+## `@savvy-web/github-action-builder`
+
+For **Node.js 24 GitHub Actions**, whose output is a different shape entirely:
+self-contained ESM bundles committed to the repository (not an npm package) so a
+runner can execute them directly. It bundles `src/main.ts` (plus optional
+`pre.ts`/`post.ts`) into flat `dist/*.js` files and validates `action.yml`. See
+`silk://guides/building-a-github-action`.
+
+### When to use it
+
+- You are building a GitHub Action, not a published library
+- The output must be a committed single-file bundle referenced from `action.yml`
+
+## Decision guide
+
+```text
+Is the package a GitHub Action (committed Node.js 24 bundle)?
+  Yes → github-action-builder
+
+Is the package an RSPress doc-site plugin?
+  Yes → rspress-builder
+
+Otherwise (any npm-published TypeScript library)
+  → bundler
+```
+
+## Common pitfalls
+
+**bundler / rspress-builder:** Relative imports inside source must use `.js`
+extensions (the ESM requirement). The build reports "cannot find module" on a
+missing extension.
+
+**github-action-builder:** The `dist/` bundle must be committed so GitHub runners
+can execute it; `action.yml` must declare `runs.using: "node24"`.
+
+## See also
+
+- `silk://packages/bundler/overview` — the library build front door in full
+- `silk://guides/building-a-github-action` — GitHub Actions use a separate builder
+- `silk://standards/api-model-pipeline` — how the bundler's prod API model becomes docs