@savvy-web/mcp 0.4.1 → 0.4.2

package/bin/savvy-mcp.d.ts

@@ -0,0 +1 @@
+export { };

package/index.d.ts

@@ -0,0 +1,122 @@
+import { SilkWorkspaceAnalyzer, Turbo } from "@savvy-web/silk-effects";
+import { Layer, ManagedRuntime, Schema } 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<{
+  uri: typeof Schema.String;
+  lastModified: Schema.optional<typeof Schema.String>;
+  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>;
+  }>;
+}>;
+type ManifestEntry = Schema.Schema.Type<typeof ManifestEntry>;
+declare const Manifest: Schema.Struct<{
+  entries: Schema.Array$<Schema.Struct<{
+    uri: typeof Schema.String;
+    lastModified: Schema.optional<typeof Schema.String>;
+    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>;
+    }>;
+  }>>;
+}>;
+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[];
+  /** Never return empty: 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. */
+interface McpContext {
+  readonly runtime: ManagedRuntime.ManagedRuntime<SilkWorkspaceAnalyzer | WorkspaceRoot | Turbo.TurboInspector, WorkspaceDiscoveryError>;
+  readonly cwd: string;
+  readonly docIndex: DocIndex;
+  readonly manifest: Manifest;
+  readonly contentRoot: string;
+}
+//#endregion
+//#region src/runtime.d.ts
+/**
+ * The MCP runtime layer. Provides `SilkWorkspaceAnalyzer`, `WorkspaceRoot`, and
+ * `Turbo.TurboInspector`; requires `CommandExecutor` + `FileSystem` + `Path`
+ * from the host's platform layer (`NodeContext.layer` in bin.ts).
+ *
+ * `TurboInspectorLive` is fed its own `ToolDiscoveryLive`, whose
+ * `PackageManagerDetector` + `WorkspaceRoot` requirements are satisfied by
+ * {@link DepsLive}; the leftover `CommandExecutor` + `FileSystem` flow up to the
+ * host platform layer.
+ */
+declare const SilkRuntimeLive: Layer.Layer<import("@savvy-web/silk-effects").SilkWorkspaceAnalyzer | import("workspaces-effect").WorkspaceRoot | Turbo.TurboInspector, import("workspaces-effect").WorkspaceDiscoveryError, import("@effect/platform/FileSystem").FileSystem | import("@effect/platform/Path").Path | import("@effect/platform/CommandExecutor").CommandExecutor>;
+//#endregion
+//#region src/server.d.ts
+/** Build the server and connect it over stdio. */
+declare function startMcpServer(ctx: McpContext): Promise<void>;
+//#endregion
+//#region src/version.d.ts
+/**
+ * The package version, replaced at build time. `0.0.0` in dev/test indicates
+ * an unbuilt source run. Kept in its own module so both `server.ts` and the
+ * `index.ts` barrel can import it without forming an import cycle.
+ *
+ * @packageDocumentation
+ */
+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 };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,5 @@
+import { SilkRuntimeLive } from "./runtime.js";
+import { CURRENT_MCP_VERSION } from "./version.js";
+import { startMcpServer } from "./server.js";
+
+export { CURRENT_MCP_VERSION, SilkRuntimeLive, startMcpServer };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/mcp",
-	"version": "0.4.1",
+	"version": "0.4.2",
 	"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",
@@ -28,9 +28,6 @@
 	"bin": {
 		"savvy-mcp": "bin/savvy-mcp.js"
 	},
