@savvy-web/mcp 0.4.2 → 1.0.0

package/README.md

@@ -44,6 +44,7 @@ npx @modelcontextprotocol/inspector savvy-mcp .
 - `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.
 - `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. It never writes a changeset. Backed by the same `silk-effects` changeset services the `savvy` CLI uses.
 
 ## Resources
 

package/index.d.ts

@@ -1,4 +1,4 @@
-import { SilkWorkspaceAnalyzer, Turbo } from "@savvy-web/silk-effects";
+import { Changesets, 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
@@ -84,7 +84,7 @@ declare class DocIndex {
 //#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 runtime: ManagedRuntime.ManagedRuntime<SilkWorkspaceAnalyzer | WorkspaceRoot | Turbo.TurboInspector | Changesets.BranchAnalyzer | Changesets.ConfigInspector, WorkspaceDiscoveryError>;
   readonly cwd: string;
   readonly docIndex: DocIndex;
   readonly manifest: Manifest;
@@ -93,16 +93,17 @@ interface McpContext {
 //#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).
+ * The MCP runtime layer. Provides `SilkWorkspaceAnalyzer`, `WorkspaceRoot`,
+ * `Turbo.TurboInspector`, `Changesets.BranchAnalyzer`, and
+ * `Changesets.ConfigInspector`; 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>;
+declare const SilkRuntimeLive: Layer.Layer<import("@savvy-web/silk-effects").SilkWorkspaceAnalyzer | import("workspaces-effect").WorkspaceRoot | Turbo.TurboInspector | Changesets.BranchAnalyzer | Changesets.ConfigInspector, 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/mcp",
-	"version": "0.4.2",
+	"version": "1.0.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",
@@ -23,17 +23,18 @@
 		".": {
 			"types": "./index.d.ts",
 			"import": "./index.js"
-		}
+		},
+		"./package.json": "./package.json"
 	},
 	"bin": {
 		"savvy-mcp": "bin/savvy-mcp.js"
 	},
 	"dependencies": {
 		"@effect/platform": "^0.96.1",
-		"@effect/platform-node": "^0.106.0",
+		"@effect/platform-node": "^0.107.0",
 		"@modelcontextprotocol/sdk": "^1.29.0",
-		"@savvy-web/silk-effects": "1.0.1",
-		"effect": "^3.21.2",
+		"@savvy-web/silk-effects": "1.1.0",
+		"effect": "^3.21.3",
 		"fuse.js": "^7.4.0",
 		"workspaces-effect": "^1.2.0",
 		"zod": "^4.4.3"

package/public/content/packages/cli/command-tree.md

@@ -29,9 +29,8 @@ savvy init        orchestrator → changeset · commit · lint init in one pass
 savvy check       orchestrator → runs all three checks
 savvy commit      init · check · hook(session-start · pre-commit-message ·
                   post-commit-verify · user-prompt-submit)
-savvy changeset   init · check · lint · transform · validate-file · version ·
-                  classify · analyze-branch · release-surface ·
-                  config(show · validate) · deps(detect · regen)
+savvy changeset   lint · check · transform · validate-file · version ·
+                  config(validate) · deps(detect · regen)
 savvy lint        init · check · fmt(package-json · pnpm-workspace · yaml)
 ```
 

package/runtime.js

@@ -1,4 +1,4 @@
-import { ChangesetConfigReaderLive, SilkWorkspaceAnalyzerLive, TagStrategyLive, ToolDiscoveryLive, Turbo, VersioningStrategyLive } from "@savvy-web/silk-effects";
+import { ChangesetConfigReaderLive, Changesets, SilkWorkspaceAnalyzerLive, TagStrategyLive, ToolDiscoveryLive, Turbo, VersioningStrategyLive } from "@savvy-web/silk-effects";
 import { Layer } from "effect";
 import { WorkspaceRootLive, WorkspacesLive } from "workspaces-effect";
 
@@ -22,17 +22,19 @@ import { WorkspaceRootLive, WorkspacesLive } from "workspaces-effect";
 * cross-feed sibling layers.
 */
 const DepsLive = Layer.mergeAll(WorkspacesLive, ChangesetConfigReaderLive, TagStrategyLive, VersioningStrategyLive.pipe(Layer.provide(ChangesetConfigReaderLive)));
+const InspectorAndAnalyzerLive = Changesets.BranchAnalyzerLive.pipe(Layer.provideMerge(Changesets.ConfigInspectorLive));
 /**
-* 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).
+* The MCP runtime layer. Provides `SilkWorkspaceAnalyzer`, `WorkspaceRoot`,
+* `Turbo.TurboInspector`, `Changesets.BranchAnalyzer`, and
+* `Changesets.ConfigInspector`; 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));
+const SilkRuntimeLive = Layer.mergeAll(SilkWorkspaceAnalyzerLive, WorkspaceRootLive, Turbo.TurboInspectorLive.pipe(Layer.provide(ToolDiscoveryLive)), InspectorAndAnalyzerLive).pipe(Layer.provide(DepsLive));
 
 //#endregion
 export { SilkRuntimeLive };

package/server.js

@@ -1,6 +1,9 @@
 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 { 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";
@@ -78,6 +81,50 @@ function buildServer(ctx) {
 		const data = await ctx.runtime.runPromise(turboInspect(args, ctx.cwd));
 		return structuredResult(Schema.decodeSync(TurboInspectAsMarkdown)(data), data);
 	});
+	server.registerTool("changeset_inspect", {
+		description: "Read-only changeset analysis for the changeset-manager workflow. mode=branch diffs the current branch against its base and classifies every changed file by owning package (with packagesAffected and the unmapped paths to ask the user about). mode=config surfaces the resolved .changeset/config.json (release surfaces, versionFiles, ignore list). mode=classify maps arbitrary repo-relative paths to their owning package. Prefer this over shelling out to the savvy CLI.",
+		inputSchema: {
+			mode: z.enum([
+				"branch",
+				"config",
+				"classify"
+			]).describe("Which inspection to run."),
+			base: z.optional(z.string()).describe("Override the base branch (branch mode only)."),
+			paths: z.optional(z.array(z.string())).describe("Paths to classify (classify mode only)."),
+			cwd: z.optional(z.string()).describe("Directory to resolve the workspace root from.")
+		},
+		outputSchema: effectToZodSchema(ChangesetInspectResult),
+		annotations: { readOnlyHint: true }
+	}, async (args) => {
+		const data = await ctx.runtime.runPromise(changesetInspect(args, ctx.cwd));
+		return structuredResult(Schema.decodeSync(ChangesetInspectAsMarkdown)(data), data);
+	});
+	server.registerTool("changeset_validate", {
+		description: "Read-only validation of changeset files against the section-aware rules. Pass dir (default .changeset). Returns typed diagnostics (file, rule, line, column, message) plus ok/errorCount in structuredContent. Prefer this over shelling out to savvy changeset lint.",
+		inputSchema: {
+			dir: z.optional(z.string()).describe("Changeset directory to validate (default .changeset)."),
+			cwd: z.optional(z.string()).describe("Directory to resolve the workspace root from.")
+		},
+		outputSchema: effectToZodSchema(ChangesetValidateResult),
+		annotations: { readOnlyHint: true }
+	}, async (args) => {
+		const data = await ctx.runtime.runPromise(changesetValidate(args, ctx.cwd));
+		return structuredResult(Schema.decodeSync(ChangesetValidateAsMarkdown)(data), data);
+	});
+	server.registerTool("biome_check", {
+		description: "Run Biome over a path and get structured diagnostics back. mode=check (default; lint + format + organize-imports) or mode=lint. Set write=true to apply safe fixes (--write), unsafe=true for unsafe fixes (--write --unsafe). Prefer this over shelling out to biome; the LSP already covers files you've edited. Returns markdown in content[] and a typed object in structuredContent. NOTE: with write/unsafe this tool MUTATES files (git-reversible).",
+		inputSchema: {
+			paths: z.optional(z.array(z.string())).describe("Paths to check. Defaults to the whole workspace."),
+			mode: z.optional(z.enum(["check", "lint"])).describe("check = lint+format+imports (default); lint = lint only."),
+			write: z.optional(z.boolean()).describe("Apply safe fixes (--write)."),
+			unsafe: z.optional(z.boolean()).describe("Apply unsafe fixes (--write --unsafe); implies write."),
+			cwd: z.optional(z.string()).describe("Directory to resolve the workspace root from.")
+		},
+		outputSchema: effectToZodSchema(BiomeCheckResult)
+	}, async (args) => {
+		const data = await runBiomeCheck(args, ctx.cwd);
+		return structuredResult(Schema.decodeSync(BiomeCheckAsMarkdown)(data), data);
+	});
 	registerAllResources(server, {
 		manifest: ctx.manifest,
 		contentRoot: ctx.contentRoot

package/tools/biome-check.js

@@ -0,0 +1,188 @@
+import { Lint } from "@savvy-web/silk-effects";
+import { ParseResult, Schema } from "effect";
+import { realpathSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { spawnSync } from "node:child_process";
+
+//#region src/tools/biome-check.ts
+/**
+* The `biome_check` MCP tool: a thin proxy that runs Biome over a path with the
+* gitlab reporter, parses it into a typed result, and can apply fixes. Unlike the
+* other savvy-mcp tools this one MUTATES the working tree when `write`/`unsafe`
+* is set — the first intentional exception to the read-only convention.
+*
+* @packageDocumentation
+*/
+/** Normalized diagnostic severity. */
+const BiomeSeverity = Schema.Literal("error", "warning", "info");
+/** A single normalized Biome diagnostic. */
+const BiomeDiagnostic = Schema.Struct({
+	file: Schema.String,
+	line: Schema.Number,
+	severity: BiomeSeverity,
+	rule: Schema.String,
+	message: Schema.String
+}).annotations({ identifier: "BiomeDiagnostic" });
+/** The `biome_check` tool result. */
+const BiomeCheckResult = Schema.Struct({
+	summary: Schema.Struct({
+		errors: Schema.Number,
+		warnings: Schema.Number
+	}),
+	diagnostics: Schema.Array(BiomeDiagnostic),
+	wrote: Schema.Boolean,
+	guidance: Schema.String
+}).annotations({
+	identifier: "BiomeCheckResult",
+	title: "biome_check result",
+	description: "Structured Biome diagnostics, with a flag for whether a --write pass ran."
+});
+/** Guardrail shown to the agent so it fixes code rather than silencing rules. */
+const GUIDANCE = "Fix the actual code. Do NOT disable rules or add config overrides to silence these.";
+/** Shape of a single diagnostic in Biome's `--reporter=gitlab` output. */
+const GitlabDiagnostic = Schema.Struct({
+	description: Schema.String,
+	check_name: Schema.String,
+	severity: Schema.Literal("info", "minor", "major", "critical", "blocker"),
+	location: Schema.Struct({
+		path: Schema.String,
+		lines: Schema.Struct({ begin: Schema.Number })
+	})
+});
+const GitlabArray = Schema.Array(GitlabDiagnostic);
+const decodeGitlab = Schema.decodeUnknownSync(GitlabArray);
+/** Map a gitlab severity onto our three-level scale. */
+const mapSeverity = (s) => s === "info" ? "info" : s === "minor" ? "warning" : "error";
+/**
+* Parse Biome `--reporter=gitlab` stdout into normalized diagnostics. Returns []
+* for empty, non-JSON, or shape-mismatched input (never throws).
+*/
+const parseBiomeGitlab = (stdout) => {
+	const trimmed = stdout.trim();
+	if (!trimmed) return [];
+	let raw;
+	try {
+		raw = JSON.parse(trimmed);
+	} catch {
+		return [];
+	}
+	let decoded;
+	try {
+		decoded = decodeGitlab(raw);
+	} catch {
+		return [];
+	}
+	return decoded.map((d) => ({
+		file: d.location.path,
+		line: d.location.lines.begin,
+		severity: mapSeverity(d.severity),
+		rule: d.check_name,
+		message: d.description
+	}));
+};
+/** Assemble the structured result from normalized diagnostics + the write flag. */
+const buildBiomeResult = (params) => {
+	return {
+		summary: {
+			errors: params.diagnostics.filter((d) => d.severity === "error").length,
+			warnings: params.diagnostics.filter((d) => d.severity === "warning").length
+		},
+		diagnostics: [...params.diagnostics],
+		wrote: params.wrote,
+		guidance: GUIDANCE
+	};
+};
+/** Render the structured result as markdown. */
+const renderMarkdown = (data) => {
+	if (data.diagnostics.length === 0) return `# biome — clean\n\n✅ No remaining diagnostics.${data.wrote ? " A --write pass ran; check `git diff` for what changed." : ""}`;
+	const lines = [`# biome — ${data.summary.errors} error(s), ${data.summary.warnings} warning(s)`, ``];
+	if (data.wrote) lines.push(`A --write pass ran; the diagnostics below remain unfixed.`, ``);
+	for (const d of data.diagnostics) lines.push(`- \`${d.file}:${d.line}\` **${d.severity}** ${d.rule} — ${d.message}`);
+	lines.push(``, `---`, data.guidance);
+	return lines.join("\n");
+};
+/** One-way transform: result to markdown. Encoding back is forbidden. */
+const BiomeCheckAsMarkdown = Schema.transformOrFail(BiomeCheckResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(renderMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "BiomeCheckAsMarkdown is one-way: markdown cannot be parsed back."))
+});
+/**
+* Run Biome and return structured diagnostics. When `write`/`unsafe` is set,
+* runs a fix pass first, then a read-only gitlab pass to report what remains.
+*
+* @remarks Resolves the Biome binary via {@link Lint.Biome.findBiome} (global
+* first, then the project's package manager). Throws if Biome is unavailable or
+* exits with status > 1 (Biome itself failed, vs. status 1 = lint issues found).
+*/
+const runBiomeCheck = async (args, fallbackCwd) => {
+	const mode = args.mode ?? "check";
+	const canonicalize = (p) => {
+		try {
+			return realpathSync(p);
+		} catch {
+			return resolve(p);
+		}
+	};
+	const root = canonicalize(fallbackCwd);
+	const within = (abs) => abs === root || abs.startsWith(`${root}${sep}`);
+	const cwd = canonicalize(args.cwd ?? fallbackCwd);
+	if (!within(cwd)) throw new Error(`cwd escapes the workspace root: ${args.cwd}`);
+	const paths = (args.paths && args.paths.length > 0 ? args.paths : ["."]).map((p) => {
+		const lexical = resolve(cwd, p);
+		if (!within(canonicalize(lexical))) throw new Error(`path escapes the workspace root: ${p}`);
+		return relative(cwd, lexical) || ".";
+	});
+	const doWrite = Boolean(args.write || args.unsafe);
+	const biomeCmd = Lint.Biome.findBiome();
+	if (!biomeCmd) throw new Error("Biome not found. Install @biomejs/biome globally (recommended) or as a devDependency.");
+	const parts = biomeCmd.split(" ");
+	const bin = parts[0];
+	const prefix = parts.slice(1);
+	const maxBuffer = 64 * 1024 * 1024;
+	const timeout = 12e4;
+	const killSignal = "SIGKILL";
+	let wrote = false;
+	if (doWrite) {
+		const fix = spawnSync(bin, [
+			...prefix,
+			mode,
+			"--write",
+			...args.unsafe ? ["--unsafe"] : [],
+			"--no-errors-on-unmatched",
+			...paths
+		], {
+			cwd,
+			encoding: "utf8",
+			maxBuffer,
+			timeout,
+			killSignal
+		});
+		if (fix.error) throw fix.error;
+		if ((fix.status ?? 0) > 1) throw new Error(`Biome --write failed (exit ${fix.status}): ${(fix.stderr ?? "").trim() || "unknown error"}`);
+		wrote = true;
+	}
+	const read = spawnSync(bin, [
+		...prefix,
+		mode,
+		"--reporter=gitlab",
+		"--error-on-warnings",
+		"--no-errors-on-unmatched",
+		...paths
+	], {
+		cwd,
+		encoding: "utf8",
+		maxBuffer,
+		timeout,
+		killSignal
+	});
+	if (read.error) throw read.error;
+	if ((read.status ?? 0) > 1) throw new Error(`Biome failed (exit ${read.status}): ${(read.stderr ?? "").trim() || "unknown error"}`);
+	return buildBiomeResult({
+		diagnostics: parseBiomeGitlab(read.stdout ?? ""),
+		wrote
+	});
+};
+
+//#endregion
+export { BiomeCheckAsMarkdown, BiomeCheckResult, runBiomeCheck };

