@savvy-web/mcp 2.7.5 → 3.0.0

package/README.md

@@ -32,13 +32,18 @@ The server speaks MCP over stdio and is meant to be spawned by an MCP client. A
 
 The single positional argument is the project directory; if omitted, the server resolves it from `SAVVY_MCP_PROJECT_DIR`, then `CLAUDE_PROJECT_DIR`, then the current working directory.
 
-To exercise it by hand during development, run it through the MCP inspector:
+To exercise it by hand, pipe JSON-RPC to it over stdio. Every response is one JSON line on stdout, logs go to stderr, and the server exits 0 when stdin closes. Keep stdin open until you have read the response you want — a request still in flight when stdin closes is dropped:
 
 ```bash
-npx @modelcontextprotocol/inspector savvy-mcp .
-# opens the inspector UI against a live savvy-mcp instance
+(printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"probe","version":"0.0.0"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'; sleep 2) | savvy-mcp .
+# line 1: the initialize result; line 2: the ten tools
 ```
 
+Any generic MCP client works the same way; nothing extra ships with the package for interactive use.
+
 ## 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.

package/bin/savvy-mcp.js

@@ -1,38 +1,14 @@
 #!/usr/bin/env node
-import { makeSilkRuntimeLayer } from "../runtime.js";
-import { startMcpServer } from "../server.js";
-import { Layer, ManagedRuntime } from "effect";
-import { NodeServices } from "@effect/platform-node";
+import { main } from "../main.js";
 
 //#region src/bin.ts
 /**
-* Binary entrypoint for the `savvy-mcp` server.
-*
-* Resolves the project working directory, builds the long-lived runtime
-* (root-bound to that directory), and starts the MCP server over stdio.
+* Binary entrypoint for the `savvy-mcp` server. Owns nothing itself — see
+* `main.ts` for the process bootstrap.
 *
 * @internal
 */