-	"files": [
-		"public"
-	],
 	"dependencies": {
 		"@effect/platform": "^0.96.1",
 		"@effect/platform-node": "^0.106.0",

package/resources/catalog.js

@@ -0,0 +1,29 @@
+//#region src/resources/catalog.ts
+const TIER_HEADINGS = [
+	["standards", "Standards"],
+	["packages", "Packages"],
+	["guides", "Guides"]
+];
+function renderCatalogMarkdown(manifest) {
+	const lines = [
+		"# silk://catalog",
+		"",
+		"Read this first to orient. To fetch a doc, call `resources/read` with its `silk://` URI.",
+		"To search by intent, use the `silk_docs_search` tool.",
+		""
+	];
+	for (const [tier, heading] of TIER_HEADINGS) {
+		const entries = manifest.entries.filter((e) => e.tier === tier && e.status !== "deprecated");
+		if (entries.length === 0) continue;
+		lines.push(`## ${heading}`, "");
+		for (const e of entries) {
+			const gen = e.source === "generated" ? " (generated)" : "";
+			lines.push(`- \`${e.uri}\`${gen} — ${e.title}. load when: ${e.summary}`);
+		}
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+
+//#endregion
+export { renderCatalogMarkdown };

package/resources/doc-index.js

@@ -0,0 +1,112 @@
+import Fuse from "fuse.js";
+
+//#region src/resources/doc-index.ts
+const STOP_WORDS = new Set([
+	"how",
+	"do",
+	"i",
+	"the",
+	"a",
+	"an",
+	"to",
+	"of",
+	"in",
+	"for",
+	"is",
+	"what",
+	"when",
+	"use"
+]);
+const FUSE_THRESHOLD = .6;
+const confidenceLabel = (confidence) => confidence >= .6 ? "high" : confidence >= .4 ? "medium" : "low";
+const toRanked = (item, score, matches) => ({
+	item,
+	confidence: 1 - (score ?? 1),
+	matchedOn: matches.map((m) => m.key ?? "")
+});
+var DocIndex = class DocIndex {
+	fuse;
+	entries;
+	byUri;
+	constructor(fuse, entries, byUri) {
+		this.fuse = fuse;
+		this.entries = entries;
+		this.byUri = byUri;
+	}
+	static fromManifest(manifest, bodies) {
+		const entries = manifest.entries.filter((e) => e.status !== "deprecated").map((e) => ({
+			...e,
+			body: bodies[e.uri] ?? ""
+		}));
+		return new DocIndex(new Fuse(entries, {
+			useExtendedSearch: true,
+			ignoreLocation: true,
+			includeScore: true,
+			includeMatches: true,
+			minMatchCharLength: 2,
+			threshold: FUSE_THRESHOLD,
+			keys: [
+				{
+					name: "title",
+					weight: .55
+				},
+				{
+					name: "tags",
+					weight: .3
+				},
+				{
+					name: "summary",
+					weight: .12
+				},
+				{
+					name: "body",
+					weight: .03
+				}
+			]
+		}), entries, new Map(entries.map((e) => [e.uri, e])));
+	}
+	search(query, opts = {}) {
+		const limit = opts.limit ?? 10;
+		const tokens = query.toLowerCase().split(/\s+/).filter((t) => t.length >= 2 && !STOP_WORDS.has(t));
+		const raw = tokens.length > 0 ? this.fuse.search(tokens.map((t) => `'${t}`).join(" | ")) : [];
+		const filteredByTier = opts.tier ? raw.filter((r) => r.item.tier === opts.tier) : raw;
+		const ranked = filteredByTier.length > 0 ? filteredByTier.map((r) => toRanked(r.item, r.score, r.matches ?? [])) : this.fallback(opts.tier);
+		ranked.sort((a, b) => b.confidence - a.confidence || (b.item.priority ?? .5) - (a.item.priority ?? .5));
+		const present = new Set(ranked.map((r) => r.item.uri));
+		const seeAlso = [];
+		for (const r of ranked.slice(0, 3)) for (const rel of r.item.related) {
+			const uri = rel.startsWith("silk://") ? rel : `silk://${rel}`;
+			if (present.has(uri)) continue;
+			const neighbor = this.byUri.get(uri);
+			if (!neighbor) continue;
+			present.add(uri);
+			seeAlso.push({
+				item: neighbor,
+				confidence: 0,
+				matchedOn: ["related"]
+			});
+		}
+		return [...ranked, ...seeAlso].slice(0, limit).map(({ item, confidence, matchedOn }) => ({
+			uri: item.uri,
+			title: item.title,
+			summary: item.summary,
+			tags: item.tags,
+			tier: item.tier,
+			confidence: Number(confidence.toFixed(3)),
+			confidenceLabel: confidenceLabel(confidence),
+			matchedOn: [...new Set(matchedOn)].filter(Boolean),
+			related: item.related
+		}));
+	}
+	/** Never return empty: surface the top entries (by priority) as low-confidence. */
+	fallback(tier) {
+		return this.entries.filter((e) => tier ? e.tier === tier : true).slice().sort((a, b) => (b.priority ?? .5) - (a.priority ?? .5)).slice(0, 5).map((item) => ({
+			item,
+			confidence: 0,
+			matchedOn: []
+		}));
+	}
+};
+
+//#endregion
+export { DocIndex };

package/resources/index.js

@@ -0,0 +1,48 @@
+import { renderCatalogMarkdown } from "./catalog.js";
+import { readDocBody } from "./load.js";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/resources/index.ts
+const resourceName = (entry) => `silk_${entry.id.replace(/[^A-Za-z0-9]/g, "_")}`;
+const toSdkAnnotations = (e) => ({
+	audience: [...e.audience],
+	priority: e.priority,
+	...e.lastModified ? { lastModified: e.lastModified } : {}
+});
+function registerAllResources(server, deps) {
+	const { manifest, bodies, contentRoot } = deps;
+	server.registerResource("silk_catalog", "silk://catalog", {
+		title: "Silk resource catalog",
+		description: "Read this first. Lists every Silk resource grouped by tier with a 'load when' hint. Fetch a doc with resources/read <uri>; search by intent with silk_docs_search.",
+		mimeType: "text/markdown"
+	}, async (uri) => ({ contents: [{
+		uri: uri.href,
+		mimeType: "text/markdown",
+		text: renderCatalogMarkdown(manifest)
+	}] }));
+	const byUri = new Map(manifest.entries.map((e) => [e.uri, e]));
+	const readBody = (uri, relPath) => bodies ? bodies[uri] ?? "" : readDocBody(contentRoot, relPath);
+	server.registerResource("silk_doc", new ResourceTemplate("silk://{+path}", { list: async () => ({ resources: manifest.entries.filter((e) => e.status !== "deprecated").map((e) => ({
+		name: resourceName(e),
+		uri: e.uri,
+		title: e.title,
+		description: e.summary,
+		mimeType: "text/markdown",
+		annotations: toSdkAnnotations(e)
+	})) }) }), {
+		title: "Silk documentation resource",
+		mimeType: "text/markdown"
+	}, async (uri, variables) => {
+		const relPath = String(variables.path ?? "");
+		const entry = byUri.get(uri.href);
+		return { contents: [{
+			uri: uri.href,
+			mimeType: "text/markdown",
+			text: readBody(uri.href, relPath),
+			...entry ? { annotations: toSdkAnnotations(entry) } : {}
+		}] };
+	});
+}
+
+//#endregion
+export { registerAllResources };

package/resources/load.js

@@ -0,0 +1,38 @@
+import { resolveResourcePath } from "./paths.js";
+import { Manifest } from "./schema.js";
+import { Schema } from "effect";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/resources/load.ts
+/**
+* Resolve the content root across source/built layouts and load the manifest
+* + a doc body by relative path.
+*
+* @packageDocumentation
+*/
+/**
+* Locate the directory holding `manifest.json` + the content markdown. The
+* built bundle copies `public/` next to the emitted chunk (`<pkg>/public/content`);
+* the source layout keeps it under the package root (`packages/mcp/public/content`).
+* Probe both and fail loudly if neither has a manifest, so a broken build surfaces a
+* clear path list instead of an opaque ENOENT later in {@link loadManifest}.
+*/
+function resolveContentRoot() {
+	const here = dirname(fileURLToPath(import.meta.url));
+	const candidates = [join(here, "..", "public", "content"), join(here, "..", "..", "public", "content")];
+	for (const candidate of candidates) if (existsSync(join(candidate, "manifest.json"))) return candidate;
+	throw new Error(`[savvy-mcp] cannot locate public/content with a manifest.json (tried: ${candidates.join(", ")})`);
+}
+function loadManifest(contentRoot) {
+	const raw = JSON.parse(readFileSync(join(contentRoot, "manifest.json"), "utf8"));
+	return Schema.decodeUnknownSync(Manifest)(raw);
+}
+/** Read a doc body markdown by its relative path (the `{+path}` template var). */
+function readDocBody(contentRoot, relPath) {
+	return readFileSync(resolveResourcePath(contentRoot, relPath), "utf8");
+}
+
+//#endregion
+export { loadManifest, readDocBody, resolveContentRoot };

package/resources/paths.js

@@ -0,0 +1,23 @@
+import { isAbsolute, normalize, resolve, sep } from "node:path";
+
+//#region src/resources/paths.ts
+/**
+* Resolve a relative content path against the content root, appending `.md`
+* (or `index.md` for a trailing slash) and rejecting traversal. Operates on
+* the manifest-resolved relative path, never on URL components.
+*
+* @packageDocumentation
+*/
+function resolveResourcePath(root, relativePath) {
+	if (relativePath.includes("\0")) throw new Error("path contains null byte");
+	if (isAbsolute(relativePath)) throw new Error("absolute path not allowed");
+	const stripped = relativePath.replace(/^\/+/, "");
+	const withIndex = stripped === "" || stripped.endsWith("/") ? `${stripped}index` : stripped;
+	const resolved = resolve(root, normalize(withIndex.endsWith(".md") ? withIndex : `${withIndex}.md`));
+	const rootWithSep = root.endsWith(sep) ? root : `${root}${sep}`;
+	if (!resolved.startsWith(rootWithSep) && resolved !== root) throw new Error("path escapes content root");
+	return resolved;
+}
+
+//#endregion
+export { resolveResourcePath };

package/resources/query-log.js

@@ -0,0 +1,20 @@
+//#region src/resources/query-log.ts
+/** Build the structured stderr line for one search (pure; no I/O). */
+function formatQueryLogLine(query, results) {
+	const top = results.slice(0, 3);
+	const belowThreshold = results.length === 0 || results.every((r) => r.confidenceLabel === "low");
+	const payload = {
+		query,
+		topResults: top.map((r) => r.uri),
+		topConfidence: results[0]?.confidence ?? 0,
+		belowThreshold
+	};
+	return `[savvy-mcp] docs-search ${JSON.stringify(payload)}`;
+}
+/** Write a query log line to stderr. */
+const stderrQueryLogger = (line) => {
+	process.stderr.write(`${line}\n`);
+};
+
+//#endregion
+export { formatQueryLogLine, stderrQueryLogger };

package/resources/schema.js

@@ -0,0 +1,40 @@
+import { Schema } from "effect";
+
+//#region src/resources/schema.ts
+/**
+* Front-matter and manifest schemas for the Silk resource corpus.
+*
+* @packageDocumentation
+*/
+/** `id` = the stable URI suffix: tier-prefixed, slash-separated slug segments. */
+const ID_PATTERN = /^(standards|packages|guides)\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\/?$/;
+const Tier = Schema.Literal("standards", "packages", "guides");
+const Audience = Schema.Array(Schema.Literal("user", "assistant"));
+const Source = Schema.Literal("hand", "generated");
+const Status = Schema.Literal("draft", "stable", "deprecated");
+/** YAML front-matter on every content markdown file. */
+const DocFrontMatter = Schema.Struct({
+	id: Schema.String.pipe(Schema.pattern(ID_PATTERN)),
+	title: Schema.NonEmptyString,
+	summary: Schema.NonEmptyString,
+	tier: Tier,
+	source: Source,
+	status: Schema.optionalWith(Status, { default: () => "stable" }),
+	supersededBy: Schema.optional(Schema.String),
+	tags: Schema.Array(Schema.NonEmptyString),
+	audience: Schema.optionalWith(Audience, { default: () => ["assistant"] }),
+	priority: Schema.optionalWith(Schema.Number.pipe(Schema.between(0, 1)), { default: () => .5 }),
+	related: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] })
+});
+/** A manifest entry = decoded front-matter + the derived uri + lastModified. */
+const ManifestEntry = Schema.Struct({
+	...DocFrontMatter.fields,
+	uri: Schema.String,
+	lastModified: Schema.optional(Schema.String)
+});
+const Manifest = Schema.Struct({ entries: Schema.Array(ManifestEntry) });
+const decodeDocFrontMatter = Schema.decodeUnknown(DocFrontMatter);
+const decodeManifest = Schema.decodeUnknown(Manifest);
+
+//#endregion
+export { Manifest };

