bun-workspaces 1.4.1 → 1.5.0

package/README.md

@@ -11,6 +11,7 @@
 - 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.
@@ -81,6 +82,7 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-workspaces",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "A monorepo management tool for Bun, with a CLI and API to enhance Bun's native workspaces.",
   "license": "MIT",
   "exports": {

package/src/ai/mcp/bwMcpServer.d.ts

@@ -0,0 +1,4 @@
+import type { FileSystemProject } from "../../project/implementations/fileSystemProject";
+export declare const startBwMcpServer: (
+  project: FileSystemProject,
+) => Promise<void>;

package/src/ai/mcp/bwMcpServer.mjs

@@ -0,0 +1,46 @@
+import package_0 from "../../../package.json";
+import { API_QUICKSTART } from "../../internal/docs/apiQuickstart.mjs";
+import { CLI_QUICKSTART } from "../../internal/docs/cliQuickstart.mjs";
+import { createMcpServer } from "./core/index.mjs";
+import { registerBwResources } from "./resources.mjs";
+import { registerBwTools } from "./tools.mjs"; // CONCATENATED MODULE: external "../../../package.json"
+// CONCATENATED MODULE: external "../../internal/docs/apiQuickstart.mjs"
+// CONCATENATED MODULE: external "../../internal/docs/cliQuickstart.mjs"
+// CONCATENATED MODULE: external "./core/index.mjs"
+// CONCATENATED MODULE: external "./resources.mjs"
+// CONCATENATED MODULE: external "./tools.mjs"
+// CONCATENATED MODULE: ./src/ai/mcp/bwMcpServer.ts
+
+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 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\`.
+
+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.
+
+There are optional configuration files for the bun-workspaces CLI and TypeScript API. See the bw://docs/config resource for the full configuration reference.
+
+## CLI quickstart
+
+\`\`\`bash
+${CLI_QUICKSTART}
+\`\`\`
+
+## API quickstart
+
+\`\`\`typescript
+${API_QUICKSTART}
+\`\`\`
+`.trim();
+const startBwMcpServer = async (project) => {
+  const server = createMcpServer({
+    name: "bun-workspaces",
+    version: package_0.version,
+    instructions: SERVER_INSTRUCTIONS,
+  });
+  registerBwTools(server, project);
+  registerBwResources(server, project);
+  await server.start();
+};
+
+export { startBwMcpServer };

package/src/ai/mcp/core/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./transport";
+export * from "./server";

package/src/ai/mcp/core/index.mjs

@@ -0,0 +1,3 @@
+export * from "./types.mjs";
+export * from "./transport.mjs";
+export * from "./server.mjs"; // CONCATENATED MODULE: ./src/ai/mcp/core/index.ts

package/src/ai/mcp/core/server.d.ts

@@ -0,0 +1,14 @@
+import { type McpTransport } from "./transport";
+import {
+  type McpServerInfo,
+  type Resource,
+  type ResourceHandler,
+  type Tool,
+  type ToolHandler,
+} from "./types";
+export type McpServer = {
+  registerTool: (tool: Tool, handler: ToolHandler) => void;
+  registerResource: (resource: Resource, handler: ResourceHandler) => void;
+  start: (transport?: McpTransport) => Promise<void>;
+};
+export declare const createMcpServer: (info: McpServerInfo) => McpServer;

package/src/ai/mcp/core/server.mjs

@@ -0,0 +1,169 @@
+import { createStdioTransport } from "./transport.mjs";
+import { JSON_RPC_ERROR_CODES, MCP_PROTOCOL_VERSION } from "./types.mjs"; // CONCATENATED MODULE: external "./transport.mjs"
+// CONCATENATED MODULE: external "./types.mjs"
+// CONCATENATED MODULE: ./src/ai/mcp/core/server.ts
+
+const createMcpServer = (info) => {
+  const tools = new Map();
+  const resources = new Map();
+  const registerTool = (tool, handler) => {
+    tools.set(tool.name, {
+      tool,
+      handler,
+    });
+  };
+  const registerResource = (resource, handler) => {
+    resources.set(resource.uri, {
+      resource,
+      handler,
+    });
+  };
+  const start = async (transport) => {
+    const activeTransport = transport ?? createStdioTransport();
+    const send = (id, result) => {
+      activeTransport.send({
+        jsonrpc: "2.0",
+        id,
+        result,
+      });
+    };
+    const sendError = (id, code, message) => {
+      activeTransport.send({
+        jsonrpc: "2.0",
+        id,
+        error: {
+          code,
+          message,
+        },
+      });
+    };
+    const handleInitialize = (id) => {
+      const result = {
+        protocolVersion: MCP_PROTOCOL_VERSION,
+        capabilities: {
+          ...(tools.size > 0
+            ? {
+                tools: {},
+              }
+            : {}),
+          ...(resources.size > 0
+            ? {
+                resources: {},
+              }
+            : {}),
+        },
+        serverInfo: {
+          name: info.name,
+          version: info.version,
+        },
+        ...(info.instructions !== undefined
+          ? {
+              instructions: info.instructions,
+            }
+          : {}),
+      };
+      send(id, result);
+    };
+    const handleListTools = (id) => {
+      send(id, {
+        tools: [...tools.values()].map(({ tool }) => tool),
+      });
+    };
+    const handleCallTool = async (id, params) => {
+      const name = params["name"];
+      const args = params["arguments"] ?? {};
+      const registered = tools.get(name);
+      if (!registered) {
+        sendError(
+          id,
+          JSON_RPC_ERROR_CODES.methodNotFound,
+          `Tool not found: ${name}`,
+        );
+        return;
+      }
+      try {
+        const result = await registered.handler(args);
+        send(id, result);
+      } catch (error) {
+        send(id, {
+          content: [
+            {
+              type: "text",
+              text: error instanceof Error ? error.message : String(error),
+            },
+          ],
+          isError: true,
+        });
+      }
+    };
+    const handleListResources = (id) => {
+      send(id, {
+        resources: [...resources.values()].map(({ resource }) => resource),
+      });
+    };
+    const handleReadResource = async (id, params) => {
+      const uri = params["uri"];
+      const registered = resources.get(uri);
+      if (!registered) {
+        sendError(
+          id,
+          JSON_RPC_ERROR_CODES.invalidParams,
+          `Resource not found: ${uri}`,
+        );
+        return;
+      }
+      try {
+        const result = await registered.handler(uri);
+        send(id, result);
+      } catch (error) {
+        sendError(
+          id,
+          JSON_RPC_ERROR_CODES.internalError,
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+    };
+    for await (const raw of activeTransport.receive()) {
+      const method = raw["method"];
+      if (typeof method !== "string") continue;
+      const id = raw["id"];
+      // Notifications have no id — no response needed
+      if (id === undefined || id === null) continue;
+      const requestId = id;
+      const params = raw["params"] ?? {};
+      switch (method) {
+        case "initialize":
+          handleInitialize(requestId);
+          break;
+        case "ping":
+          send(requestId, {});
+          break;
+        case "tools/list":
+          handleListTools(requestId);
+          break;
+        case "tools/call":
+          await handleCallTool(requestId, params);
+          break;
+        case "resources/list":
+          handleListResources(requestId);
+          break;
+        case "resources/read":
+          await handleReadResource(requestId, params);
+          break;
+        default:
+          sendError(
+            requestId,
+            JSON_RPC_ERROR_CODES.methodNotFound,
+            `Method not found: ${method}`,
+          );
+      }
+    }
+  };
+  return {
+    registerTool,
+    registerResource,
+    start,
+  };
+};
+
+export { createMcpServer };

package/src/ai/mcp/core/transport.d.ts

@@ -0,0 +1,12 @@
+export type RawMessage = Record<string, unknown>;
+export type McpTransport = {
+  receive: () => AsyncGenerator<RawMessage>;
+  send: (message: RawMessage) => void;
+};
+export type MemoryTransport = McpTransport & {
+  sent: RawMessage[];
+};
+export declare const createMemoryTransport: (
+  messages: RawMessage[],
+) => MemoryTransport;
+export declare const createStdioTransport: () => McpTransport;

package/src/ai/mcp/core/transport.mjs

@@ -0,0 +1,45 @@
+import readline from "readline"; // CONCATENATED MODULE: external "readline"
+// CONCATENATED MODULE: ./src/ai/mcp/core/transport.ts
+
+const createMemoryTransport = (messages) => {
+  const sent = [];
+  const send = (message) => {
+    sent.push(message);
+  };
+  const receive = async function* () {
+    for (const message of messages) {
+      yield message;
+    }
+  };
+  return {
+    send,
+    receive,
+    sent,
+  };
+};
+const createStdioTransport = () => {
+  const send = (message) => {
+    process.stdout.write(JSON.stringify(message) + "\n");
+  };
+  const receive = async function* () {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      terminal: false,
+    });
+    for await (const line of rl) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        yield JSON.parse(trimmed);
+      } catch {
+        // Ignore malformed lines — the client sent invalid JSON
+      }
+    }
+  };
+  return {
+    send,
+    receive,
+  };
+};
+
+export { createMemoryTransport, createStdioTransport };

