@savvy-web/mcp 0.1.0

package/index.js

@@ -0,0 +1,3 @@
+var src_CURRENT_MCP_VERSION = "0.0.0";
+export { SilkRuntimeLive, startMcpServer } from "./547.js";
+export { src_CURRENT_MCP_VERSION as CURRENT_MCP_VERSION };

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@savvy-web/mcp",
+  "version": "0.1.0",
+  "private": false,
+  "description": "The savvy MCP server — Silk Suite tooling and library knowledge for coding agents",
+  "homepage": "https://github.com/savvy-web/systems/tree/main/packages/mcp",
+  "bugs": {
+    "url": "https://github.com/savvy-web/systems/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/savvy-web/systems.git",
+    "directory": "packages/mcp"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "C. Spencer Beggs",
+    "email": "spencer@savvyweb.systems",
+    "url": "https://savvyweb.systems"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "bin": {
+    "savvy-mcp": "bin/savvy-mcp.js"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.1",
+    "@effect/platform-node": "^0.106.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@savvy-web/silk-effects": "0.6.0",
+    "effect": "^3.21.2",
+    "fuse.js": "^7.4.0",
+    "workspaces-effect": "^1.1.0",
+    "zod": "^4.4.3"
+  },
+  "files": [
+    "!mcp.api.json",
+    "!tsconfig.json",
+    "!tsdoc.json",
+    "547.js",
+    "bin/savvy-mcp.js",
+    "index.d.ts",
+    "index.js",
+    "package.json",
+    "resources/content/_templates/guides.md",
+    "resources/content/_templates/packages.md",
+    "resources/content/_templates/standards.md",
+    "resources/content/guides/api-docs-from-api-extractor.md",
+    "resources/content/guides/building-a-github-action.md",
+    "resources/content/guides/choosing-a-builder.md",
+    "resources/content/guides/llm-friendly-json-schemas.md",
+    "resources/content/manifest.json",
+    "resources/content/packages/cli/command-tree.md",
+    "resources/content/packages/cli/init-and-check.md",
+    "resources/content/packages/mcp/resource-taxonomy.md",
+    "resources/content/packages/rslib-builder/overview.md",
+    "resources/content/packages/silk-effects/index.md",
+    "resources/content/packages/silk-effects/managed-section.md",
+    "resources/content/packages/silk-effects/platform-layers.md",
+    "resources/content/packages/silk/export-map.md",
+    "resources/content/packages/silk/install-and-setup.md",
+    "resources/content/standards/api-model-pipeline.md",
+    "resources/content/standards/catalog-usage.md",
+    "resources/content/standards/changeset-discipline.md",
+    "resources/content/standards/changeset-format.md",
+    "resources/content/standards/commit-contract.md",
+    "resources/content/standards/dependency-conventions.md",
+    "resources/content/standards/linting-conventions.md",
+    "resources/content/standards/publishability.md",
+    "resources/content/standards/semver.md",
+    "resources/content/standards/test-classification.md",
+    "resources/content/tags.json",
+    "tsdoc-metadata.json"
+  ]
+}

package/resources/content/_templates/guides.md

@@ -0,0 +1,12 @@
+# Guide title
+
+A short intro framing the problem and when to read this guide.
+
+## A section
+
+Free-form prose, lists, and code as the topic demands. Keep each guide a single
+focused page; split when it outgrows the body budget.
+
+## Another section
+
+Close with concrete recommendations or a checklist where it helps.

package/resources/content/_templates/packages.md

@@ -0,0 +1,21 @@
+# Package topic title
+
+## What
+
+One paragraph: what this package or service is and the problem it solves.
+
+## API
+
+The key shapes, signatures, and statics a consumer touches. Condensed, not a full port.
+
+## Layer
+
+The Effect layer(s) and their platform requirements, or the install/build wiring.
+
+## Usage
+
+A short, runnable example of the common path.
+
+## Related
+
+Cross-link sibling digests and the standards they implement.

package/resources/content/_templates/standards.md

