bun-workspaces 1.6.0 → 1.8.0

package/README.md

@@ -6,20 +6,13 @@
 
 ### [**See Full Documentation Here**: _https://bunworkspaces.com_](https://bunworkspaces.com)
 
-**Big Recent Updates!**
-
-- Version 1 is here after the initial alpha! 🍔🍔👁️🍔🍔
-- You can demo the CLI [directly in the browser](https://bunworkspaces.com/web-cli)
-- There's now [an official blog](https://bunworkspaces.com/blog/bun-workspaces-v1) to cover noteworthy releases and more!
-- There's now a provided [MCP server](https://bunworkspaces.com/ai/mcp) for your AI tooling to understand how to use `bun-workspaces`!
-<hr/>
-
 This is a CLI and TypeScript API to enhance your monorepo development with Bun's [native workspaces](https://bun.sh/docs/install/workspaces) feature for nested JavaScript/TypeScript packages.
 
 - Works right away, with no boilerplate required 🍔🍴
 - Get metadata about your monorepo 🤖
 - Orchestrate your workspaces' `package.json` scripts 📋
 - Run inline [Bun Shell](https://bun.com/docs/runtime/shell) scripts in workspaces 🐚
+  Use the [MCP server](https://bunworkspaces.com/ai/mcp) for your AI tooling to learn how to use `bun-workspaces` and add project metadata to context! 🛠️
 
 This is a tool to help manage a Bun monorepo, offering features beyond what [Bun's --filter feature](https://bun.com/docs/pm/filter) can do. It can be used to get a variety of metadata about your project and run scripts across your workspaces with advanced control.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-workspaces",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "A monorepo management tool for Bun, with a CLI and API to enhance Bun's native workspaces.",
   "license": "MIT",
   "exports": {
@@ -15,6 +15,10 @@
     "./config": {
       "types": "./src/config/public.d.ts",
       "default": "./src/config/public.mjs"
+    },
+    "./script": {
+      "types": "./src/runScript/public.d.ts",
+      "default": "./src/runScript/public.mjs"
     }
   },
   "types": "./src/index.d.ts",

package/src/2392.mjs

@@ -138,7 +138,7 @@ const CLI_COMMANDS_CONFIG = {
   },
   mcpServer: {
     command: "mcp-server",
-    isGlobal: false,
+    isGlobal: true,
     aliases: [],
     description:
       "Start the bun-workspaces MCP (Model Context Protocol) server over stdio",

package/src/{1108.mjs → 3725.mjs}

@@ -1,4 +1,4 @@
-const SCRIPT_RUNTIME_METADATA_CONFIG = {
+const WORKSPACE_SCRIPT_METADATA_CONFIG = {
   projectPath: {
     inlineName: "<projectPath>",
     envVarName: "BW_PROJECT_PATH",
@@ -24,7 +24,14 @@ const SCRIPT_RUNTIME_METADATA_CONFIG = {
     envVarName: "BW_WORKSPACE_NAME",
   },
 };
-const getScriptRuntimeMetadataConfig = (key) =>
-  SCRIPT_RUNTIME_METADATA_CONFIG[key];
+const validateWorkspaceScriptMetadataKey = (key) => {
+  if (!(key in WORKSPACE_SCRIPT_METADATA_CONFIG)) {
+    throw new Error(`Invalid workspace script metadata key: ${key}`);
+  }
+};
+const getWorkspaceScriptMetadataConfig = (key) => {
+  validateWorkspaceScriptMetadataKey(key);
+  return WORKSPACE_SCRIPT_METADATA_CONFIG[key];
+};
 
-export { getScriptRuntimeMetadataConfig };
+export { getWorkspaceScriptMetadataConfig };

package/src/ai/mcp/bwMcpServer.mjs

@@ -1,336 +1,46 @@
 import package_0 from "../../../package.json";
 import { createMcpServer } from "./core/index.mjs";
 import { registerBwResources } from "./resources.mjs";
+import { setServerWorkingDirectory } from "./serverState.mjs";
 import { registerBwTools } from "./tools.mjs";
 
-const CLI_QUICKSTART = `
-# You can add this to .bashrc, .zshrc, or similar.
-# You can also invoke "bw" in your root package.json scripts.
-alias bw="bunx bun-workspaces"
-
-# List all workspaces in your project
-bw list-workspaces
-
-# ls is an alias for list-workspaces
-bw ls --json --pretty # Output as formatted JSON
-
-# Get info about a workspace
-bw workspace-info my-workspace
-bw info my-workspace --json --pretty # info is alias for workspace-info
-
-# Get info about a script, such as the workspaces that have it
-bw script-info my-script
-
-# Run the lint script for all workspaces
-# that have it in their package.json "scripts" field
-bw run-script lint
-
-# run is an alias for run-script
-bw run lint my-workspace # Run for a single workspace
-bw run lint my-workspace-a my-workspace-b # Run for multiple workspaces
-bw run lint my-alias-a my-alias-b # Run by alias (set by optional config)
-
-# A workspace's script will wait until any workspaces it depends on have completed
-# Similar to Bun's --filter behavior
-bw run lint --dep-order
-
-# Continue running scripts even if a dependency fails
-bw run lint --dep-order --ignore-dep-failure
-
-bw run lint "my-workspace-*" # Run for matching workspace names
-bw run lint "alias:my-alias-*" "path:my-glob/**/*" "tag:my-tag" # Use matching specifiers
-bw run lint "*" "not:path:my-path/*" # Run for all workspaces not in my-path/
-
-bw run lint --args="--my-appended-args" # Add args to each script call
-bw run lint --args="--my-arg=<workspaceName>" # Use the workspace name in args
-
-bw run "bun build" --inline # Run an inline command via the Bun shell
-
-# Scripts run in parallel by default
-bw run lint --parallel=false # Run in series
-bw run lint --parallel=2 # Run in parallel with a max of 2 concurrent scripts
-bw run lint --parallel=auto # Default, based on number of available logical CPUs
-bw run lint --parallel=50% # Run in parallel with a max of 50% of the "auto" limit
-
-# Use the grouped output style (default when on a TTY)
-bw run my-script --output-style=grouped
-
-# Set the max preview lines for script output in grouped output style
-bw run my-script --output-style=grouped --grouped-lines=auto
-bw run my-script --output-style=grouped --grouped-lines=10
-
-# Use simple script output with workspace prefixes (default when not on a TTY)
-bw run my-script --output-style=prefixed
-
-# Use the plain output style (no workspace prefixes)
-bw run my-script --output-style=plain
-
-# Silence all output of the run command
-bw --log-level=silent run my-script --output-style=none
-
-# Show usage (you can pass --help to any command)
-bw help
-bw --help
-
-# Show version
-bw --version
-
-# Pass --cwd to any command
-bw --cwd=/path/to/your/project ls
-bw --cwd=/path/to/your/project run my-script
-
-# Pass --log-level to any command (debug, info, warn, error, or silent)
-bw --log-level=debug ls
-`.trim();
-const INLINE_SCRIPT_EXAMPLE =
-  /* unused pure expression or super */ null &&
-  `
-# Run an inline command from the workspace directory
-bw run "bun run build" --inline
-`.trim();
-
-const RUN_WORKSPACE_SCRIPT_EXAMPLE = `
-const { output, exit } = project.runWorkspaceScript({
-  workspaceNameOrAlias: "my-workspace",
-  script: "my-script",
-
-  // Optional. Arguments to add to the command
-  // Can be a string or an array of strings
-  // If string, the argv will be parsed POSIX-style
-  args: ["--my", "--appended", "--args"],
-
-  // Optional. Whether to ignore all output from the script.
-  // This saves memory when you don't need script output.
-  ignoreOutput: false,
-});
-
-// Get a stream of the script subprocess's output
-for await (const { chunk, metadata } of output.text()) {
-  // console.log(chunk); // The output chunk's content (string)
-  // console.log(metadata.streamName); // The output stream, "stdout" or "stderr"
-  // console.log(metadata.workspace); // The target Workspace
-}
-
-// Get data about the script execution after it exits
-const exitResult = await exit;
-
-// exitResult.exitCode // The exit code (number)
-// exitResult.signal // The exit signal (string), or null
-// exitResult.success // true if exit code was 0
-// exitResult.startTimeISO // Start time (string)
-// exitResult.endTimeISO // End time (string)
-// exitResult.durationMs // Duration in milliseconds (number)
-// exitResult.metadata.workspace // The target workspace (Workspace)
-
-`.trim();
-const RUN_SCRIPT_ACROSS_WORKSPACES_EXAMPLE = `
-
-const { output, summary } = project.runScriptAcrossWorkspaces({
-  // Optional. This will run in all matching workspaces that have my-script
-  // Accepts same values as the CLI run-script command's workspace patterns
-  // When not provided, all workspaces that have the script will be used.
-  workspacePatterns: ["my-workspace", "my-name-pattern-*"],
-
-  // Required. The package.json "scripts" field name to run
-  script: "my-script",
-
-  // Optional. Arguments to add to the command (same as for runWorkspaceScript)
-  args: ["--my", "--appended", "--args"],
-
-  // Optional. Whether to run the scripts in parallel (default: true)
-  parallel: true,
-
-  // Optional. When true, a workspace's script will wait
-  // until any workspaces it depends on have completed
-  dependencyOrder: false,
-
-  // Optional. When true and dependencyOrder is true,
-  // continue running scripts even if a dependency fails
-  ignoreDependencyFailure: false,
-
-  // Optional. Whether to ignore all output from the scripts.
-  // This saves memory when you don't need script output.
-  ignoreOutput: false,
-
-  // Optional, callback when script starts, skips, or exits
-  onScriptEvent: (event, { workspace, exitResult }) => {
-    // event: "start", "skip", "exit"
-  }
-});
-
-// Get a stream of script output
-for await (const { chunk, metadata } of output.text()) {
-  // console.log(chunk); // the output chunk's content (string)
-  // console.log(metadata.streamName); // "stdout" or "stderr"
-  // console.log(metadata.workspace); // the Workspace that the output came from
-}
-
-// Get final summary data and script exit details after all scripts have completed
-const summaryResult = await summary;
-
-// summaryResult.totalCount // Total number of scripts
-// summaryResult.allSuccess // true if all scripts succeeded
-// summaryResult.successCount // Number of scripts that succeeded
-// summaryResult.failureCount // Number of scripts that failed
-// summaryResult.startTimeISO // Start time (string)
-// summaryResult.endTimeISO // End time (string)
-// summaryResult.durationMs // Total duration in milliseconds (number)
-
-// The exit details of each workspace script
-for (const exitResult of summaryResult.scriptResults) {
-  // exitResult.exitCode // The exit code (number)
-  // exitResult.signal // The exit signal (string), or null
-  // exitResult.success // true if exit code was 0
-  // exitResult.startTimeISO // Start time (ISO string)
-  // exitResult.endTimeISO // End time (ISO string)
-  // exitResult.durationMs // Duration in milliseconds (number)
-  // exitResult.metadata.workspace // The target workspace (Workspace)
-}
-`.trim();
-const API_QUICKSTART = `
-import { createFileSystemProject } from "bun-workspaces";
-
-// A Project contains the core functionality of bun-workspaces.
-// Below defaults to process.cwd() for the project root directory
-// Pass { rootDirectory: "path/to/your/project" } to use a different root directory
-const project = createFileSystemProject();
-
-// A Workspace that matches the name or alias "my-workspace"
-const myWorkspace = project.findWorkspaceByNameOrAlias("my-workspace");
-
-// Array of workspaces whose names match the wildcard pattern
-const wildcardWorkspaces = project.findWorkspacesByPattern("my-workspace-*");
-
-// Array of workspaces that have "my-script" in their package.json "scripts"
-const workspacesWithScript = project.listWorkspacesWithScript("my-script");
-
-// Run a script in a workspace
-const runSingleScript = async () => {
-  ${RUN_WORKSPACE_SCRIPT_EXAMPLE.split("\n").join("\n  ")}
-}
-
-// Run a script in all workspaces that have it in their package.json "scripts" field
-const runManyScripts = async () => {
-  ${RUN_SCRIPT_ACROSS_WORKSPACES_EXAMPLE.split("\n").join("\n  ")}
-}
-`.trim();
-
-const ROOT_CONFIG_QUICKSTART = `
-// bw.root.ts — place in your project root directory
-// Also supported: bw.root.js, bw.root.json, bw.root.jsonc, or a "bw" key in package.json
-import { defineRootConfig } from "bun-workspaces/config";
-
-export default defineRootConfig({
-  defaults: {
-    // default value for --parallel option
-    parallelMax: 4,
-    // default value for --shell option
-    shell: "system",
-    // default value for global --include-root-workspace option
-    includeRootWorkspace: false,
-  },
-
-  // Apply workspace configs in bulk by workspace pattern, in order.
-  // Each entry merges into matching workspaces' accumulated config.
-  // Pattern matching reflects aliases and tags added by earlier entries.
-  workspacePatternConfigs: [
-    {
-      patterns: ["path:packages/apps/**/*"],
-      config: { tags: ["app"] },
-    },
-    {
-      patterns: ["path:packages/libs/**/*"],
-      config: { tags: ["lib"] },
-    },
-    {
-      // "tag:app" matches because the first entry added it
-      patterns: ["tag:app"],
-      config: {
-        rules: {
-          workspaceDependencies: {
-            allowPatterns: ["tag:lib"], // apps may only depend on libs
-          },
-        },
-      },
-    },
-    {
-      patterns: ["tag:app"],
-      // Factory form: receives static workspace data and accumulated config
-      config: (workspace, prevConfig) => ({
-        alias: workspace.name.replace(/^@my-scope\\//, ""),
-      }),
-    },
-  ],
-});
-`.trim();
-const WORKSPACE_CONFIG_QUICKSTART = `
-// bw.workspace.ts — place in a workspace directory
-
-// Also supported: bw.workspace.js, bw.workspace.json, bw.workspace.jsonc, or a "bw" key in package.json
-
-import { defineWorkspaceConfig } from "bun-workspaces/config";
-
-export default defineWorkspaceConfig({
-  alias: "my-web-app", // shorthand name; use array for multiple
-  tags: ["app", "frontend"],
-  scripts: {
-    // lower order runs first in sequenced script execution
-    build: { order: 1 },
-    test: { order: 2 },
-  },
-  rules: {
-    workspaceDependencies: {
-      // Only "my-workspace" or workspaces tagged "lib" are allowed as dependencies
-      allowPatterns: ["tag:lib", "my-workspace"],
-      // Workspaces tagged "backend" are forbidden as dependencies
-      denyPatterns: ["tag:backend"],
-    },
-  },
-});
-`.trim();
-
 const SERVER_INSTRUCTIONS = `
-bun-workspaces MCP server: tools to query Bun monorepo workspace metadata and documentation resources for the bun-workspaces CLI and TypeScript API.
+bun-workspaces ${package_0.version} MCP server: tools to query Bun monorepo workspace metadata and documentation resources for the bun-workspaces CLI and TypeScript API.
 
-bun-workspaces is an npm package that works on top of Bun's native workspaces. If this server is running, the project likely has bun-workspaces installed, or the user invokes it via bunx — often using the recommended alias "bw" for \`bunx bun-workspaces\`.
+bun-workspaces is an npm package that works on top of Bun's native workspaces. It has a CLI and TS API.
 
-Use the tools to understand the project's workspaces and scripts. Running scripts across workspaces is a core bw feature not exposed as a tool — use the CLI directly. See the bw://docs/cli resource for the full CLI reference.
+Files such as bw.workspace.ts and bw.root.ts may be present for configuration.
 
-There are optional configuration files for the bun-workspaces CLI and TypeScript API. See the bw://docs/config resource for the full configuration reference.
+Use resources for docs on the CLI and TS API, or get a project overview via bw://project.
+bw://docs/overview, bw://docs/concepts, bw://docs/cli, bw://docs/api, and bw://docs/config cover most functionality.
 
-## CLI quickstart
+Use the tools to get specific metadata about the project.
 
+## CLI quickstart
 \`\`\`bash
-${CLI_QUICKSTART}
+$ alias bw="bunx bun-workspaces"
+$ bw --help # usage
+$ # run is an alias for run-script
+$ bw run lint # run the "lint" script for all workspaces that have it
+$ bw run "echo inline script" --inline # run an inline command via the Bun shell
+$ bw run lint my-workspace-a my-workspace-b # run for specific workspaces
+$ bw run lint --dep-order # run the lint script for all workspaces, waiting for all dependencies to complete
+$ bw run lint "my-workspace-*" # wildcard for workspace names
+$ bw run lint "alias:my-alias-*" "path:packages/**/*" "not:path:my-path/*" # use workspace patterns
 \`\`\`
 
-## API quickstart
-
-\`\`\`typescript
-${API_QUICKSTART}
-\`\`\`
-
-## Root config quickstart
-
-\`\`\`typescript
-${ROOT_CONFIG_QUICKSTART}
-\`\`\`
-
-## Workspace config quickstart
-
-\`\`\`typescript
-${WORKSPACE_CONFIG_QUICKSTART}
-\`\`\`
+(end bun-workspaces MCP instructions)
 `.trim();
-const startBwMcpServer = async (project) => {
+const startBwMcpServer = async (options) => {
+  setServerWorkingDirectory(options.initialWorkingDirectory);
   const server = createMcpServer({
     name: "bun-workspaces",
     version: package_0.version,
     instructions: SERVER_INSTRUCTIONS,
   });
-  registerBwTools(server, project);
-  registerBwResources(server, project);
+  registerBwTools(server);
+  registerBwResources(server);
   await server.start();
 };
 
-export { startBwMcpServer };
+export { SERVER_INSTRUCTIONS, startBwMcpServer };

package/src/ai/mcp/resources.mjs

@@ -5,6 +5,7 @@ import {
   DOC_CONFIG,
   DOC_OVERVIEW,
 } from "../../internal/generated/aiDocs/docs.mjs";
+import { getServerProject } from "./serverState.mjs";
 
 const textResource = (uri, text) => ({
   contents: [
@@ -15,7 +16,7 @@ const textResource = (uri, text) => ({
     },
   ],
 });
-const registerBwResources = (server, project) => {
+const registerBwResources = (server) => {
   server.registerResource(
     {
       uri: "bw://project",
@@ -24,23 +25,30 @@ const registerBwResources = (server, project) => {
         "Overview of this bun-workspaces project: name, root directory, and all workspace metadata.",
       mimeType: "application/json",
     },
-    (uri) => ({
-      contents: [
-        {
-          uri,
-          mimeType: "application/json",
-          text: JSON.stringify(
-            {
-              name: project.name,
-              rootDirectory: project.rootDirectory,
-              workspaces: project.workspaces,
-            },
-            null,
-            2,
-          ),
-        },
-      ],
-    }),
+    (uri) => {
+      const project = getServerProject();
+      const data = project
+        ? {
+            available: true,
+            name: project.name,
+            rootDirectory: project.rootDirectory,
+            workspaces: project.workspaces,
+          }
+        : {
+            available: false,
+            message:
+              "No bun-workspaces project is available in the current directory.",
+          };
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "application/json",
+            text: JSON.stringify(data, null, 2),
+          },
+        ],
+      };
+    },
   );
   server.registerResource(
     {
@@ -57,7 +65,7 @@ const registerBwResources = (server, project) => {
       uri: "bw://docs/concepts",
       name: "bun-workspaces concepts",
       description:
-        "Workspace patterns, script runtime metadata, and how to run scripts via the CLI.",
+        "Workspace patterns, workspace script metadata, and how to run scripts via the CLI.",
       mimeType: "text/markdown",
     },
     (uri) => textResource(uri, DOC_CONCEPTS),

package/src/ai/mcp/serverState.mjs

@@ -0,0 +1,20 @@
+import { createFileSystemProject } from "../../project/implementations/fileSystemProject.mjs";
+
+const SERVER_STATE = {
+  workingDirectory: null,
+};
+const setServerWorkingDirectory = (directory) => {
+  SERVER_STATE.workingDirectory = directory;
+};
+const getServerProject = () => {
+  if (!SERVER_STATE.workingDirectory) return null;
+  try {
+    return createFileSystemProject({
+      rootDirectory: SERVER_STATE.workingDirectory,
+    });
+  } catch {
+    return null;
+  }
+};
+
+export { getServerProject, setServerWorkingDirectory };

package/src/ai/mcp/tools.mjs

@@ -1,5 +1,6 @@
 import { getDoctorInfo } from "../../doctor/index.mjs";
 import { BUN_WORKSPACES_VERSION } from "../../internal/version.mjs";
+import { getServerProject, setServerWorkingDirectory } from "./serverState.mjs";
 
 const textResult = (data) => ({
   content: [
@@ -18,7 +19,14 @@ const errorResult = (message) => ({
   ],
   isError: true,
 });
-const registerBwTools = (server, project) => {
+const NO_PROJECT_RESULT = errorResult(
+  "No bun-workspaces project is available in the current directory.",
+);
+const withProject = (handler) => (input) => {
+  const project = getServerProject();
+  return project ? handler(project, input) : NO_PROJECT_RESULT;
+};
+const registerBwTools = (server) => {
   server.registerTool(
     {
       name: "version",
@@ -51,13 +59,13 @@ const registerBwTools = (server, project) => {
         },
       },
     },
-    ({ patterns }) => {
+    withProject((project, { patterns }) => {
       const workspaces =
         patterns && Array.isArray(patterns) && patterns.length > 0
           ? project.findWorkspacesByPattern(...patterns)
           : project.workspaces;
       return textResult(workspaces);
-    },
+    }),
   );
   server.registerTool(
     {
@@ -76,7 +84,7 @@ const registerBwTools = (server, project) => {
         required: ["nameOrAlias"],
       },
     },
-    ({ nameOrAlias }) => {
+    withProject((project, { nameOrAlias }) => {
       const name = nameOrAlias;
       const workspace =
         name === /* inlined export .ROOT_WORKSPACE_SELECTOR */ "@root"
@@ -86,7 +94,7 @@ const registerBwTools = (server, project) => {
         return errorResult(`Workspace not found: "${name}"`);
       }
       return textResult(workspace);
-    },
+    }),
   );
   server.registerTool(
     {
@@ -96,7 +104,7 @@ const registerBwTools = (server, project) => {
         type: "object",
       },
     },
-    () => textResult(project.rootWorkspace),
+    withProject((project) => textResult(project.rootWorkspace)),
   );
   server.registerTool(
     {
@@ -107,14 +115,14 @@ const registerBwTools = (server, project) => {
         type: "object",
       },
     },
-    () => {
+    withProject((project) => {
       const scriptMap = project.mapScriptsToWorkspaces();
       const scripts = Object.values(scriptMap).map(({ name, workspaces }) => ({
         name,
         workspaces: workspaces.map((w) => w.name),
       }));
       return textResult(scripts);
-    },
+    }),
   );
   server.registerTool(
     {
@@ -132,7 +140,7 @@ const registerBwTools = (server, project) => {
         required: ["script"],
       },
     },
-    ({ script }) => {
+    withProject((project, { script }) => {
       const scriptMap = project.mapScriptsToWorkspaces();
       const scriptMetadata = scriptMap[script];
       if (!scriptMetadata) {
@@ -142,7 +150,7 @@ const registerBwTools = (server, project) => {
         name: scriptMetadata.name,
         workspaces: scriptMetadata.workspaces.map((w) => w.name),
       });
-    },
+    }),
   );
   server.registerTool(
     {
@@ -153,14 +161,14 @@ const registerBwTools = (server, project) => {
         type: "object",
       },
     },
-    () => {
+    withProject((project) => {
       const tagMap = project.mapTagsToWorkspaces();
       const tags = Object.entries(tagMap).map(([tag, workspaces]) => ({
         tag,
         workspaces: workspaces.map((w) => w.name),
       }));
       return textResult(tags);
-    },
+    }),
   );
   server.registerTool(
     {
@@ -178,7 +186,7 @@ const registerBwTools = (server, project) => {
         required: ["tag"],
       },
     },
-    ({ tag }) => {
+    withProject((project, { tag }) => {
       const tagMap = project.mapTagsToWorkspaces();
       const tagWorkspaces = tagMap[tag];
       if (!tagWorkspaces) {
@@ -188,6 +196,36 @@ const registerBwTools = (server, project) => {
         name: tag,
         workspaces: tagWorkspaces.map((w) => w.name),
       });
+    }),
+  );
+  server.registerTool(
+    {
+      name: "set_working_directory",
+      description:
+        "Set the working directory used by this MCP server. All subsequent project queries will reflect the new directory.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          directory: {
+            type: "string",
+            description: "Absolute path to the new working directory",
+          },
+        },
+        required: ["directory"],
+      },
+    },
+    ({ directory }) => {
+      setServerWorkingDirectory(directory);
+      const project = getServerProject();
+      return textResult({
+        directory,
+        project: project
+          ? {
+              name: project.name,
+              workspaces: project.workspaces.map((w) => w.name),
+            }
+          : null,
+      });
     },
   );
   server.registerTool(

package/src/cli/commands/mcp.mjs

@@ -1,10 +1,15 @@
 import { startBwMcpServer } from "../../ai/mcp/index.mjs";
 import { logger } from "../../internal/logger/index.mjs";
-import { handleProjectCommand } from "./commandHandlerUtils.mjs";
+import { handleGlobalCommand } from "./commandHandlerUtils.mjs";
 
-const mcpServer = handleProjectCommand("mcpServer", async ({ project }) => {
-  logger.printLevel = "silent";
-  await startBwMcpServer(project);
-});
+const mcpServer = handleGlobalCommand(
+  "mcpServer",
+  async ({ workingDirectory }) => {
+    logger.printLevel = "silent";
+    await startBwMcpServer({
+      initialWorkingDirectory: workingDirectory,
+    });
+  },
+);
 
 export { mcpServer };

package/src/cli/createCli.mjs

@@ -82,11 +82,8 @@ const createCli = ({ defaultCwd = process.cwd(), defaultMiddleware } = {}) => {
         process.exit(1);
         return;
       }
-      const { project, projectError } = initializeWithGlobalOptions(
-        program,
-        args,
-        middleware,
-      );
+      const { project, projectError, workingDirectory } =
+        initializeWithGlobalOptions(program, args, middleware);
       middleware.findProject({
         ...defaultContext,
         project,
@@ -105,6 +102,7 @@ const createCli = ({ defaultCwd = process.cwd(), defaultMiddleware } = {}) => {
         outputWriters,
         terminalWidth,
         terminalHeight,
+        workingDirectory,
       });
       defineGlobalCommands({
         program,
@@ -113,6 +111,7 @@ const createCli = ({ defaultCwd = process.cwd(), defaultMiddleware } = {}) => {
         outputWriters,
         terminalWidth,
         terminalHeight,
+        workingDirectory,
       });
       logger.debug(`Commands initialized. Parsing args...`);
       middleware.preParse({

package/src/cli/globalOptions/globalOptions.mjs

@@ -133,6 +133,7 @@ const applyGlobalOptions = (options) => {
   return {
     project,
     projectError: error,
+    workingDirectory: options.cwd,
   };
 };
 const initializeWithGlobalOptions = (program, args, middleware) => {

package/src/cli/index.d.ts

@@ -587,7 +587,7 @@ export declare const CLI_COMMANDS_CONFIG: {
   };
   readonly mcpServer: {
     readonly command: "mcp-server";
-    readonly isGlobal: false;
+    readonly isGlobal: true;
     readonly aliases: [];
     readonly description: "Start the bun-workspaces MCP (Model Context Protocol) server over stdio";
     readonly options: {};
@@ -791,7 +791,7 @@ export declare const getCliCommandConfig: (commandName: CliCommandName) =>
     }
   | {
       readonly command: "mcp-server";
-      readonly isGlobal: false;
+      readonly isGlobal: true;
       readonly aliases: [];
       readonly description: "Start the bun-workspaces MCP (Model Context Protocol) server over stdio";
       readonly options: {};
@@ -919,6 +919,7 @@ export type GlobalCommandContext = {
   outputWriters: Required<WriteOutputOptions>;
   terminalWidth: number;
   terminalHeight: number;
+  workingDirectory: string;
 };
 export type ProjectCommandContext = GlobalCommandContext & {
   project: FileSystemProject;
@@ -1022,7 +1023,7 @@ export declare const defineProjectCommands: (
   context: ProjectCommandContext,
 ) => void;
 export declare const mcpServer: (
-  context: ProjectCommandContext,
+  context: GlobalCommandContext,
 ) => import("commander").Command;
 export declare const runScript: (
   context: ProjectCommandContext,
@@ -1080,6 +1081,7 @@ export declare const initializeWithGlobalOptions: (
     ): CreateProjectScriptCommandResult;
   }>;
   projectError: Error | null;
+  workingDirectory: string;
 };
 
 export {};

package/src/internal/generated/aiDocs/docs.mjs

@@ -25,12 +25,28 @@ Patterns can include a wildcard to match only by workspace name: \`my-workspace-
 - Special root workspace selector: \`@root\`.
 - Any pattern can start with \`not:\` to negate the pattern. (e.g. "not:my-workspace-name", "not:tag:my-tag-\\*") This excludes workspaces that match any other present patterns from a result.
 
-### Script runtime metadata
+### Workspace Script Metadata
 
-Scripts ran via bw can access metadata via env vars. This same metadata can be interpolated into inline scripts and appended args.
+Scripts ran via bun-workspaces can access metadata about the workspace, script, and project
+via env vars. This same metadata can also be interpolated into inline scripts and appended args.
 
 \`\`\`typescript
-// in a script
+// in a workspace's script invoked by bun-workspaces using a metadata function
+import { getWorkspaceScriptMetadata } from "bun-workspaces/script";
+
+// Use the helper within a script that was invoked via bun-workspaces
+const projectPath = getWorkspaceScriptMetadata("projectPath");
+const projectName = getWorkspaceScriptMetadata("projectName");
+const workspaceName = getWorkspaceScriptMetadata("workspaceName");
+const workspacePath = getWorkspaceScriptMetadata("workspacePath");
+const workspaceRelativePath = getWorkspaceScriptMetadata(
+  "workspaceRelativePath",
+);
+const scriptName = getWorkspaceScriptMetadata("scriptName");
+\`\`\`
+
+\`\`\`typescript
+// In a script, but accessing the same data via plain environment variables (same values as previous example)
 const projectPath = process.env.BW_PROJECT_PATH;
 const workspaceName = process.env.BW_WORKSPACE_NAME;
 const workspacePath = process.env.BW_WORKSPACE_PATH;

package/src/project/implementations/fileSystemProject.mjs

@@ -15,7 +15,7 @@ import {
 import { logger } from "../../internal/logger/index.mjs";
 import {
   createScriptRuntimeEnvVars,
-  interpolateScriptRuntimeMetadata,
+  interpolateWorkspaceScriptMetadata,
   runScript,
   runScripts,
 } from "../../runScript/index.mjs";
@@ -39,11 +39,18 @@ const serializeArgs = (args, metadata, shell) => {
   if (Array.isArray(args)) {
     return args
       .map((arg) =>
-        quoteArg(interpolateScriptRuntimeMetadata(arg, metadata, shell), shell),
+        quoteArg(
+          interpolateWorkspaceScriptMetadata(arg, metadata, shell),
+          shell,
+        ),
       )
       .join(" ");
   }
-  const interpolated = interpolateScriptRuntimeMetadata(args, metadata, shell);
+  const interpolated = interpolateWorkspaceScriptMetadata(
+    args,
+    metadata,
+    shell,
+  );
   // Escape backslashes in interpolated values before POSIX parse on Windows,
   // so that path separators survive parse's escape processing (\\→\)
   const parseInput =
@@ -215,7 +222,7 @@ class _FileSystemProject extends ProjectBase {
       typeof options.inline === "object"
         ? (options.inline?.scriptName ?? "")
         : "";
-    const scriptRuntimeMetadata = {
+    const workspaceScriptMetadata = {
       projectPath: this.rootDirectory,
       projectName: this.name,
       workspacePath: resolveWorkspacePath(this, workspace),
@@ -223,11 +230,11 @@ class _FileSystemProject extends ProjectBase {
       workspaceName: workspace.name,
       scriptName: options.inline ? inlineScriptName : options.script,
     };
-    const args = serializeArgs(options.args, scriptRuntimeMetadata, shell);
+    const args = serializeArgs(options.args, workspaceScriptMetadata, shell);
     const script = options.inline
-      ? interpolateScriptRuntimeMetadata(
+      ? interpolateWorkspaceScriptMetadata(
           options.script,
-          scriptRuntimeMetadata,
+          workspaceScriptMetadata,
           shell,
         ) + (args ? " " + args : "")
       : options.script;
@@ -251,7 +258,7 @@ class _FileSystemProject extends ProjectBase {
       metadata: {
         workspace,
       },
-      env: createScriptRuntimeEnvVars(scriptRuntimeMetadata),
+      env: createScriptRuntimeEnvVars(workspaceScriptMetadata),
       shell,
       ignoreOutput: options.ignoreOutput ?? false,
     });
@@ -422,7 +429,7 @@ class _FileSystemProject extends ProjectBase {
           typeof options.inline === "object"
             ? (options.inline?.scriptName ?? "")
             : "";
-        const scriptRuntimeMetadata = {
+        const workspaceScriptMetadata = {
           projectPath: this.rootDirectory,
           projectName: this.name,
           workspacePath: resolveWorkspacePath(this, workspace),
@@ -430,11 +437,15 @@ class _FileSystemProject extends ProjectBase {
           workspaceName: workspace.name,
           scriptName: options.inline ? inlineScriptName : options.script,
         };
-        const args = serializeArgs(options.args, scriptRuntimeMetadata, shell);
+        const args = serializeArgs(
+          options.args,
+          workspaceScriptMetadata,
+          shell,
+        );
         const script = options.inline
-          ? interpolateScriptRuntimeMetadata(
+          ? interpolateWorkspaceScriptMetadata(
               options.script,
-              scriptRuntimeMetadata,
+              workspaceScriptMetadata,
               shell,
             ) + (args ? " " + args : "")
           : options.script;
@@ -456,7 +467,7 @@ class _FileSystemProject extends ProjectBase {
             workspace,
           },
           scriptCommand,
-          env: createScriptRuntimeEnvVars(scriptRuntimeMetadata),
+          env: createScriptRuntimeEnvVars(workspaceScriptMetadata),
           shell,
           dependsOn: options.dependencyOrder
             ? workspace.dependencies

package/src/runScript/index.mjs

@@ -3,7 +3,7 @@ export * from "./runScripts.mjs";
 export * from "./scriptCommand.mjs";
 export * from "./output/index.mjs";
 export * from "./parallel.mjs";
-export * from "./scriptRuntimeMetadata.mjs";
+export * from "./workspaceScriptMetadata.mjs";
 export * from "./scriptShellOption.mjs";
 
 export {};

package/src/runScript/public.d.ts

@@ -0,0 +1,42 @@
+// Generated by dts-bundle-generator v9.5.1
+
+declare const WORKSPACE_SCRIPT_METADATA_CONFIG: {
+  readonly projectPath: {
+    readonly inlineName: "<projectPath>";
+    readonly envVarName: "BW_PROJECT_PATH";
+  };
+  readonly projectName: {
+    readonly inlineName: "<projectName>";
+    readonly envVarName: "BW_PROJECT_NAME";
+  };
+  readonly workspacePath: {
+    readonly inlineName: "<workspacePath>";
+    readonly envVarName: "BW_WORKSPACE_PATH";
+  };
+  readonly workspaceRelativePath: {
+    readonly inlineName: "<workspaceRelativePath>";
+    readonly envVarName: "BW_WORKSPACE_RELATIVE_PATH";
+  };
+  readonly scriptName: {
+    readonly inlineName: "<scriptName>";
+    readonly envVarName: "BW_SCRIPT_NAME";
+  };
+  readonly workspaceName: {
+    readonly inlineName: "<workspaceName>";
+    readonly envVarName: "BW_WORKSPACE_NAME";
+  };
+};
+export type WorkspaceScriptMetadataKey =
+  keyof typeof WORKSPACE_SCRIPT_METADATA_CONFIG;
+/**
+ * This is a utility to run from a workspace's script that was called via `bun-workspaces`.
+ *
+ * It gets the value of some metadata value about the project, workspace, or script that was invoked.
+ */
+export declare const getWorkspaceScriptMetadata: (
+  key: WorkspaceScriptMetadataKey,
+) => string;
+/** @deprecated Renamed: Use {@link WorkspaceScriptMetadataKey} instead */
+export type ScriptRuntimeMetadataKey = WorkspaceScriptMetadataKey;
+
+export {};

package/src/runScript/public.mjs

@@ -0,0 +1 @@
+export { getWorkspaceScriptMetadata } from "./workspaceScriptMetadata.mjs";

package/src/runScript/recursion.mjs

@@ -1,10 +1,10 @@
-import { getScriptRuntimeMetadataConfig } from "../1108.mjs";
+import { getWorkspaceScriptMetadataConfig } from "../3725.mjs";
 
 const checkIsRecursiveScript = (workspaceName, scriptName) => {
   const parentWorkspace =
-    process.env[getScriptRuntimeMetadataConfig("workspaceName").envVarName];
+    process.env[getWorkspaceScriptMetadataConfig("workspaceName").envVarName];
   const parentScript =
-    process.env[getScriptRuntimeMetadataConfig("scriptName").envVarName];
+    process.env[getWorkspaceScriptMetadataConfig("scriptName").envVarName];
   if (!parentWorkspace || !parentScript) {
     return false;
   }

package/src/runScript/workspaceScriptMetadata.mjs

@@ -0,0 +1,60 @@
+import { BunWorkspacesError, IS_WINDOWS } from "../internal/core/index.mjs";
+import { getWorkspaceScriptMetadataConfig } from "../3725.mjs";
+
+const createScriptRuntimeEnvVars = (metadata) => {
+  const keys = [
+    "projectPath",
+    "projectName",
+    "workspacePath",
+    "workspaceRelativePath",
+    "scriptName",
+    "workspaceName",
+  ];
+  return keys.reduce((acc, key) => {
+    const { envVarName } = getWorkspaceScriptMetadataConfig(key);
+    acc[envVarName] = metadata[key];
+    return acc;
+  }, {});
+};
+const interpolateWorkspaceScriptMetadata = (text, metadata, shell) => {
+  const keys = [
+    "projectPath",
+    "projectName",
+    "workspacePath",
+    "workspaceRelativePath",
+    "scriptName",
+    "workspaceName",
+  ];
+  const inlineNames = keys.map(
+    (key) => getWorkspaceScriptMetadataConfig(key).inlineName,
+  );
+  return text.replace(new RegExp(inlineNames.join("|"), "g"), (match) => {
+    const key = keys.find(
+      (k) => getWorkspaceScriptMetadataConfig(k).inlineName === match,
+    );
+    const value = metadata[key];
+    if (IS_WINDOWS && shell === "bun") {
+      return value.replace(/\\/g, "\\\\");
+    }
+    return value;
+  });
+};
+/**
+ * This is a utility to run from a workspace's script that was called via `bun-workspaces`.
+ *
+ * It gets the value of some metadata value about the project, workspace, or script that was invoked.
+ */ const getWorkspaceScriptMetadata = (key) => {
+  const { envVarName } = getWorkspaceScriptMetadataConfig(key);
+  if (!(envVarName in process.env)) {
+    throw new BunWorkspacesError(
+      `getScriptMetadata() called with key "${key}" but environment variable ${envVarName} is not set. getScriptMetadata() may not have been called in a workspace script running via bun-workspaces.`,
+    );
+  }
+  return process.env[envVarName];
+};
+
+export {
+  createScriptRuntimeEnvVars,
+  getWorkspaceScriptMetadata,
+  interpolateWorkspaceScriptMetadata,
+};

package/src/runScript/scriptRuntimeMetadata.mjs

@@ -1,43 +0,0 @@
-import { IS_WINDOWS } from "../internal/core/index.mjs";
-import { getScriptRuntimeMetadataConfig } from "../1108.mjs";
-
-const createScriptRuntimeEnvVars = (metadata) => {
-  const keys = [
-    "projectPath",
-    "projectName",
-    "workspacePath",
-    "workspaceRelativePath",
-    "scriptName",
-    "workspaceName",
-  ];
-  return keys.reduce((acc, key) => {
-    const { envVarName } = getScriptRuntimeMetadataConfig(key);
-    acc[envVarName] = metadata[key];
-    return acc;
-  }, {});
-};
-const interpolateScriptRuntimeMetadata = (text, metadata, shell) => {
-  const keys = [
-    "projectPath",
-    "projectName",
-    "workspacePath",
-    "workspaceRelativePath",
-    "scriptName",
-    "workspaceName",
-  ];
-  const inlineNames = keys.map(
-    (key) => getScriptRuntimeMetadataConfig(key).inlineName,
-  );
-  return text.replace(new RegExp(inlineNames.join("|"), "g"), (match) => {
-    const key = keys.find(
-      (k) => getScriptRuntimeMetadataConfig(k).inlineName === match,
-    );
-    const value = metadata[key];
-    if (IS_WINDOWS && shell === "bun") {
-      return value.replace(/\\/g, "\\\\");
-    }
-    return value;
-  });
-};
-
-export { createScriptRuntimeEnvVars, interpolateScriptRuntimeMetadata };