package/src/ai/mcp/core/types.d.ts

@@ -0,0 +1,104 @@
+export type JsonRpcId = string | number;
+export type JsonRpcSuccessResponse = {
+  jsonrpc: "2.0";
+  id: JsonRpcId;
+  result: unknown;
+};
+export type JsonRpcErrorResponse = {
+  jsonrpc: "2.0";
+  id: JsonRpcId;
+  error: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+};
+export declare const JSON_RPC_ERROR_CODES: {
+  readonly parseError: -32700;
+  readonly invalidRequest: -32600;
+  readonly methodNotFound: -32601;
+  readonly invalidParams: -32602;
+  readonly internalError: -32603;
+};
+export declare const MCP_PROTOCOL_VERSION = "2024-11-05";
+export type ServerCapabilities = {
+  tools?: Record<string, never>;
+  resources?: Record<string, never>;
+};
+export type McpServerInfo = {
+  name: string;
+  version: string;
+  instructions?: string;
+};
+export type InitializeResult = {
+  protocolVersion: string;
+  capabilities: ServerCapabilities;
+  serverInfo: {
+    name: string;
+    version: string;
+  };
+  instructions?: string;
+};
+export type JsonSchemaProperty =
+  | {
+      type: "string";
+      description?: string;
+      enum?: string[];
+    }
+  | {
+      type: "number";
+      description?: string;
+    }
+  | {
+      type: "boolean";
+      description?: string;
+    }
+  | {
+      type: "array";
+      items: JsonSchemaProperty;
+      description?: string;
+    }
+  | {
+      type: "object";
+      properties?: Record<string, JsonSchemaProperty>;
+      required?: string[];
+      description?: string;
+    };
+export type ToolInputSchema = {
+  type: "object";
+  properties?: Record<string, JsonSchemaProperty>;
+  required?: string[];
+};
+export type Tool = {
+  name: string;
+  description: string;
+  inputSchema: ToolInputSchema;
+};
+export type TextContent = {
+  type: "text";
+  text: string;
+};
+export type CallToolResult = {
+  content: TextContent[];
+  isError?: boolean;
+};
+export type Resource = {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+};
+export type ResourceContent = {
+  uri: string;
+  mimeType: string;
+  text: string;
+};
+export type ReadResourceResult = {
+  contents: ResourceContent[];
+};
+export type ToolHandler = (
+  args: Record<string, unknown>,
+) => Promise<CallToolResult> | CallToolResult;
+export type ResourceHandler = (
+  uri: string,
+) => Promise<ReadResourceResult> | ReadResourceResult;