package/tools/changeset-inspect.js

@@ -0,0 +1,126 @@
+import { Changesets } from "@savvy-web/silk-effects";
+import { Effect, ParseResult, Schema } from "effect";
+import { WorkspaceRoot } from "workspaces-effect";
+
+//#region src/tools/changeset-inspect.ts
+/**
+* The `changeset_inspect` MCP tool: a discriminated-union result keyed by `mode`
+* (branch | config), each variant embedding the corresponding resolved-output
+* schema from silk-effects' Changesets namespace, plus a one-way markdown
+* transform. Read-only.
+*
+* @packageDocumentation
+*/
+/** Branch-analysis variant. */
+const ChangesetBranchResult = Schema.Struct({
+	mode: Schema.Literal("branch"),
+	result: Changesets.BranchAnalysisSchema
+}).annotations({ identifier: "ChangesetBranchResult" });
+/** Config-inspection variant. */
+const ChangesetConfigResult = Schema.Struct({
+	mode: Schema.Literal("config"),
+	result: Changesets.InspectedConfigSchema
+}).annotations({ identifier: "ChangesetConfigResult" });
+/** Classify variant — arbitrary paths to owning package. */
+const ChangesetClassifyResult = Schema.Struct({
+	mode: Schema.Literal("classify"),
+	result: Schema.Array(Changesets.ClassificationSchema)
+}).annotations({ identifier: "ChangesetClassifyResult" });
+/** The `changeset_inspect` tool result — a discriminated union keyed by `mode`. */
+const ChangesetInspectResult = Schema.Union(ChangesetBranchResult, ChangesetConfigResult, ChangesetClassifyResult).annotations({
+	identifier: "ChangesetInspectResult",
+	title: "changeset_inspect result",
+	description: "Read-only changeset analysis grouped by mode (branch | config | classify)."
+});
+/**
+* Render a repo/config-derived value as an inert markdown code span. Escapes
+* backticks and backslashes so a crafted filename or package name cannot inject
+* markdown structure into the transcript that an agent reads.
+*/
+const mdInline = (value) => `\`${value.replace(/[`\\]/g, "\\$&")}\``;
+/** Render the structured result as a markdown transcript. */
+const renderMarkdown = (data) => {
+	switch (data.mode) {
+		case "branch": {
+			const r = data.result;
+			const lines = [
+				`# changeset branch analysis — base ${mdInline(r.baseBranch)}`,
+				``,
+				`merge base: ${mdInline(r.mergeBaseSha)}`,
+				``,
+				`## Packages affected`,
+				r.packagesAffected.map((p) => `- ${mdInline(p)}`).join("\n") || "(none)",
+				``,
+				`## Files`
+			];
+			for (const f of r.files) {
+				const owner = f.package ? mdInline(f.package) : mdInline("<unmapped>");
+				lines.push(`- ${mdInline(f.status)}  ${mdInline(f.path)}  ->  ${owner}`);
+			}
+			if (r.unmappedFiles.length > 0) {
+				lines.push(``, `## Unmapped (ask the user)`);
+				for (const p of r.unmappedFiles) lines.push(`- ${mdInline(p)}`);
+			}
+			return lines.join("\n");
+		}
+		case "config": {
+			const r = data.result;
+			const lines = [
+				`# changeset config — ${mdInline(r.configPath)}`,
+				``,
+				`base branch: ${mdInline(r.baseBranch)}`,
+				`access: ${r.access}`,
+				`changelog: ${r.changelog ? mdInline(r.changelog) : "(none)"}`,
+				`ignored: ${r.ignore.map(mdInline).join(", ") || "(none)"}`,
+				``,
+				`## Packages`
+			];
+			for (const p of r.packages) {
+				lines.push(`### ${mdInline(p.name)} (${mdInline(p.version)})`, `- dir: ${mdInline(p.workspaceDir)}`);
+				if (p.additionalScopes.length > 0) lines.push(`- additionalScopes: ${p.additionalScopes.map(mdInline).join(", ")}`);
+				if (p.versionFiles.length > 0) lines.push(`- versionFiles: ${p.versionFiles.map((v) => mdInline(v.glob)).join(", ")}`);
+			}
+			if (r.packages.length === 0) lines.push("(none resolved)");
+			return lines.join("\n");
+		}
+		case "classify": {
+			const lines = [`# changeset classify`, ``];
+			for (const c of data.result) {
+				const owner = c.package ? mdInline(c.package) : mdInline("<unmapped>");
+				lines.push(`- ${mdInline(c.path)}  ->  ${owner}`);
+			}
+			if (data.result.length === 0) lines.push("(no paths)");
+			return lines.join("\n");
+		}
+	}
+};
+/** One-way transform: result to markdown. Encoding back is forbidden. */
+const ChangesetInspectAsMarkdown = Schema.transformOrFail(ChangesetInspectResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(renderMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "ChangesetInspectAsMarkdown is one-way: markdown cannot be parsed back."))
+});
+/**
+* Effect handler: resolve the workspace root, then dispatch to the matching
+* Changesets service keyed by `mode`. Mirrors `turboInspect`.
+*/
+const changesetInspect = (args, fallbackCwd) => Effect.gen(function* () {
+	const root = yield* (yield* WorkspaceRoot).find(args.cwd ?? fallbackCwd);
+	switch (args.mode) {
+		case "branch": return {
+			mode: "branch",
+			result: yield* (yield* Changesets.BranchAnalyzer).analyzeBranch(root, args.base ? { baseBranch: args.base } : void 0)
+		};
+		case "config": return {
+			mode: "config",
+			result: yield* (yield* Changesets.ConfigInspector).inspect(root)
+		};
+		case "classify": return {
+			mode: "classify",
+			result: yield* (yield* Changesets.ConfigInspector).classify(root, args.paths ?? [])
+		};
+	}
+});
+
+//#endregion
+export { ChangesetInspectAsMarkdown, ChangesetInspectResult, changesetInspect };