package/runtime.js

@@ -0,0 +1,38 @@
+import { ChangesetConfigReaderLive, SilkWorkspaceAnalyzerLive, TagStrategyLive, ToolDiscoveryLive, Turbo, VersioningStrategyLive } from "@savvy-web/silk-effects";
+import { Layer } from "effect";
+import { WorkspaceRootLive, WorkspacesLive } from "workspaces-effect";
+
+//#region src/runtime.ts
+/**
+* Composes the long-lived Effect runtime layer for the MCP server.
+*
+* `SilkRuntimeLive` provides {@link SilkWorkspaceAnalyzer} and {@link WorkspaceRoot}.
+* `WorkspaceRoot` lets the server resolve the workspace root by walking up from
+* its launch directory. The layer still requires `FileSystem` + `Path`; the host
+* (bin.ts) supplies them via `NodeContext.layer`.
+*
+* @packageDocumentation
+*/
+/**
+* The silk-effects dependency set fed to {@link SilkWorkspaceAnalyzerLive}.
+*
+* `WorkspacesLive` supplies the workspace trio plus `DependencyGraph` and
+* `TopologicalSorter` (all required by the analyzer). `VersioningStrategyLive`
+* is provided its own `ChangesetConfigReader` because `Layer.mergeAll` does not
+* cross-feed sibling layers.
+*/
+const DepsLive = Layer.mergeAll(WorkspacesLive, ChangesetConfigReaderLive, TagStrategyLive, VersioningStrategyLive.pipe(Layer.provide(ChangesetConfigReaderLive)));
+/**
+* The MCP runtime layer. Provides `SilkWorkspaceAnalyzer`, `WorkspaceRoot`, and
+* `Turbo.TurboInspector`; requires `CommandExecutor` + `FileSystem` + `Path`
+* from the host's platform layer (`NodeContext.layer` in bin.ts).
+*
+* `TurboInspectorLive` is fed its own `ToolDiscoveryLive`, whose
+* `PackageManagerDetector` + `WorkspaceRoot` requirements are satisfied by
+* {@link DepsLive}; the leftover `CommandExecutor` + `FileSystem` flow up to the
+* host platform layer.
+*/
+const SilkRuntimeLive = Layer.mergeAll(SilkWorkspaceAnalyzerLive, WorkspaceRootLive, Turbo.TurboInspectorLive.pipe(Layer.provide(ToolDiscoveryLive))).pipe(Layer.provide(DepsLive));
+
+//#endregion
+export { SilkRuntimeLive };