package/src/ai/mcp/core/types.mjs

@@ -0,0 +1,11 @@
+// CONCATENATED MODULE: ./src/ai/mcp/core/types.ts
+const JSON_RPC_ERROR_CODES = {
+  parseError: -32700,
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internalError: -32603,
+};
+const MCP_PROTOCOL_VERSION = "2024-11-05";
+
+export { JSON_RPC_ERROR_CODES, MCP_PROTOCOL_VERSION };

package/src/ai/mcp/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./core";
+export * from "./bwMcpServer";

package/src/ai/mcp/index.mjs

@@ -0,0 +1,2 @@
+export * from "./core/index.mjs";
+export * from "./bwMcpServer.mjs"; // CONCATENATED MODULE: ./src/ai/mcp/index.ts

package/src/ai/mcp/resources.d.ts

@@ -0,0 +1,6 @@
+import type { FileSystemProject } from "../../project/implementations/fileSystemProject";
+import type { McpServer } from "./core";
+export declare const registerBwResources: (
+  server: McpServer,
+  project: FileSystemProject,
+) => void;

package/src/ai/mcp/resources.mjs

@@ -0,0 +1,98 @@
+import {
+  DOC_API,
+  DOC_CLI,
+  DOC_CONCEPTS,
+  DOC_CONFIG,
+  DOC_OVERVIEW,
+} from "../../internal/generated/aiDocs/docs.mjs"; // CONCATENATED MODULE: external "../../internal/generated/aiDocs/docs.mjs"
+// CONCATENATED MODULE: ./src/ai/mcp/resources.ts
+
+const textResource = (uri, text) => ({
+  contents: [
+    {
+      uri,
+      mimeType: "text/markdown",
+      text,
+    },
+  ],
+});
+const registerBwResources = (server, project) => {
+  server.registerResource(
+    {
+      uri: "bw://project",
+      name: "Project overview",
+      description:
+        "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,
+          ),
+        },
+      ],
+    }),
+  );
+  server.registerResource(
+    {
+      uri: "bw://docs/overview",
+      name: "bun-workspaces overview",
+      description:
+        "What bun-workspaces is, its domain model, and core concepts.",
+      mimeType: "text/markdown",
+    },
+    (uri) => textResource(uri, DOC_OVERVIEW),
+  );
+  server.registerResource(
+    {
+      uri: "bw://docs/concepts",
+      name: "bun-workspaces concepts",
+      description:
+        "Workspace patterns, script runtime metadata, and how to run scripts via the CLI.",
+      mimeType: "text/markdown",
+    },
+    (uri) => textResource(uri, DOC_CONCEPTS),
+  );
+  server.registerResource(
+    {
+      uri: "bw://docs/cli",
+      name: "bun-workspaces CLI reference",
+      description:
+        "Full CLI command reference with examples, including run-script and all global options.",
+      mimeType: "text/markdown",
+    },
+    (uri) => textResource(uri, DOC_CLI),
+  );
+  server.registerResource(
+    {
+      uri: "bw://docs/api",
+      name: "bun-workspaces TypeScript API reference",
+      description:
+        "TypeScript API examples for createFileSystemProject and the Project/Workspace interfaces.",
+      mimeType: "text/markdown",
+    },
+    (uri) => textResource(uri, DOC_API),
+  );
+  server.registerResource(
+    {
+      uri: "bw://docs/config",
+      name: "bun-workspaces config reference",
+      description:
+        "Root config (bw.root.jsonc) and workspace config (bw.workspace.jsonc) schema and options.",
+      mimeType: "text/markdown",
+    },
+    (uri) => textResource(uri, DOC_CONFIG),
+  );
+};
+
+export { registerBwResources };

package/src/ai/mcp/tools.d.ts

@@ -0,0 +1,6 @@
+import type { FileSystemProject } from "../../project/implementations/fileSystemProject";
+import type { McpServer } from "./core";
+export declare const registerBwTools: (
+  server: McpServer,
+  project: FileSystemProject,
+) => void;