@savvy-web/mcp 1.3.5 → 1.4.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@savvy-web%2Fmcp?label=npm&color=cb3837)](https://www.npmjs.com/package/@savvy-web/mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
 
-The `savvy-mcp` [Model Context Protocol](https://modelcontextprotocol.io/) server. It serves [Silk Suite](https://github.com/savvy-web/systems) tooling and library knowledge to coding agents as structured tools and a curated documentation corpus, so an agent can read workspace facts and Silk docs instead of parsing console output or guessing.
+The `savvy-mcp` [Model Context Protocol](https://modelcontextprotocol.io/) server. It serves [Silk Suite](https://github.com/savvy-web/systems) tooling to coding agents as structured tools, so an agent can read workspace facts and run Silk checks instead of parsing console output or guessing. It is a tools-only server — six tools, no resources.
 
 ## Install
 
@@ -42,22 +42,12 @@ 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. 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`.
 - `changeset_preview` — read-only preview of the next release: it runs the genuine changesets engine over the pending changesets and returns each package's version bump (old to new) plus the rendered CHANGELOG block, exactly as it would ship. It never mutates the repo. Backed by the same `silk-effects` release planner the `savvy changeset version` command applies.
 - `biome_check` — run Biome over a path and get structured diagnostics back: `mode=check` (lint, format and organize-imports) or `mode=lint`. Unlike the other tools it can mutate — pass `write` for safe fixes or `unsafe` for unsafe ones (both git-reversible) — so it returns the same diagnostics the Biome LSP surfaces for files you have edited.
 
-## Resources
-
-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, with a bare `silk://packages/<pkg>/api` index page listing each package's symbols.
-
 ## License
 
 [MIT](LICENSE)

package/bin/savvy-mcp.js

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 import { SilkRuntimeLive } from "../runtime.js";
-import { loadManifest, readDocBody, resolveContentRoot } from "../resources/load.js";
 import { startMcpServer } from "../server.js";
-import { DocIndex } from "../resources/doc-index.js";
 import { Layer, ManagedRuntime } from "effect";
 import { NodeContext } from "@effect/platform-node";
 
@@ -23,16 +21,9 @@ function resolveProjectDir() {
 async function main() {
 	const cwd = resolveProjectDir();
 	const appLayer = SilkRuntimeLive.pipe(Layer.provide(NodeContext.layer));
-	const runtime = ManagedRuntime.make(appLayer);
-	const contentRoot = resolveContentRoot();
-	const manifest = loadManifest(contentRoot);
-	const bodies = Object.fromEntries(manifest.entries.map((e) => [e.uri, readDocBody(contentRoot, e.uri.replace(/^silk:\/\//, ""))]));
 	const ctx = {
-		runtime,
-		cwd,
-		docIndex: DocIndex.fromManifest(manifest, bodies),
-		manifest,
-		contentRoot
+		runtime: ManagedRuntime.make(appLayer),
+		cwd
 	};
 	process.stderr.write(`[savvy-mcp] starting in ${cwd}\n`);
 	await startMcpServer(ctx);

package/index.d.ts

@@ -1,94 +1,11 @@
 import { Changesets, SilkWorkspaceAnalyzer, Turbo } from "@savvy-web/silk-effects";
-import { Layer, ManagedRuntime, Schema } from "effect";
+import { Layer, ManagedRuntime } from "effect";
 import { WorkspaceDiscoveryError, WorkspaceRoot } from "workspaces-effect";
-//#region src/resources/schema.d.ts
-/** A manifest entry = decoded front-matter + the derived uri + lastModified. */
-declare const ManifestEntry: Schema.Struct<{
-  id: Schema.filter<typeof Schema.String>;
-  title: typeof Schema.NonEmptyString;
-  summary: typeof Schema.NonEmptyString;
-  tier: Schema.Literal<["standards", "packages", "guides"]>;
-  source: Schema.Literal<["hand", "generated"]>;
-  status: Schema.optionalWith<Schema.Literal<["draft", "stable", "deprecated"]>, {
-    default: () => "stable";
-  }>;
-  supersededBy: Schema.optional<typeof Schema.String>;
-  tags: Schema.Array$<typeof Schema.NonEmptyString>;
-  audience: Schema.optionalWith<Schema.Array$<Schema.Literal<["user", "assistant"]>>, {
-    default: () => ReadonlyArray<"assistant">;
-  }>;
-  priority: Schema.optionalWith<Schema.filter<typeof Schema.Number>, {
-    default: () => number;
-  }>;
-  related: Schema.optionalWith<Schema.Array$<typeof Schema.String>, {
-    default: () => ReadonlyArray<string>;
-  }>;
-  uri: typeof Schema.String;
-  lastModified: Schema.optional<typeof Schema.String>;
-}>;
-type ManifestEntry = Schema.Schema.Type<typeof ManifestEntry>;
-declare const Manifest: Schema.Struct<{
-  entries: Schema.Array$<Schema.Struct<{
-    id: Schema.filter<typeof Schema.String>;
-    title: typeof Schema.NonEmptyString;
-    summary: typeof Schema.NonEmptyString;
-    tier: Schema.Literal<["standards", "packages", "guides"]>;
-    source: Schema.Literal<["hand", "generated"]>;
-    status: Schema.optionalWith<Schema.Literal<["draft", "stable", "deprecated"]>, {
-      default: () => "stable";
-    }>;
-    supersededBy: Schema.optional<typeof Schema.String>;
-    tags: Schema.Array$<typeof Schema.NonEmptyString>;
-    audience: Schema.optionalWith<Schema.Array$<Schema.Literal<["user", "assistant"]>>, {
-      default: () => ReadonlyArray<"assistant">;
-    }>;
-    priority: Schema.optionalWith<Schema.filter<typeof Schema.Number>, {
-      default: () => number;
-    }>;
-    related: Schema.optionalWith<Schema.Array$<typeof Schema.String>, {
-      default: () => ReadonlyArray<string>;
-    }>;
-    uri: typeof Schema.String;
-    lastModified: Schema.optional<typeof Schema.String>;
-  }>>;
-}>;
-type Manifest = Schema.Schema.Type<typeof Manifest>;
-//#endregion
-//#region src/resources/doc-index.d.ts
-interface SearchResult {
-  readonly uri: string;
-  readonly title: string;
-  readonly summary: string;
-  readonly tags: ReadonlyArray<string>;
-  readonly tier: ManifestEntry["tier"];
-  readonly confidence: number;
-  readonly confidenceLabel: "high" | "medium" | "low";
-  readonly matchedOn: ReadonlyArray<string>;
-  readonly related: ReadonlyArray<string>;
-}
-interface SearchOptions {
-  readonly limit?: number;
-  readonly tier?: ManifestEntry["tier"];
-}
-declare class DocIndex {
-  private readonly fuse;
-  private readonly entries;
-  private readonly byUri;
-  private constructor();
-  static fromManifest(manifest: Manifest, bodies: Readonly<Record<string, string>>): DocIndex;
-  search(query: string, opts?: SearchOptions): SearchResult[];
-  /** Browse fallback: surface the top entries (by priority) as low-confidence. */
-  private fallback;
-}
-//#endregion
 //#region src/context.d.ts
-/** The long-lived runtime, the project working directory, and the resource layer. */
+/** The long-lived runtime and the project working directory. */
 interface McpContext {
   readonly runtime: ManagedRuntime.ManagedRuntime<SilkWorkspaceAnalyzer | WorkspaceRoot | Turbo.TurboInspector | Changesets.BranchAnalyzer | Changesets.ConfigInspector | Changesets.ReleasePlanner, WorkspaceDiscoveryError>;
   readonly cwd: string;
-  readonly docIndex: DocIndex;
-  readonly manifest: Manifest;
-  readonly contentRoot: string;
 }
 //#endregion
 //#region src/runtime.d.ts
@@ -120,5 +37,5 @@ declare function startMcpServer(ctx: McpContext): Promise<void>;
  */
 declare const CURRENT_MCP_VERSION = "0.0.0";
 //#endregion
-export { CURRENT_MCP_VERSION, type DocIndex, type Manifest, type ManifestEntry, type McpContext, type SearchOptions, type SearchResult, SilkRuntimeLive, startMcpServer };
+export { CURRENT_MCP_VERSION, type McpContext, SilkRuntimeLive, startMcpServer };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/mcp",
-	"version": "1.3.5",
+	"version": "1.4.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",
@@ -38,7 +38,6 @@
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@savvy-web/silk-effects": "1.5.2",
 		"effect": "^3.21.4",
-		"fuse.js": "^7.4.0",
 		"workspaces-effect": "^1.2.0",
 		"zod": "^4.4.3"
 	}

package/server.js

@@ -1,11 +1,8 @@
-import { registerAllResources } from "./resources/index.js";
-import { stderrQueryLogger } from "./resources/query-log.js";
 import { effectToZodSchema } from "./schema/effect-to-zod.js";
 import { BiomeCheckAsMarkdown, BiomeCheckResult, runBiomeCheck } from "./tools/biome-check.js";
 import { ChangesetInspectAsMarkdown, ChangesetInspectResult, changesetInspect } from "./tools/changeset-inspect.js";
 import { ChangesetPreviewAsMarkdown, ChangesetPreviewResult, changesetPreview } from "./tools/changeset-preview.js";
 import { ChangesetValidateAsMarkdown, ChangesetValidateResult, changesetValidate } from "./tools/changeset-validate.js";
-import { DocsSearchResult, DocsSearchResultAsMarkdown, runDocsSearch } from "./tools/docs-search.js";
 import { TurboInspectAsMarkdown, TurboInspectResult, turboInspect } from "./tools/turbo-inspect.js";
 import { WorkspaceInfoAsMarkdown, WorkspaceInfoResult, workspaceInfo } from "./tools/workspace-info.js";
 import { CURRENT_MCP_VERSION } from "./version.js";
@@ -16,8 +13,8 @@ import { z } from "zod";
 
 //#region src/server.ts
 /**
-* Constructs the MCP server, registers tools and resources, and connects the
-* stdio transport.
+* Constructs the MCP server, registers tools, and connects the stdio
+* transport.
 *
 * @packageDocumentation
 */
@@ -29,7 +26,7 @@ const structuredResult = (text, structured) => ({
 	}],
 	structuredContent: structured
 });
-/** Build the MCP server for the given context, registering tools + resources. */
+/** Build the MCP server for the given context, registering tools. */
 function buildServer(ctx) {
 	const server = new McpServer({
 		name: "savvy-mcp",
@@ -44,26 +41,6 @@ function buildServer(ctx) {
 		const data = await ctx.runtime.runPromise(workspaceInfo(root));
 		return structuredResult(Schema.decodeSync(WorkspaceInfoAsMarkdown)(data), data);
 	});
-	server.registerTool("silk_docs_search", {
-		description: "Search Silk documentation by intent. Pass plain keywords or a short phrase describing what you need (e.g. 'changeset bump rules'). Returns ranked docs with a confidence label; fetch a hit with resources/read <uri>. Read silk://catalog first to orient.",
-		inputSchema: {
-			query: z.string().describe("Keywords or a short phrase describing the doc you need."),
-			limit: z.optional(z.number()).describe("Max results (default 10)."),
-			tier: z.optional(z.enum([
-				"standards",
-				"packages",
-				"guides"
-			])).describe("Restrict to one tier.")
-		},
-		outputSchema: effectToZodSchema(DocsSearchResult),
-		annotations: { readOnlyHint: true }
-	}, async (args) => {
-		const data = runDocsSearch(ctx.docIndex, args.query, {
-			...args.limit !== void 0 ? { limit: args.limit } : {},
-			...args.tier !== void 0 ? { tier: args.tier } : {}
-		}, stderrQueryLogger);
-		return structuredResult(Schema.decodeSync(DocsSearchResultAsMarkdown)(data), data);
-	});
 	server.registerTool("turbo_inspect", {
 		description: "Read-only Turborepo inspection. mode=cache diagnoses why a task's cache is hitting/missing (per-package status plus the exact hash contributors: input files, env vars, external-dep hashes, global hash). mode=graph returns the task graph and critical path. mode=affected lists changed packages and their dependents. Never executes tasks (uses --dry).",
 		inputSchema: {
@@ -135,10 +112,6 @@ function buildServer(ctx) {
 		const data = await runBiomeCheck(args, ctx.cwd);
 		return structuredResult(Schema.decodeSync(BiomeCheckAsMarkdown)(data), data);
 	});
-	registerAllResources(server, {
-		manifest: ctx.manifest,
-		contentRoot: ctx.contentRoot
-	});
 	return server;
 }
 /** Build the server and connect it over stdio. */

package/tools/biome-check.js

@@ -1,8 +1,8 @@
 import { Lint } from "@savvy-web/silk-effects";
 import { ParseResult, Schema } from "effect";
+import { spawnSync } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
-import { spawnSync } from "node:child_process";
 
 //#region src/tools/biome-check.ts
 /**

package/content/_templates/guides.md

@@ -1,12 +0,0 @@
-# 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/content/_templates/packages.md

@@ -1,21 +0,0 @@
-# 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/content/_templates/standards.md

@@ -1,17 +0,0 @@
-# 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/content/guides/api-docs-from-api-extractor.md

@@ -1,174 +0,0 @@
----
-id: guides/api-docs-from-api-extractor
-title: Generating API docs from API Extractor
-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/bundler/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 — Emit the API model from the build
-
-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 { defineBuild, runBuild } from "@savvy-web/bundler";
-
-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" }],
-    },
-  },
-});
-
-export default config;
-
-if (import.meta.main) {
-  await runBuild(config, { cwd: import.meta.dirname, argv: process.argv.slice(2) });
-}
-```
-
-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
-
-```bash
-pnpm --filter @savvy-web/your-package run build:prod
-```
-
-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`
-
-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/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/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
-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`, `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)`. 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 → mcp build:prod
-```
-
-## 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 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/bundler/overview` — configuring the builder that emits the model