@@ -0,0 +1,17 @@
+# Standard title
+
+## Rule
+
+State the durable rule in one or two sentences. This is the thing that must hold.
+
+## Why
+
+Explain the reasoning the rule encodes, so a reader can apply judgment at the edges.
+
+## Examples
+
+Show a conforming case and a non-conforming case.
+
+## See also
+
+Cross-link related standards and package digests by `silk://` URI.

package/resources/content/guides/api-docs-from-api-extractor.md

@@ -0,0 +1,160 @@
+---
+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.
+tier: guides
+source: hand
+tags: [api, build]
+priority: 0.5
+related: [standards/api-model-pipeline, packages/rslib-builder/overview]
+---
+
+## Overview
+
+The Silk Suite generates API-reference docs from Microsoft API Extractor models
+rather than hand-authoring them. The pipeline has three stages: emit a model,
+render it to markdown, and compile rendered docs into the MCP resource corpus.
+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`
+
+A library package opts in by passing an `apiModel` option to `NodeLibraryBuilder.create()`:
+
+```typescript
+import { NodeLibraryBuilder } from "@savvy-web/rslib-builder";
+
+export default NodeLibraryBuilder.create({
+  apiModel: {
+    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.
+
+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.
+
+See `silk://packages/rslib-builder/overview` for full builder configuration.
+
+## Step 2 — Build the model
+
+```bash
+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/`.
+
+## Step 3 — Render with `api-extractor-llms`
+
+The rendering library takes a model path, two injectable callbacks, and returns
+one `RenderedDoc` per top-level public member.
+
+### Core API
+
+```typescript
+import { loadApiModel, renderPackage } from "api-extractor-llms";
+import type { FrontmatterRenderer, RouteFormatter } from "api-extractor-llms";
+
+const pkg = await loadApiModel("/path/to/silk-effects.api.json");
+
+const routeFor: RouteFormatter = (ref) =>
+  `silk://packages/silk-effects/api/${ref.kind}/${ref.slug}`;
+
+const frontmatter: FrontmatterRenderer = (meta) =>
+  `---\nid: packages/silk-effects/api/${meta.kind}/${meta.slug}\ntitle: "${meta.name}"\n---\n\n`;
+
+const docs = renderPackage(pkg, { packageName: "@savvy-web/silk-effects", routeFor, frontmatter });
+
+for (const doc of docs) {
+  // doc.markdown = frontmatter block + rendered body
+  // doc.kind, doc.name, doc.slug identify the item
+}
+```
+
+### What `renderPackage` produces
+
+For each top-level public member, the shared body renderer emits:
+
+- An ATX `# Name` heading
+- The TypeScript signature in a fenced `ts` code block (via `TypeSignatureFormatter`)
+- TSDoc summary paragraph
+- `## Parameters` list with types and descriptions (if any)
+- `## Returns` section (if documented)
+- `## Members` section listing class/interface/namespace members with signatures and summaries
+- `## Examples` blocks with language-tagged fences (from `@example` TSDoc tags)
+- Cross-links in prose resolved through the injected `routeFor` (via `CrossLinker`)
+
+The two injectable callbacks — `routeFor` (URL scheme) and `frontmatter` (YAML
+block) — are the only consumer-specific pieces. The body rendering is shared
+across all consumers.
+
+## Step 4 — The MCP generator script
+
+`packages/mcp/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).
+
+```typescript
+// The silk crosslink scheme
+const routeFor = (target: ApiTarget) => (ref: ApiItemRef) =>
+  `silk://${target.idPrefix}/api/${ref.kind}/${ref.slug}`;
+
+// The silk frontmatter renderer (derives id, title, summary, tags)
+const frontmatter = (meta: DocMeta) => toYaml(frontMatterFor(target, meta));
+
+const docs = renderPackage(pkg, {
+  packageName: target.packageName,
+  routeFor: routeFor(target),
+  frontmatter,
+});
+```
+
+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).
+
+## 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)`.
+
+In Turborepo the pipeline is:
+
+```text
+build:prod (each library) → generate-api-docs → build:catalog
+```
+
+## Authoring notes
+
+- TSDoc coverage determines output quality. Undocumented public members produce
+  sparse rendered docs with no summary or parameter descriptions.
+- The slug is the lowercased display name. A class `MyService` maps to
+  `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.
+
+## 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

package/resources/content/guides/building-a-github-action.md

@@ -0,0 +1,233 @@
+---
+id: guides/building-a-github-action
+title: Building a GitHub Action
+summary: Scaffold a Node.js 24 GitHub Action with @savvy-web/github-action-builder and the github-action-effects services.
+tier: guides
+source: hand
+tags: [github-actions, build]
+priority: 0.5
+related: [guides/choosing-a-builder, standards/api-model-pipeline]
+---
+
+## Overview
+
+Two packages work together to build and power Node.js 24 GitHub Actions in the
+Silk Suite:
+
+- **`@savvy-web/github-action-builder`** — zero-config rsbuild-based build tool
+  that bundles TypeScript source into self-contained ESM files and validates
+  `action.yml`
+- **`@savvy-web/github-action-effects`** — Effect service library replacing all
+  `@actions/*` packages with native ESM implementations
+
+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
+libraries).
+
+## Step 1 — Project structure
+
+```text
+my-action/
+├── src/
+│   ├── main.ts      # Required — main action logic
+│   ├── pre.ts       # Optional — pre-action hook
+│   └── post.ts      # Optional — post-action hook
+├── action.yml       # GitHub metadata; must have runs.using: "node24"
+└── package.json
+```
+
+The builder auto-detects `src/pre.ts` and `src/post.ts` if they exist. Only
+`src/main.ts` is required.
+
+`action.yml` must declare `runs.using: "node24"`. The builder validates this and
+fails if any other value is present.
+
+## Step 2 — Install and configure the builder
+
+```bash
+pnpm add -D @savvy-web/github-action-builder
+```
+
+Zero-config usage — no config file needed:
+
+```bash
+github-action-builder build
+```
+
+Or create an optional `action.config.ts` for customization:
+
+```typescript
+import { defineConfig } from "@savvy-web/github-action-builder";
+
+export default defineConfig({
+  build: {
+    minify: true,        // default: true
+    sourceMap: false,    // default: false
+    externals: [],       // exclude from bundle (must be available at runtime)
+    ignore: [],          // replace with a throwing stub
+  },
+  validation: {
+    requireActionYml: true,
+    strict: undefined,   // auto-detects CI; warn locally, error in CI
+  },
+  persistLocal: {
+    enabled: true,       // auto-copy to .github/actions/local/ after build
+    path: ".github/actions/local",
+  },
+});
+```
+
+### Build output
+
+Each detected entry emits one flat ESM file:
+
+| Input | Output |
+| --- | --- |
+| `src/main.ts` | `dist/main.js` |
+| `src/pre.ts` | `dist/pre.js` |
+| `src/post.ts` | `dist/post.js` |
+| (generated) | `dist/package.json` |
+
+All output files are self-contained ESM bundles. Dynamic `import()` calls are
+folded back into the parent file (`asyncChunks: false`), so `action.yml` can
+always reference a known single-file path.
+
+The builder also copies output to `.github/actions/local/` for local testing with
+[nektos/act](https://github.com/nektos/act) unless `persistLocal.enabled: false`.
+
+## Step 3 — Write action logic with `github-action-effects`
+
+```bash
+pnpm add @savvy-web/github-action-effects
+```
+
+The library provides 37 Effect service interfaces across six domains:
+
+| Domain | Services cover |
+| --- | --- |
+| Core action I/O | Outputs, state, logging, environment, cache |
+| Git operations | Branches, commits, tags via Git Data API |
+| GitHub API | REST client, GraphQL, releases, issues, PR lifecycle, check runs, rate limiting |
+| Build tooling | Command execution, npm registry, workspace detection, changeset analysis |
+| Attestation | SLSA statement construction, Sigstore signing, CycloneDX SBOM generation |
+| Runtime layer | GitHub Actions workflow command protocol, `ActionsConfigProvider`, `ActionsLogger`, `Step` |
+
+### Runtime layer
+
+The runtime layer replaces all `@actions/*` packages with native ESM implementations:
+
+```typescript
+import { Effect, Config } from "effect";
+import { ActionsRuntime, Action, Step } from "@savvy-web/github-action-effects";
+
+const program = Effect.gen(function* () {
+  // Inputs via Effect's Config API (reads INPUT_* env vars)
+  const name = yield* Config.string("name");
+  const count = yield* Config.integer("count");
+
+  // Logging maps to workflow commands
+  yield* Effect.log("Processing...");        // plain stdout
+  yield* Effect.logDebug("detail");          // ::debug::detail
+  yield* Effect.logWarning("heads up");      // ::warning::heads up
+
+  // Step buffering: one success line on pass, spills debug buffer on fail
+  yield* Step.withStep("fetch data", fetchData(name));
+});
+
+// Provide the runtime layer
+Action.run(program);
+// or: program.pipe(Effect.provide(ActionsRuntime.Default))
+```
+
+### Reading inputs
+
+Action inputs are read via Effect's `Config` API backed by `ActionsConfigProvider`,
+which translates config keys to `INPUT_*` environment variables:
+
+```typescript
+const repoName = yield* Config.string("repo-name"); // reads INPUT_REPO-NAME
+```
+
+### Composing services
+
+Services are provided via Effect Layers. The programmatic pattern:
+
+```typescript
+import { Effect } from "effect";
+import {
+  ActionsRuntime,
+  GitHubClient,
+  GitHubClientLive,
+} from "@savvy-web/github-action-effects";
+
+const program = Effect.gen(function* () {
+  const client = yield* GitHubClient;
+  // use client ...
+});
+
+program.pipe(
+  Effect.provide(GitHubClientLive),
+  Effect.provide(ActionsRuntime.Default),
+  Effect.runPromise,
+);
+```
+
+### Testing
+
+The library exports a `./testing` subpath that excludes `GitHubClientLive` and
+`OctokitAuthAppLive` (which import `@octokit/rest`/`@octokit/auth-app`). Use this
+in test files to avoid pulling in those dependencies:
+
+```typescript
+import { ... } from "@savvy-web/github-action-effects/testing";
+```
+
+## Step 4 — Validate and CI
+
+```bash
+# Validate action.yml and entry structure without building
+github-action-builder validate
+
+# Full build with validation
+github-action-builder build
+```
+
+In CI (`CI=true` or `GITHUB_ACTIONS=true`), validation warnings become errors and
+fail the build. Locally they are displayed as warnings and the build continues.
+
+Add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "github-action-builder build",
+    "validate": "github-action-builder validate"
+  }
+}
+```
+
+## Step 5 — Reference the built output in `action.yml`
+
+```yaml
+name: My Action
+description: Does something useful
+runs:
+  using: node24
+  main: dist/main.js
+  post: dist/post.js    # if you have a post step
+```
+
+The `dist/` directory must be committed to the repository so GitHub runners can
+execute it. The builder's `persistLocal` feature also syncs to
+`.github/actions/local/` for local `act` runs.
+
+## See also
+
+- `silk://guides/choosing-a-builder` — when to use github-action-builder vs the
+  library builders
+- `silk://standards/api-model-pipeline` — if your action repo also publishes a
+  library whose API is documented

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

@@ -0,0 +1,140 @@
+---
+id: guides/choosing-a-builder
+title: Choosing a builder (rslib vs bun)
+summary: When to reach for @savvy-web/rslib-builder vs @savvy-web/bun-builder for a Silk package.
+tier: guides
+source: hand
+tags: [build]
+priority: 0.5
+related: [packages/rslib-builder/overview]
+---
+
+## Overview
+
+The Silk Suite has two zero-config build tools for TypeScript libraries:
+
+| Package | Bundler core | Primary target |
+| --- | --- | --- |
+| `@savvy-web/rslib-builder` | rsbuild / rspack | Node.js (pnpm monorepos) |
+| `@savvy-web/bun-builder` | Bun.build() | Bun monorepos |
+
+Both tools auto-detect entry points from `package.json` `exports`, emit `dist/dev/`
+and `dist/npm/` build modes, generate rolled-up `.d.ts` declarations via API
+Extractor, resolve `catalog:` and `workspace:` protocol references for publishing,
+and transform the output `package.json` for publish readiness.
+
+## `@savvy-web/rslib-builder`
+
+The **ecosystem default** for packages inside the `savvy-web/systems` monorepo and
+any pnpm-managed Silk Suite package.
+
+### What it does
+
+- Zero-config builds via `NodeLibraryBuilder.create({})` in `rslib.config.ts`
+- Reads `exports` to discover entry points; builds `dist/dev/` and `dist/npm/`
+- Generates type declarations and emits a Microsoft API Extractor model
+  (`<unscoped>.api.json`) on the npm build
+- Transforms the output `package.json`: resolves `pnpm catalog:` references,
+  flips `private: true` to publish-ready based on `publishConfig.access`, rewrites
+  export paths from `.ts` to `.js`, adds type conditions
+- Supports dual-format ESM+CJS builds when needed (e.g. `@savvy-web/silk` for CJS
+  consumers)
+- Peer dependencies: `@rslib/core`, `@typescript/native-preview`
+
+### Configuration
+
+```typescript
+import { NodeLibraryBuilder } from "@savvy-web/rslib-builder";
+
+export default NodeLibraryBuilder.create({
+  externals: ["effect", "@effect/platform"],
+  apiModel: {
+    tsdoc: {
+      tagDefinitions: [{ tagName: "@since", syntaxKind: "block" }],
+    },
+  },
+});
+```
+
+Pass `apiModel: true` (or an options object) to enable API Extractor model
+emission. See `silk://packages/rslib-builder/overview` for full details.
+
+### When to use it
+
+- You are building a package inside `savvy-web/systems` (or a pnpm-based Silk repo)
+- You need dual-format ESM+CJS output
+- You want API Extractor model emission for MCP doc generation
+- The package uses `pnpm catalog:` or `workspace:` protocol in its dependencies
+
+## `@savvy-web/bun-builder`
+
+For **Bun-managed monorepos** where Bun.build() is the preferred bundler.
+
+### What it does
+
+- Zero-config builds via `BunLibraryBuilder.create({})` in `bun.config.ts`
+- Auto-detects entry points from `package.json` `exports`
+- Bundled or bundleless output (`bundle: false` preserves source structure)
+- Rolled-up `.d.ts` in bundled mode; raw `.d.ts` in bundleless mode
+- API Extractor model generation on npm builds (enabled by default)
+- TSDoc warnings reported with source locations; severity configurable per
+  environment (`"fail"` in CI, `"log"` locally)
+- Resolves Bun `catalog:` and `workspace:` protocol references for publishing
+- Peer dependencies: `@microsoft/api-extractor`, `@typescript/native-preview`,
+  `typescript`, `@types/bun`
+
+### Configuration
+
+```typescript
+import { BunLibraryBuilder } from "@savvy-web/bun-builder";
+
+export default BunLibraryBuilder.create({
+  bundle: true,       // default; set false for bundleless
+  apiModel: true,     // default; emits model on npm build
+});
+```
+
+Build via:
+
+```bash
+bun run bun.config.ts              # all modes
+bun run bun.config.ts --env-mode dev
+bun run bun.config.ts --env-mode npm
+```
+
+### When to use it
+
+- You are in a Bun-managed workspace (`bun.lock`, Bun catalog protocol)
+- You want sub-second build iteration times
+- You do not need rspack's CJS-to-ESM interop (which is important for certain
+  bundled GitHub Actions scenarios)
+
+## Decision guide
+
+```text
+Is this a package in savvy-web/systems (pnpm monorepo)?
+  Yes → rslib-builder
+
+Does the package need dual-format ESM+CJS output?
+  Yes → rslib-builder
+
+Is this a Bun-managed workspace?
+  Yes → bun-builder
+
+Are you building a GitHub Action (bundled Node.js 24 binary)?
+  Use @savvy-web/github-action-builder instead — see silk://guides/building-a-github-action
+```
+
+## Common pitfalls
+
+**rslib-builder:** Relative imports inside source must use `.js` extensions
+(ESM requirement). The build will report "cannot find module" on missing extensions.
+
+**bun-builder:** The Bun catalog protocol uses `workspaces.catalog` in the root
+`package.json`, distinct from pnpm's catalog. Do not mix the two in the same
+workspace.
+
+## See also
+
+- `silk://packages/rslib-builder/overview` — full rslib-builder reference
+- `silk://guides/building-a-github-action` — GitHub Actions use a separate builder