package/schema/effect-to-zod.js

@@ -0,0 +1,52 @@
+import { JSONSchema } from "effect";
+import { z } from "zod";
+
+//#region src/schema/effect-to-zod.ts
+/**
+* Convert an Effect `Schema.Schema<A, I, never>` to a zod schema:
+* `JSONSchema.make`, then inline every `#/$defs/*` `$ref`, then `z.fromJSONSchema`.
+*
+* @remarks
+* - Effect-only refinements (custom predicates, brands) erase during the
+*   round-trip; declare zod directly if boundary enforcement matters.
+* - The source schema must not use `Schema.suspend` (recursive `$ref`s would
+*   make `inlineAllRefs` non-terminating). MCP tool output schemas in this
+*   package are non-recursive projections by construction.
+* - The MCP SDK normalises `outputSchema` to an object; non-object results
+*   (e.g. a bare union) are wrapped in a permissive object so the SDK accepts
+*   them.
+*/
+const effectToZodSchema = (schema) => {
+	const inlined = inlineAllRefs(JSONSchema.make(schema));
+	const zodSchema = z.fromJSONSchema(inlined);
+	if (isObjectLike(zodSchema)) return zodSchema;
+	return z.object({}).catchall(z.unknown());
+};
+const isObjectLike = (schema) => schema instanceof z.ZodObject;
+const REF_PREFIX = "#/$defs/";
+/**
+* Replace every `$ref: "#/$defs/X"` node with the contents of `$defs.X`,
+* recursively, and drop the `$defs` table. Assumes acyclic refs.
+*/
+const inlineAllRefs = (root) => {
+	const defs = root.$defs ?? {};
+	const visit = (value) => {
+		if (Array.isArray(value)) return value.map(visit);
+		if (value === null || typeof value !== "object") return value;
+		const obj = value;
+		if (typeof obj.$ref === "string" && obj.$ref.startsWith(REF_PREFIX)) {
+			const target = defs[obj.$ref.slice(8)];
+			if (target !== void 0) return visit(target);
+		}
+		const out = {};
+		for (const [k, v] of Object.entries(obj)) {
+			if (k === "$defs") continue;
+			out[k] = visit(v);
+		}
+		return out;
+	};
+	return visit(root);
+};
+
+//#endregion
+export { effectToZodSchema };

