ashlr-stack-mcp 0.2.2 → 0.3.1

package/README.md

@@ -1,10 +1,10 @@
 # ashlr-stack-mcp
 
-> MCP server for [Ashlr Stack](https://stack.ashlr.ai). Exposes 19 tools and up to 3 resources so Claude Code / Cursor / Windsurf / Codex can provision every third-party service in a project with one call.
+> MCP server for [Ashlr Stack](https://stack.ashlr.ai). Exposes 19 tools and up to 3 resources for inspecting and configuring supported services from MCP clients.
 
 ## What it does
 
-`stack` is a CLI. `ashlr-stack-mcp` is the same capabilities as MCP tools so your coding agent can drive Stack directly. Ask Claude "add Supabase to this project" and it calls `stack_add`, which walks OAuth, provisions the project, writes secrets through Phantom, and updates `.mcp.json` — all without leaving the chat.
+`stack` is a CLI. `ashlr-stack-mcp` is the same capabilities as MCP tools so your coding agent can drive Stack directly. An agent can request `stack_add` for a supported provider; authentication, resource setup and configuration changes depend on the adapter and authorization. Inspect the result and any changes.
 
 ## Install
 
@@ -26,7 +26,25 @@ bun add -g ashlr-stack-mcp @ashlr/stack
 npm i -g ashlr-stack-mcp @ashlr/stack
 ```
 
-Every tool runs the `stack` CLI, so install `@ashlr/stack` alongside this package (or set `STACK_BIN` to the CLI). Without it the server starts and lists its tools, but each call returns "Could not run the 'stack' CLI" with the fix. The npm 0.1.1 release runs on Bun, so Bun must be installed. In source 0.2.1 this package depends on `@ashlr/stack` and runs that dependency's `stack` bin; the order is `STACK_BIN`, then that bin, then `stack` on PATH.
+Every tool runs the `stack` CLI. The server resolves it in this order: the executable specified by `STACK_BIN`, the installed `@ashlr/stack` dependency's bin, then `stack` on PATH. If none is available, the server can still start and list tools, but calls fail with a CLI error. The npm CLI and MCP packages in this release declare Node.js >= 20 and use Node entrypoints. Check your installed package manifests; source development uses Bun.
+
+## Run from a local clone
+
+Install Bun and Node.js 20 or later, then install the workspace dependencies and build the CLI from the repository root:
+
+```bash
+bun install --frozen-lockfile
+(cd packages/cli && bun run build)
+```
+
+The source server runs with Bun; the CLI build provides the workspace dependency's `dist/index.js`. Start the server from the project you want it to inspect, replacing the paths with absolute paths on your machine:
+
+```bash
+cd /absolute/path/to/my-project
+bun run /absolute/path/to/ashlr-stack/packages/mcp/src/server.ts
+```
+
+The server speaks MCP over stdin and stdout, so connect it to an MCP client rather than expecting an interactive prompt. Keep stdout reserved for the protocol. Provider operations may need Phantom and provider credentials configured separately.
 
 ## Wire it into your agent
 
@@ -42,23 +60,24 @@ Drop this into your project's `.mcp.json` (Claude Code, Cursor and Windsurf read
 }
 ```
 
-If you installed from source (no global bin), point at the entry directly:
+For a local clone, after the installation and CLI build above, point the client at the source entry directly (with `bun` available on its PATH):
 
 ```json
 {
   "mcpServers": {
     "ashlr-stack": {
       "command": "bun",
-      "args": ["run", "/absolute/path/to/ashlr-stack/packages/mcp/src/server.ts"],
-      "env": { "STACK_BIN": "/absolute/path/to/ashlr-stack/packages/cli/src/index.ts" }
+      "args": ["run", "/absolute/path/to/ashlr-stack/packages/mcp/src/server.ts"]
     }
   }
 }
 ```
 
+The client chooses the server's working directory; the absolute entry path does not set it. Configure the client to start the server in your project if supported, or pass `cwd` to project-scoped tool calls as described below.
+
 ## Targeting a project (`cwd`)
 
-Every tool runs `stack` in the server's working directory unless you pass `cwd`. When your client starts the server outside the project (Claude Desktop, a global Cursor or Windsurf config), pass the project's absolute path:
+Every tool runs `stack` in the server's working directory by default. When your client starts the server outside the project (Claude Desktop, a global Cursor or Windsurf config), pass the project's absolute path to a project-scoped tool:
 
 ```json
 { "name": "stack_list", "arguments": { "json": true, "cwd": "/home/me/code/my-app" } }

package/dist/server.js

@@ -6508,7 +6508,7 @@ var require_dist = __commonJS(function(exports, module) {
 
 // src/server.ts
 import { spawn } from "child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { existsSync, readFileSync as readFileSync2 } from "fs";
 import { join } from "path";
 
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/core/core.js
@@ -14197,8 +14197,8 @@ var ServerResultSchema2 = union([
 ]);
 
 // src/cwd.ts
-import { realpathSync, statSync } from "node:fs";
-import { isAbsolute } from "node:path";
+import { lstatSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 
 // src/tools.ts
 function validateToolInput(tool, input) {
@@ -14274,13 +14274,97 @@ function planToolCall(tool, input) {
   const resolved = resolveToolCwd(tool, input);
   if (resolved.error !== undefined)
     return { ok: false, error: resolved.error };
+  const pathKey = tool.name === "stack_scan" ? "path" : tool.name === "stack_import" ? "from" : null;
+  const project = resolved.cwd ?? process.cwd();
+  if (pathKey) {
+    const value = input[pathKey] ?? (pathKey === "path" ? "." : ".env");
+    const error = validateProjectPath(tool, pathKey, String(value), project);
+    if (error)
+      return { ok: false, error };
+  }
+  if (tool.name === "stack_apply" && typeof input.recipe_id === "string") {
+    if (!/^[a-zA-Z0-9_-]+$/.test(input.recipe_id)) {
+      return {
+        ok: false,
+        error: `${tool.name}: argument "recipe_id" must be a filename stem using letters, numbers, underscores or hyphens.`
+      };
+    }
+    const error = validateProjectPath(tool, "recipe_id", `.stack/recipes/${input.recipe_id}.toml`, project);
+    if (error)
+      return { ok: false, error };
+  }
   return { ok: true, args: tool.cliArgs(input), cwd: resolved.cwd };
 }
+function canonicalPath(path) {
+  try {
+    return realpathSync(path);
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+    try {
+      if (lstatSync(path).isSymbolicLink())
+        throw error;
+    } catch (statError) {
+      if (statError === error || statError.code !== "ENOENT") {
+        throw statError;
+      }
+    }
+    const parent = dirname(path);
+    if (parent === path)
+      throw error;
+    return resolve(canonicalPath(parent), relative(parent, path));
+  }
+}
+function validateProjectPath(tool, key, value, project) {
+  try {
+    const root = realpathSync(project);
+    const target = canonicalPath(isAbsolute(value) ? value : `${root}${sep}${value}`);
+    const suffix = relative(root, target);
+    if (suffix !== ".." && !suffix.startsWith(`..${sep}`) && !isAbsolute(suffix))
+      return null;
+  } catch {
+    return `${tool.name}: argument "${key}" cannot be resolved; use a valid path inside the project directory.`;
+  }
+  return `${tool.name}: argument "${key}" must stay inside the project directory (got ${JSON.stringify(value)}); use a path relative to cwd within the project.`;
+}
+
+// src/output.ts
+function compactJsonOutput(stdout, args) {
+  const text = stdout.trim();
+  if (!args.includes("--json"))
+    return text;
+  try {
+    JSON.parse(text);
+  } catch {
+    return text;
+  }
+  let quoted = false;
+  let escaped = false;
+  let result = "";
+  for (const char of text) {
+    if (quoted) {
+      result += char;
+      if (escaped)
+        escaped = false;
+      else if (char === "\\")
+        escaped = true;
+      else if (char === '"')
+        quoted = false;
+    } else if (char === '"') {
+      quoted = true;
+      result += char;
+    } else if (!` 
+\r	`.includes(char)) {
+      result += char;
+    }
+  }
+  return result;
+}
 
 // src/stack-bin.ts
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync, statSync as statSync2 } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, resolve } from "node:path";
+import { dirname as dirname2, resolve as resolve2 } from "node:path";
 import { fileURLToPath } from "node:url";
 var CLI_PACKAGE_JSON = ["@ashlr", "stack", "package.json"].join("/");
 function resolveCliPackageJson() {
@@ -14296,8 +14380,8 @@ function cliBinFromPackageJson(pkgJsonPath) {
     const rel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.stack;
     if (!rel)
       return;
-    const abs = resolve(dirname(pkgJsonPath), rel);
-    return existsSync(abs) ? abs : undefined;
+    const abs = resolve2(dirname2(pkgJsonPath), rel);
+    return statSync2(abs).isFile() ? abs : undefined;
   } catch {
     return;
   }
@@ -14314,7 +14398,7 @@ function resolveStackCommand(env = process.env, findPackageJson = resolveCliPack
 }
 function readServerVersion(moduleUrl = import.meta.url) {
   try {
-    const pkgPath = resolve(dirname(fileURLToPath(moduleUrl)), "..", "package.json");
+    const pkgPath = resolve2(dirname2(fileURLToPath(moduleUrl)), "..", "package.json");
     const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
     if (pkg.name === "ashlr-stack-mcp" && pkg.version)
       return pkg.version;
@@ -14325,7 +14409,7 @@ function readServerVersion(moduleUrl = import.meta.url) {
 // src/tools.ts
 var CWD_INPUT = {
   type: "string",
-  description: "Absolute path of the project directory to run in (default: the MCP server's working directory). Must be an existing directory."
+  description: "Existing absolute project directory; defaults to server cwd."
 };
 var TOOLS = [
   {
@@ -14334,7 +14418,7 @@ var TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        template: { type: "string", description: "Optional starter template name." },
+        template: { type: "string", description: "Starter template name." },
         force: { type: "boolean", description: "Overwrite an existing .stack.toml." },
         cwd: CWD_INPUT
       }
@@ -14354,7 +14438,10 @@ var TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        from: { type: "string", description: "Path to the .env file (default: .env)." },
+        from: {
+          type: "string",
+          description: "Path to the .env file inside the project (default: .env)."
+        },
         dryRun: { type: "boolean", description: "Preview without writing." },
         cwd: CWD_INPUT
       }
@@ -14374,7 +14461,10 @@ var TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        path: { type: "string", description: "Directory to scan (default: cwd)." },
+        path: {
+          type: "string",
+          description: "Directory to scan inside the project (default: cwd)."
+        },
         confidence: {
           type: "string",
           description: "Minimum confidence: low, medium, or high (default: medium)."
@@ -14437,7 +14527,7 @@ var TOOLS = [
       properties: {
         json: {
           type: "boolean",
-          description: "Machine-readable JSON (schema ashlr.stack.list/v1)."
+          description: "JSON: ashlr.stack.list/v1."
         },
         cwd: CWD_INPUT
       }
@@ -14453,7 +14543,7 @@ var TOOLS = [
         service: { type: "string" },
         json: {
           type: "boolean",
-          description: "Machine-readable JSON (schema ashlr.stack.info/v1)."
+          description: "JSON: ashlr.stack.info/v1."
         },
         cwd: CWD_INPUT
       },
@@ -14474,7 +14564,7 @@ var TOOLS = [
       properties: {
         json: {
           type: "boolean",
-          description: "Machine-readable JSON (schema ashlr.stack.status/v1)."
+          description: "JSON: ashlr.stack.status/v1."
         },
         cwd: CWD_INPUT
       }
@@ -14489,7 +14579,7 @@ var TOOLS = [
       properties: {
         json: {
           type: "boolean",
-          description: "Machine-readable JSON (schema ashlr.stack.env/v1, names only)."
+          description: "JSON: ashlr.stack.env/v1; names only."
         },
         cwd: CWD_INPUT
       }
@@ -14504,7 +14594,7 @@ var TOOLS = [
       properties: {
         json: {
           type: "boolean",
-          description: "Machine-readable JSON (schema ashlr.stack.env-diff/v1, names and declaring service only); still an error result when any are missing."
+          description: "JSON: ashlr.stack.env-diff/v1; names and service only. Missing secrets remain an error."
         },
         cwd: CWD_INPUT
       }
@@ -14519,7 +14609,7 @@ var TOOLS = [
       properties: {
         fix: { type: "boolean", description: "Attempt auto-remediation." },
         all: { type: "boolean", description: "Run across every registered project." },
-        json: { type: "boolean", description: "Machine-readable JSON output." },
+        json: { type: "boolean", description: "JSON output." },
         cwd: CWD_INPUT
       }
     },
@@ -14559,7 +14649,7 @@ var TOOLS = [
         },
         json: {
           type: "boolean",
-          description: "Machine-readable JSON (schema ashlr.stack.providers/v1)."
+          description: "JSON: ashlr.stack.providers/v1."
         }
       }
     },
@@ -14577,7 +14667,7 @@ var TOOLS = [
       properties: {
         json: {
           type: "boolean",
-          description: "Machine-readable JSON (schema ashlr.stack.projects/v1)."
+          description: "JSON: ashlr.stack.projects/v1."
         }
       }
     },
@@ -14591,7 +14681,7 @@ var TOOLS = [
       properties: {
         json: {
           type: "boolean",
-          description: "Machine-readable JSON (schema ashlr.stack.deps/v1)."
+          description: "JSON: ashlr.stack.deps/v1."
         },
         cwd: CWD_INPUT
       }
@@ -14606,7 +14696,7 @@ var TOOLS = [
       properties: {
         json: {
           type: "boolean",
-          description: "Machine-readable JSON (schema ashlr.stack.templates/v1): each template with its services, providers and secret names."
+          description: "JSON: ashlr.stack.templates/v1; services, providers and secret names."
         }
       }
     },
@@ -14620,7 +14710,7 @@ var TOOLS = [
   },
   {
     name: "stack_recommend",
-    description: "Retrieve scored curated-provider matches and per-category ranking for a query. save:true writes a Recipe for a later stack_apply request. The CLI JSON payload is forwarded as text; this tool does not request LLM inference.",
+    description: "Rank curated providers by query, returning JSON as text without LLM inference. save:true writes a Recipe for stack_apply.",
     inputSchema: {
       type: "object",
       properties: {
@@ -14634,11 +14724,11 @@ var TOOLS = [
         },
         category: {
           type: "string",
-          description: "Optional filter to a source catalog category: Database, Deploy, Cloud, AI, Analytics, Observability, Errors, Payments, Code, Tickets, Email, Auth, FeatureFlags. Matched case-insensitively; an unknown category is an error."
+          description: "Category (case-insensitive): Database, Deploy, Cloud, AI, Analytics, Observability, Errors, Payments, Code, Tickets, Email, Auth, FeatureFlags. Unknown values error."
         },
         save: {
           type: "boolean",
-          description: "When true, also freeze the result to .stack/recipes/<id>.toml so you can run stack_apply. Returns the recipe id in the response."
+          description: "Save .stack/recipes/<id>.toml for stack_apply; returns recipe id."
         },
         cwd: CWD_INPUT
       },
@@ -14663,7 +14753,7 @@ var TOOLS = [
       properties: {
         recipe_id: {
           type: "string",
-          description: "Recipe id (filename stem in .stack/recipes/)."
+          description: "Recipe id (filename stem in .stack/recipes/, letters, numbers, underscores or hyphens)."
         },
         no_wire: {
           type: "boolean",
@@ -14726,7 +14816,7 @@ server.setRequestHandler(CallToolRequestSchema2, async (request) => {
   }
   const { args, cwd } = plan;
   const { stdout, stderr, code } = await runStack(args, cwd);
-  const body = stdout.trim() + (stderr.trim() ? `
+  const body = compactJsonOutput(stdout, args) + (stderr.trim() ? `
 
 [stderr]
 ${stderr.trim()}` : "");
@@ -14738,7 +14828,7 @@ ${stderr.trim()}` : "");
 server.setRequestHandler(ListResourcesRequestSchema2, async () => {
   const resources = [];
   const cwd = process.cwd();
-  if (existsSync2(join(cwd, ".stack.toml"))) {
+  if (existsSync(join(cwd, ".stack.toml"))) {
     resources.push({
       uri: "stack://current/.stack.toml",
       name: ".stack.toml (this project)",
@@ -14746,7 +14836,7 @@ server.setRequestHandler(ListResourcesRequestSchema2, async () => {
       mimeType: "application/toml"
     });
   }
-  if (existsSync2(join(cwd, ".stack.local.toml"))) {
+  if (existsSync(join(cwd, ".stack.local.toml"))) {
     resources.push({
       uri: "stack://current/.stack.local.toml",
       name: ".stack.local.toml (local instance)",
@@ -14754,7 +14844,7 @@ server.setRequestHandler(ListResourcesRequestSchema2, async () => {
       mimeType: "application/toml"
     });
   }
-  if (existsSync2(join(cwd, ".mcp.json"))) {
+  if (existsSync(join(cwd, ".mcp.json"))) {
     resources.push({
       uri: "stack://current/.mcp.json",
       name: ".mcp.json (MCP wiring)",
@@ -14775,7 +14865,7 @@ server.setRequestHandler(ReadResourceRequestSchema2, async (request) => {
     throw new Error(`Refusing to read: ${rel}`);
   }
   const path = join(process.cwd(), rel);
-  if (!existsSync2(path))
+  if (!existsSync(path))
     throw new Error(`${rel} does not exist in cwd.`);
   const text = readFileSync2(path, "utf-8");
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ashlr-stack-mcp",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "mcpName": "io.github.ashlrai/ashlr-stack",
   "description": "MCP server for Ashlr Stack. Exposes 19 tools and 3 resources so Claude Code / Cursor / Windsurf / Codex can provision every third-party service in a project with one call.",
   "license": "MIT",
@@ -51,7 +51,7 @@
     "typecheck": "bunx tsc --noEmit"
   },
   "dependencies": {
-    "@ashlr/stack": "^0.2.2",
+    "@ashlr/stack": "^0.3.1",
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "devDependencies": {