package/tools/changeset-validate.js

@@ -0,0 +1,84 @@
+import { Changesets } from "@savvy-web/silk-effects";
+import { Data, Effect, ParseResult, Schema } from "effect";
+import { WorkspaceRoot } from "workspaces-effect";
+import { resolve } from "node:path";
+
+//#region src/tools/changeset-validate.ts
+/**
+* The `changeset_validate` MCP tool: structured changeset-file validation over
+* silk-effects' pure ChangesetLinter, returning typed diagnostics plus a
+* pass/fail summary. Read-only.
+*
+* @packageDocumentation
+*/
+/** A thrown failure from the pure {@link Changesets.ChangesetLinter.validate} (e.g. a missing directory). */
+var ChangesetValidateError = class extends Data.TaggedError("ChangesetValidateError") {};
+/** A single changeset lint diagnostic. Mirrors silk-effects' `LintMessage`. */
+const ChangesetLintMessage = Schema.Struct({
+	file: Schema.String,
+	rule: Schema.String,
+	line: Schema.Number,
+	column: Schema.Number,
+	message: Schema.String
+}).annotations({ identifier: "ChangesetLintMessage" });
+/** The `changeset_validate` tool result. */
+const ChangesetValidateResult = Schema.Struct({
+	dir: Schema.String,
+	ok: Schema.Boolean,
+	errorCount: Schema.Number,
+	messages: Schema.Array(ChangesetLintMessage)
+}).annotations({
+	identifier: "ChangesetValidateResult",
+	title: "changeset_validate result",
+	description: "Read-only validation of changeset files against the section-aware rules."
+});
+/**
+* Render a repo/lint-derived value as an inert markdown code span. Escapes
+* backticks and backslashes so a crafted filename or message cannot inject
+* markdown structure into the transcript that an agent reads.
+*/
+const mdInline = (value) => `\`${value.replace(/[`\\]/g, "\\$&")}\``;
+/** Render the structured result as a markdown transcript. */
+const renderMarkdown = (data) => {
+	if (data.ok) return `# changeset validate — ${mdInline(data.dir)}\n\nNo changeset issues found.`;
+	const lines = [
+		`# changeset validate — ${mdInline(data.dir)}`,
+		``,
+		`${data.errorCount} issue(s):`,
+		``
+	];
+	for (const m of data.messages) lines.push(`- ${mdInline(`${m.file}:${m.line}:${m.column}`)} ${mdInline(m.rule)} — ${m.message}`);
+	return lines.join("\n");
+};
+/** One-way transform: result to markdown. Encoding back is forbidden. */
+const ChangesetValidateAsMarkdown = Schema.transformOrFail(ChangesetValidateResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(renderMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "ChangesetValidateAsMarkdown is one-way: markdown cannot be parsed back."))
+});
+/**
+* Effect handler: resolve the workspace root, then validate the changeset
+* directory via the pure {@link Changesets.ChangesetLinter.validate}. The
+* synchronous call is wrapped in {@link Effect.try} so a thrown error (e.g. a
+* missing directory) surfaces as a typed {@link ChangesetValidateError} rather
+* than escaping as a defect.
+*/
+const changesetValidate = (args, fallbackCwd) => Effect.gen(function* () {
+	const dir = resolve(yield* (yield* WorkspaceRoot).find(args.cwd ?? fallbackCwd), args.dir ?? ".changeset");
+	const messages = yield* Effect.try({
+		try: () => Changesets.ChangesetLinter.validate(dir),
+		catch: (cause) => new ChangesetValidateError({
+			dir,
+			cause
+		})
+	});
+	return {
+		dir,
+		ok: messages.length === 0,
+		errorCount: messages.length,
+		messages
+	};
+});
+
+//#endregion
+export { ChangesetValidateAsMarkdown, ChangesetValidateResult, changesetValidate };