package/server.js

@@ -0,0 +1,95 @@
+import { registerAllResources } from "./resources/index.js";
+import { stderrQueryLogger } from "./resources/query-log.js";
+import { effectToZodSchema } from "./schema/effect-to-zod.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";
+import { Schema } from "effect";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+//#region src/server.ts
+/**
+* Constructs the MCP server, registers tools and resources, and connects the
+* stdio transport.
+*
+* @packageDocumentation
+*/
+/** Wrap a markdown string + structured object in the dual-channel tool result. */
+const structuredResult = (text, structured) => ({
+	content: [{
+		type: "text",
+		text
+	}],
+	structuredContent: structured
+});
+/** Build the MCP server for the given context, registering tools + resources. */
+function buildServer(ctx) {
+	const server = new McpServer({
+		name: "savvy-mcp",
+		version: CURRENT_MCP_VERSION
+	});
+	server.registerTool("workspace_info", {
+		description: "Use when you need the Silk workspace layout: runtime, package manager, and a per-workspace summary (publishability, versioning, tag/release state). Prefer this over running shell commands to inspect the workspace. Returns markdown in content[] and a typed object in structuredContent.",
+		inputSchema: { cwd: z.optional(z.string()).describe("Workspace root to analyze. Defaults to the server's project dir.") },
+		outputSchema: effectToZodSchema(WorkspaceInfoResult)
+	}, async (args) => {
+		const root = args.cwd ?? ctx.cwd;
+		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: {
+			mode: z.enum([
+				"cache",
+				"graph",
+				"affected"
+			]).describe("Which inspection to run."),
+			task: z.optional(z.string()).describe("Task name (defaults to build:dev for cache/graph)."),
+			base: z.optional(z.string()).describe("Base git ref for affected mode."),
+			cwd: z.optional(z.string()).describe("Directory to resolve the workspace root from.")
+		},
+		outputSchema: effectToZodSchema(TurboInspectResult),
+		annotations: { readOnlyHint: true }
+	}, async (args) => {
+		const data = await ctx.runtime.runPromise(turboInspect(args, ctx.cwd));
+		return structuredResult(Schema.decodeSync(TurboInspectAsMarkdown)(data), data);
+	});
+	registerAllResources(server, {
+		manifest: ctx.manifest,
+		contentRoot: ctx.contentRoot
+	});
+	return server;
+}
+/** Build the server and connect it over stdio. */
+async function startMcpServer(ctx) {
+	const server = buildServer(ctx);
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+
+//#endregion
+export { startMcpServer };

package/tools/docs-search.js

@@ -0,0 +1,59 @@
+import { formatQueryLogLine } from "../resources/query-log.js";
+import { ParseResult, Schema } from "effect";
+
+//#region src/tools/docs-search.ts
+/**
+* The `silk_docs_search` MCP tool: a read-only Fuse-backed search over the
+* resource corpus. Takes a plain keyword/phrase query (no operator DSL),
+* returns ranked results with normalized higher-is-better confidence, and
+* never returns empty.
+*
+* @packageDocumentation
+*/
+const DocsSearchHit = Schema.Struct({
+	uri: Schema.String,
+	title: Schema.String,
+	summary: Schema.String,
+	tags: Schema.Array(Schema.String),
+	tier: Schema.Literal("standards", "packages", "guides"),
+	confidence: Schema.Number,
+	confidenceLabel: Schema.Literal("high", "medium", "low"),
+	matchedOn: Schema.Array(Schema.String),
+	related: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] })
+}).annotations({ identifier: "DocsSearchHit" });
+const DocsSearchResult = Schema.Struct({
+	query: Schema.String,
+	results: Schema.Array(DocsSearchHit)
+}).annotations({
+	identifier: "DocsSearchResult",
+	title: "silk_docs_search result",
+	description: "Ranked Silk documentation matches. Fetch a hit with resources/read <uri>."
+});
+const formatDocsSearchMarkdown = (data) => {
+	const lines = [`# silk_docs_search: ${data.query}`, ""];
+	if (data.results.length === 0) {
+		lines.push("No results. Read `silk://catalog` and select a doc by reasoning.");
+		return lines.join("\n");
+	}
+	if (data.results.every((r) => r.confidenceLabel === "low")) lines.push("_No high-confidence match — read `silk://catalog` and pick by reasoning._", "");
+	for (const r of data.results) lines.push(`- \`${r.uri}\` (${r.confidenceLabel}) — ${r.title}. ${r.summary}`);
+	lines.push("", "Fetch any hit with `resources/read <uri>`.");
+	return lines.join("\n");
+};
+const DocsSearchResultAsMarkdown = Schema.transformOrFail(DocsSearchResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatDocsSearchMarkdown(data)),
+	encode: (text, _opts, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "DocsSearchResultAsMarkdown is one-way."))
+});
+/** Run a search against the in-memory index (synchronous; no Effect runtime). */
+const runDocsSearch = (index, query, opts, logger) => {
+	const results = index.search(query, opts);
+	if (logger) logger(formatQueryLogLine(query, results));
+	return {
+		query,
+		results
+	};
+};
+
+//#endregion
+export { DocsSearchResult, DocsSearchResultAsMarkdown, runDocsSearch };