-/* v8 ignore start -- process bootstrap; covered by server.smoke.test.ts */
-function resolveProjectDir() {
-	const argv = process.argv[2];
-	return (argv !== void 0 && argv.trim().length > 0 && !(argv.startsWith("${") && argv.endsWith("}")) ? argv.trim() : void 0) ?? process.env.SAVVY_MCP_PROJECT_DIR ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-}
-async function main() {
-	const cwd = resolveProjectDir();
-	const appLayer = makeSilkRuntimeLayer(cwd).pipe(Layer.provide(NodeServices.layer));
-	const ctx = {
-		runtime: ManagedRuntime.make(appLayer),
-		cwd
-	};
-	process.stderr.write(`[savvy-mcp] starting in ${cwd}\n`);
-	await startMcpServer(ctx);
-}
-main().catch((err) => {
-	process.stderr.write(`savvy-mcp: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
-	process.exit(1);
-});
-/* v8 ignore stop */
+await main();
 
 //#endregion
 export {  };

package/errors.js

@@ -0,0 +1,181 @@
+import { Schema } from "effect";
+
+//#region src/errors.ts
+/**
+* The one typed failure union every savvy-mcp tool declares, plus the helpers
+* that keep each member's `message` self-contained on the wire.
+*
+* @remarks
+* Under `failureMode: "error"` (the only mode these tools use) a declared
+* typed failure reaches the client as
+* `{ isError: true, content: [{ type: "text", text: error.message }] }` and
+* `structuredContent` is never populated for it
+* (`.repos/effect/packages/effect/src/unstable/ai/McpServer.ts:1513-1517,1592-1607`
+* at rc.115 — see the header of `server.ts`). So a structured `remediation`
+* field is invisible to a real client: every member folds its hint into
+* `message` at construction through {@link composeRemediatedMessage}, and any
+* caller-supplied value echoed back passes through {@link truncateEchoed}.
+*
+* @packageDocumentation
+*/
+/** What a caller should do next about a failed tool call. @public */
+const Remediation = Schema.Struct({
+	hint: Schema.String,
+	suggestedTool: Schema.optionalKey(Schema.String)
+});
+/**
+* Compose a self-contained wire message from a raw cause message and its
+* remediation: the human message, then the hint, then `Try <suggestedTool>.`
+* when one is present. Every {@link McpToolError} member's `message` is built
+* through this at construction, because `message` is the only field a
+* declared failure delivers to the wire.
+*
+* @public
+*/
+const composeRemediatedMessage = (message, remediation) => remediation.suggestedTool === void 0 ? `${message} ${remediation.hint}` : `${message} ${remediation.hint} Try ${remediation.suggestedTool}.`;
+const ECHO_LIMIT = 200;
+/**
+* The limit for an ENGINE message echoed through {@link engineError} or an
+* argument-decode message: wider than {@link truncateEchoed}'s default because
+* the engine's own rendering (a git stderr, a decode path) is the diagnostic,
+* but still bounded — the kit embeds caller values (`base`, `task`, the
+* decoded value) in those messages untruncated.
+*/
+const ENGINE_ECHO_LIMIT = 2e3;
+/**
+* Truncate a caller-supplied value before it is echoed back inside an error's
+* `message`. Without this a pathological argument (a multi-megabyte `cwd`,
+* say) is echoed once in the response's `content[0].text` and once more in the
+* corresponding log line, burning an agent's context twice on what is usually
+* a typo.
+*
+* @public
+*/
+const truncateEchoed = (value, limit = ECHO_LIMIT) => value.length > limit ? `${value.slice(0, limit)}…` : value;
+/**
+* No workspace root was found walking up from the requested directory.
+* `message` is composed through {@link composeRemediatedMessage} at
+* construction, so it is what reaches the wire as `content[0].text`.
+*
+* @public
+*/
+var WorkspaceNotFound = class extends Schema.TaggedError()("WorkspaceNotFound", {
+	cwd: Schema.String,
+	message: Schema.String,
+	remediation: Remediation
+}) {};
+/**
+* A tool argument was structurally acceptable but semantically invalid — a
+* `repos_manage` action missing the field it needs, a `biome_check` path
+* outside the workspace, a `changeset_validate` directory that does not
+* exist. `message` is composed through {@link composeRemediatedMessage}.
+*
+* @public
+*/
+var InvalidArgument = class extends Schema.TaggedError()("InvalidArgument", {
+	argument: Schema.String,
+	message: Schema.String,
+	remediation: Remediation
+}) {};
+/**
+* A silk-effects engine program failed with one of its own typed errors
+* (`TurboError`, `GitError`, `ReposConfigError`, …). `source` carries that
+* error's `_tag`; `message` is its own rendering plus the remediation,
+* composed through {@link composeRemediatedMessage}.
+*
+* @public
+*/
+var EngineError = class extends Schema.TaggedError()("EngineError", {
+	source: Schema.String,
+	message: Schema.String,
+	remediation: Remediation
+}) {};
+/**
+* No Biome binary could be located. `message` is composed through
+* {@link composeRemediatedMessage}.
+*
+* @public
+*/
+var BiomeUnavailable = class extends Schema.TaggedError()("BiomeUnavailable", {
+	message: Schema.String,
+	remediation: Remediation
+}) {};
+/**
+* Biome itself failed (exit status above 1, a spawn error, or a timeout) —
+* distinct from "lint issues found", which is a successful result. `message`
+* is composed through {@link composeRemediatedMessage}.
+*
+* @public
+*/
+var BiomeFailed = class extends Schema.TaggedError()("BiomeFailed", {
+	exitCode: Schema.optionalKey(Schema.Number),
+	message: Schema.String,
+	remediation: Remediation
+}) {};
+/** The one failure schema every savvy-mcp tool declares. @public */
+const McpToolError = Schema.Union([
+	WorkspaceNotFound,
+	InvalidArgument,
+	EngineError,
+	BiomeUnavailable,
+	BiomeFailed
+]);
+/** The remediation every `WorkspaceNotFound` carries. */
+const WORKSPACE_REMEDIATION = {
+	hint: "Pass a cwd inside the project (a directory at or below a package.json with a workspace manifest), or omit cwd to use the server's project directory.",
+	suggestedTool: "workspace_info"
+};
+/**
+* Build a {@link WorkspaceNotFound} for the directory the caller asked about.
+* The kit's own `WorkspaceRootNotFoundError` message renders the search path
+* and probed markers; it is not echoed because it embeds the untruncated
+* caller value, which `cwd` already carries through {@link truncateEchoed}.
+*
+* @public
+*/
+const workspaceNotFound = (cwd) => new WorkspaceNotFound({
+	cwd,
+	message: composeRemediatedMessage(`No workspace root was found walking up from "${truncateEchoed(cwd)}".`, WORKSPACE_REMEDIATION),
+	remediation: WORKSPACE_REMEDIATION
+});
+/**
+* Build an {@link InvalidArgument}: `raw` is the human message (already
+* truncated by the caller where it echoes an argument).
+*
+* @public
+*/
+const invalidArgument = (argument, raw, remediation) => new InvalidArgument({
+	argument,
+	message: composeRemediatedMessage(raw, remediation),
+	remediation
+});
+/**
+* Build an {@link EngineError} from a silk-effects typed error. Every engine
+* error in this server renders itself through a `message` getter, so that
+* rendering is the raw message — passed through {@link truncateEchoed} at
+* {@link ENGINE_ECHO_LIMIT}, since the kit embeds caller values in it;
+* `source` keeps the tag for anything that inspects the typed error directly.
+*
+* @public
+*/
+const engineError = (cause, remediation) => new EngineError({
+	source: cause._tag,
+	message: composeRemediatedMessage(truncateEchoed(cause.message, ENGINE_ECHO_LIMIT), remediation),
+	remediation
+});
+/**
+* The shared mapping every handler applies to its engine error channel: the
+* kit's `WorkspaceRootNotFoundError` becomes {@link WorkspaceNotFound} for the
+* directory the caller requested; anything else becomes {@link EngineError}
+* with the tool's remediation.
+*
+* @param requestedCwd - the directory the caller asked about (already the
+*   fallback when the call omitted `cwd`)
+* @param remediation - the tool-specific hint for an engine failure
+*
+* @public
+*/
+const mapEngineError = (requestedCwd, remediation) => (cause) => cause._tag === "WorkspaceRootNotFoundError" ? workspaceNotFound(requestedCwd) : engineError(cause, remediation);
+
+//#endregion
+export { BiomeFailed, BiomeUnavailable, ENGINE_ECHO_LIMIT, EngineError, InvalidArgument, McpToolError, Remediation, WorkspaceNotFound, composeRemediatedMessage, engineError, invalidArgument, mapEngineError, truncateEchoed, workspaceNotFound };