package/tools/turbo-inspect.js

@@ -0,0 +1,113 @@
+import { Turbo } from "@savvy-web/silk-effects";
+import { Effect, ParseResult, Schema } from "effect";
+import { WorkspaceRoot } from "workspaces-effect";
+
+//#region src/tools/turbo-inspect.ts
+/**
+* The `turbo_inspect` MCP tool: a discriminated-union result schema keyed by
+* `mode` (cache | graph | affected), each variant embedding the corresponding
+* `Turbo` result schema from silk-effects, plus a one-way markdown transform.
+*
+* @packageDocumentation
+*/
+/** Cache-diagnosis variant of the `turbo_inspect` result. */
+const TurboCacheResult = Schema.Struct({
+	mode: Schema.Literal("cache"),
+	result: Turbo.CacheDiagnosis
+}).annotations({ identifier: "TurboCacheResult" });
+/** Task-graph variant of the `turbo_inspect` result. */
+const TurboGraphResult = Schema.Struct({
+	mode: Schema.Literal("graph"),
+	result: Turbo.TaskGraphResult
+}).annotations({ identifier: "TurboGraphResult" });
+/** Affected-packages variant of the `turbo_inspect` result. */
+const TurboAffectedResult = Schema.Struct({
+	mode: Schema.Literal("affected"),
+	result: Turbo.AffectedResult
+}).annotations({ identifier: "TurboAffectedResult" });
+/** The `turbo_inspect` tool result — a discriminated union keyed by `mode`. */
+const TurboInspectResult = Schema.Union(TurboCacheResult, TurboGraphResult, TurboAffectedResult).annotations({
+	identifier: "TurboInspectResult",
+	title: "turbo_inspect result",
+	description: "Read-only Turborepo inspection grouped by mode (cache | graph | affected)."
+});
+/** Render the structured result as a markdown transcript. */
+const renderMarkdown = (data) => {
+	switch (data.mode) {
+		case "cache": {
+			const r = data.result;
+			const lines = [
+				`# turbo cache — ${r.task}`,
+				``,
+				`**${r.hits}/${r.totalTasks} cached**, ${r.misses} miss(es).`,
+				``,
+				`## Global hash`,
+				`- rootKey: \`${r.global.rootKey}\``,
+				`- global files: ${r.global.globalFileCount}`,
+				`- external deps hash: \`${r.global.externalDependenciesHash}\``,
+				`- internal deps hash: \`${r.global.internalDependenciesHash}\``,
+				`- global env: ${r.global.globalEnvVars.join(", ") || "(none)"}`
+			];
+			if (r.explanations.length > 0) {
+				lines.push(``, `## Misses`);
+				for (const m of r.explanations) lines.push(`### ${m.package} (\`${m.taskId}\`)`, `- hash: \`${m.hash}\``, `- input files: ${m.inputFileCount}`, `- hashed env: ${m.hashedEnvVars.join(", ") || "(none)"}`, `- external deps hash: \`${m.externalDependenciesHash}\``, `- depends on: ${m.dependsOn.join(", ") || "(none)"}`);
+			}
+			return lines.join("\n");
+		}
+		case "graph": {
+			const r = data.result;
+			return [
+				`# turbo task graph${r.task ? ` — ${r.task}` : ""}`,
+				``,
+				`${r.nodeCount} task node(s).`,
+				``,
+				`## Critical path`,
+				r.criticalPath.map((id, i) => `${i + 1}. \`${id}\``).join("\n") || "(empty)"
+			].join("\n");
+		}
+		case "affected": {
+			const r = data.result;
+			return [
+				`# turbo affected — base ${r.base}`,
+				``,
+				`## Changed packages`,
+				r.packages.map((p) => `- ${p}`).join("\n") || "(none)",
+				``,
+				`## Dependents`,
+				r.dependents.map((p) => `- ${p}`).join("\n") || "(none)"
+			].join("\n");
+		}
+	}
+};
+/** One-way transform: result to markdown. Encoding back is forbidden. */
+const TurboInspectAsMarkdown = Schema.transformOrFail(TurboInspectResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(renderMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "TurboInspectAsMarkdown is one-way: markdown cannot be parsed back."))
+});
+/**
+* Effect handler: resolve the workspace root by walking up from the requested
+* directory, then dispatch to the matching {@link Turbo.TurboInspector} method
+* keyed by `mode`. Mirrors `workspaceInfo`'s `WorkspaceRoot.find` resolution.
+*/
+const turboInspect = (args, fallbackCwd) => Effect.gen(function* () {
+	const root = yield* (yield* WorkspaceRoot).find(args.cwd ?? fallbackCwd);
+	const inspector = yield* Turbo.TurboInspector;
+	switch (args.mode) {
+		case "cache": return {
+			mode: "cache",
+			result: yield* inspector.diagnoseCache(args.task ?? "build:dev", root)
+		};
+		case "graph": return {
+			mode: "graph",
+			result: yield* inspector.taskGraph(root, args.task)
+		};
+		case "affected": return {
+			mode: "affected",
+			result: yield* inspector.affected(root, args.base)
+		};
+	}
+});
+
+//#endregion
+export { TurboInspectAsMarkdown, TurboInspectResult, turboInspect };

package/tools/workspace-info.js

@@ -0,0 +1,92 @@
+import { SilkWorkspaceAnalyzer } from "@savvy-web/silk-effects";
+import { Effect, ParseResult, Schema } from "effect";
+import { WorkspaceRoot } from "workspaces-effect";
+
+//#region src/tools/workspace-info.ts
+/** A flattened, non-recursive summary of one analyzed workspace. */
+const WorkspaceSummary = Schema.Struct({
+	name: Schema.String,
+	version: Schema.String,
+	path: Schema.String,
+	root: Schema.Boolean,
+	publishable: Schema.Boolean,
+	targets: Schema.Array(Schema.String).annotations({ description: "Publish registry URLs." }),
+	versioned: Schema.Boolean,
+	tagged: Schema.Boolean,
+	released: Schema.Boolean,
+	linked: Schema.Array(Schema.String).annotations({ description: "Names of linked workspaces." }),
+	fixed: Schema.Array(Schema.String).annotations({ description: "Names of fixed-group siblings." })
+}).annotations({ identifier: "WorkspaceSummary" });
+/** The `workspace_info` tool result — a projection of `WorkspaceAnalysis`. */
+const WorkspaceInfoResult = Schema.Struct({
+	root: Schema.String,
+	runtime: Schema.Literal("node", "bun"),
+	packageManager: Schema.Struct({
+		type: Schema.Literal("npm", "pnpm", "yarn", "bun"),
+		version: Schema.optional(Schema.String)
+	}),
+	workspaceCount: Schema.Number,
+	workspaces: Schema.Array(WorkspaceSummary)
+}).annotations({
+	identifier: "WorkspaceInfoResult",
+	title: "workspace_info result",
+	description: "Structured snapshot of the Silk workspace: runtime, package manager, and a per-workspace summary (publishability, versioning, tag/release state, linked/fixed relations)."
+});
+const toSummary = (w) => ({
+	name: w.name,
+	version: w.version.current,
+	path: w.path,
+	root: w.root,
+	publishable: w.publishable,
+	targets: w.targets.map((t) => t.registry),
+	versioned: w.versioned,
+	tagged: w.tagged,
+	released: w.released,
+	linked: w.linked.map((l) => l.name),
+	fixed: w.fixed.map((f) => f.name)
+});
+/** Project a full `WorkspaceAnalysis` to the flat tool result. */
+const toWorkspaceInfoResult = (analysis) => ({
+	root: analysis.root,
+	runtime: analysis.runtime,
+	packageManager: {
+		type: analysis.packageManager.type,
+		...analysis.packageManager.version !== void 0 ? { version: analysis.packageManager.version } : {}
+	},
+	workspaceCount: analysis.workspaces.length,
+	workspaces: analysis.workspaces.map(toSummary)
+});
+/** Render the structured result as a markdown transcript. */
+const formatWorkspaceInfoMarkdown = (data) => {
+	const pm = data.packageManager.version ? `${data.packageManager.type}@${data.packageManager.version}` : data.packageManager.type;
+	const lines = [
+		`# Workspace: ${data.root}`,
+		"",
+		`- runtime: ${data.runtime}`,
+		`- package manager: ${pm}`,
+		`- workspaces: ${data.workspaceCount}`,
+		"",
+		"| name | version | publishable | versioned | tagged | released |",
+		"| --- | --- | --- | --- | --- | --- |"
+	];
+	for (const w of data.workspaces) lines.push(`| ${w.name} | ${w.version} | ${w.publishable} | ${w.versioned} | ${w.tagged} | ${w.released} |`);
+	return lines.join("\n");
+};
+/** One-way transform: result to markdown. Encoding back is forbidden. */
+const WorkspaceInfoAsMarkdown = Schema.transformOrFail(WorkspaceInfoResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatWorkspaceInfoMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "WorkspaceInfoAsMarkdown is one-way: markdown cannot be parsed back."))
+});
+/**
+* Effect handler: resolve the workspace root by walking up from `base`, analyze
+* that root, and project to the tool result. Fails with `WorkspaceRootNotFoundError`
+* when `base` is not inside a workspace.
+*/
+const workspaceInfo = (base) => Effect.gen(function* () {
+	const root = yield* (yield* WorkspaceRoot).find(base);
+	return toWorkspaceInfoResult(yield* (yield* SilkWorkspaceAnalyzer).analyze(root));
+});
+
+//#endregion
+export { WorkspaceInfoAsMarkdown, WorkspaceInfoResult, workspaceInfo };

package/version.js

@@ -0,0 +1,12 @@
+//#region src/version.ts
+/**
+* The package version, replaced at build time. `0.0.0` in dev/test indicates
+* an unbuilt source run. Kept in its own module so both `server.ts` and the
+* `index.ts` barrel can import it without forming an import cycle.
+*
+* @packageDocumentation
+*/
+const CURRENT_MCP_VERSION = "0.0.0";
+
+//#endregion
+export { CURRENT_MCP_VERSION };