@teambit/cli-mcp-server 0.0.0-01a64fc189fd54260378eef7ec9b3e522f9d6315

package/README.docs.mdx

@@ -0,0 +1,345 @@
+# Bit CLI MCP Server
+
+The Bit CLI MCP Server provides a [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/mcp) interface to Bit's command-line functionality, enabling programmatic access to Bit workspace and component management operations. This server exposes Bit CLI commands as MCP tools, making it possible to automate, script, or integrate Bit operations with other tools and platforms.
+
+## Overview
+
+This server acts as a bridge between MCP clients (such as VS Code, AI tools, or your own applications) and the Bit CLI. It leverages the Bit server API for efficient communication and provides both individual CLI command tools and specialized composite tools for common workflows. The server automatically manages a Bit server instance in the background for optimal performance.
+
+## Installation
+
+### Prerequisites
+
+- Node.js (v18 or later recommended)
+- Bit CLI installed and available in your PATH
+
+### Getting Started
+
+The Bit CLI MCP Server is included with Bit. If you have Bit installed, you can run the server using:
+
+```
+bit mcp-server start
+```
+
+## Usage
+
+### Command-Line Options
+
+```
+bit mcp-server start [options]
+```
+
+Options:
+
+- `--consumer-project`: For non-Bit workspaces that only consume Bit component packages. Enables only "bit_remote_search" and "bit_remote_component_details" tools and automatically adds the "--remote" flag to relevant commands.
+- `--include-additional <commands>`: Add specific commands to the available tools (comma-separated list)
+
+### Integrating with IDEs
+
+The easiest way to integrate the MCP server with your IDE is to use the `setup` command:
+
+```bash
+# Basic setup for VS Code (default)
+bit mcp-server setup
+```
+
+This will automatically configure your VS Code settings to use the Bit MCP server. See the [Automatic Setup](#automatic-integration-setup) section below for more options.
+
+### Automatic Integration Setup
+
+The **recommended way** to integrate the MCP server with your IDE is using the `setup` command:
+
+```bash
+bit mcp-server setup [vscode|cursor|windsurf|roo|cline|claude-code] [options]
+```
+
+This command automatically configures the MCP server settings in your chosen editor. If no editor is specified, it defaults to VS Code.
+
+#### Supported Editors
+
+- **VS Code**: `bit mcp-server setup vscode` (or just `bit mcp-server setup`)
+- **Cursor**: `bit mcp-server setup cursor`
+- **Windsurf**: `bit mcp-server setup windsurf`
+- **Roo Code**: `bit mcp-server setup roo`
+- **Cline**: `bit mcp-server setup cline`
+- **Claude Code**: `bit mcp-server setup claude-code`
+
+#### Configuration Options
+
+- `--global`: Apply configuration globally (user settings) instead of workspace settings
+- `--consumer-project`: Configure for consumer projects
+- `--include-additional <commands>`: Add specific commands to the available tools
+
+#### Examples
+
+```bash
+# Basic VS Code setup (workspace level)
+bit mcp-server setup
+
+# Global setup for Cursor
+bit mcp-server setup cursor --global
+
+# Setup with consumer project mode
+bit mcp-server setup --consumer-project
+
+# Setup for Claude Code (creates .mcp.json file)
+bit mcp-server setup claude-code
+
+# Global setup for Claude Code
+bit mcp-server setup claude-code --global
+```
+
+#### Manual Configuration
+
+If you need to manually configure the settings, here's how to set up VS Code MCP integration:
+
+**For workspace-specific configuration:**
+
+1. Create a `.vscode/mcp.json` file in your workspace folder
+2. Add the following configuration:
+
+```json
+{
+  "servers": {
+    "bit-cli": {
+      "type": "stdio",
+      "command": "bit",
+      "args": ["mcp-server", "start"]
+    }
+  }
+}
+```
+
+**For global configuration:**
+
+1. Open VS Code settings (JSON) by pressing `Ctrl + Shift + P` (or `Cmd + Shift + P` on macOS) and typing `Preferences: Open Settings (JSON)`
+2. Add the following configuration:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "bit-cli": {
+        "type": "stdio",
+        "command": "bit",
+        "args": ["mcp-server", "start"]
+      }
+    }
+  }
+}
+```
+
+#### Claude Code Setup
+
+Claude Code uses `.mcp.json` files for MCP server configuration. The setup command creates these files automatically:
+
+**Workspace Configuration:**
+
+```bash
+bit mcp-server setup claude-code
+```
+
+This creates a `.mcp.json` file in your project root:
+
+```json
+{
+  "mcpServers": {
+    "bit": {
+      "command": "bit",
+      "args": ["mcp-server", "start"]
+    }
+  }
+}
+```
+
+**Global Configuration:**
+
+```bash
+bit mcp-server setup claude-code --global
+```
+
+This creates/updates the global configuration file:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/claude/claude_desktop_config.json`
+
+**Important**: After setup, restart Claude Code for the MCP server to be available.
+
+**Claude Code Rules:**
+
+To provide Bit-specific guidance to Claude Code, use the rules command:
+
+```bash
+bit mcp-server rules claude-code
+```
+
+This creates `.claude/bit.md` with Bit instructions. To integrate with your existing `CLAUDE.md`, add:
+
+```markdown
+@.claude/bit.md
+```
+
+This approach ensures your existing `CLAUDE.md` file is never overwritten.
+
+### Programmatic Usage
+
+```javascript
+import { McpClient } from '@modelcontextprotocol/sdk/client';
+
+async function example() {
+  const client = await McpClient.spawn('bit', ['mcp-server', 'start']);
+
+  // Call a Bit CLI tool via MCP
+  const result = await client.callTool('bit_status', { cwd: '/path/to/workspace' });
+  console.log(result.content[0].text);
+
+  // Close the connection when done
+  await client.close();
+}
+```
+
+## Available Tools
+
+The Bit CLI MCP Server operates in two modes and provides several specialized tools:
+
+### Default Mode
+
+In default mode, the server exposes a minimal set of essential tools focused on core functionality. This ensures optimal performance and safety:
+
+- **Always Available Tools:**
+
+  - `bit_remote_search`: Search for components in remote scopes
+  - `bit_workspace_info`: Get comprehensive workspace information including status, components list, apps, templates, and dependency graph
+  - `bit_component_details`: Get detailed information about a specific component including basic info and optionally its public API schema
+  - `bit_query`: Execute read-only Bit commands that safely inspect workspace and component state without making modifications
+  - `bit_execute`: Execute any Bit command, including those that modify workspace or repository state (use with caution)
+  - `bit_commands_list`: Get all available Bit commands with descriptions and groups (for command discovery)
+  - `bit_command_help`: Get detailed help for a specific Bit command including syntax, arguments, flags, and usage examples
+
+> **Command Discovery vs. Command Help**: Use `bit_commands_list` to discover what commands are available in Bit, then use `bit_command_help` with a specific command name to get detailed usage information including arguments, flags, and examples.
+
+### Consumer Project Mode (--consumer-project)
+
+This mode is designed for applications or projects that are not Bit workspaces but need to consume or work with Bit components as packages. It provides a minimal set of tools focused on component discovery and information:
+
+- `bit_remote_search`: Search for components in remote scopes
+- `bit_remote_component_details`: Get detailed information about a remote component including basic info and its public API schema (combines the functionality of show and schema commands)
+
+In this mode:
+
+1. You don't need a Bit workspace initialization
+2. Only these 2 tools are available (no workspace-specific tools)
+3. The `--remote` flag is automatically added to component detail queries
+4. The `cwd` parameter is still required but can be any directory (not necessarily a Bit workspace)
+5. You can still add additional tools with the `--include-additional` flag
+
+## Tool Parameters
+
+All tools accept a `cwd` parameter specifying the workspace path. Additional parameters vary by command.
+
+### bit_remote_search
+
+Search for multiple components in parallel for efficient discovery:
+
+```json
+{
+  "queries": ["input", "button", "validation"],
+  "cwd": "/path/to/workspace"
+}
+```
+
+**Parameters:**
+
+- `queries` (required): Array of search terms. Use either variations/synonyms of one component type (`["btn", "button"]`) or different components needed for a task (`["table", "pagination", "filter"]`)
+- `cwd` (optional): Path to workspace directory
+- `owners` (optional): Filter by specific owners (auto-extracted from workspace.jsonc if not provided)
+- `skipAutoOwner` (optional): Disable automatic owner extraction
+
+**Examples:**
+
+- Form components: `["input", "button", "validation", "dropdown"]`
+- Layout components: `["header", "navigation", "footer"]`
+- Data display: `["table", "pagination", "filter", "sort"]`
+- Button variations: `["button", "btn", "click"]`
+
+Example tool call for `bit_status`:
+
+```json
+{
+  "cwd": "/path/to/workspace",
+  "warnings": true,
+  "json": true
+}
+```
+
+## Custom Tool Selection
+
+To customize the available tools:
+
+```
+# Add specific tools to the available tools
+bit mcp-server start --include-additional "build,lint,format,create,schema"
+
+# For consumer projects (non-Bit workspaces)
+bit mcp-server start --consumer-project
+
+# Add specific tools to the consumer project set
+bit mcp-server start --consumer-project --include-additional "deps,get,preview"
+```
+
+### Writing AI Assistant Rules
+
+The MCP server provides a `rules` command to create instruction files for AI assistants:
+
+```bash
+bit mcp-server rules [vscode|cursor|windsurf|roo|cline|claude-code] [options]
+```
+
+This command creates rules/instructions markdown files that provide guidance to AI assistants on how to effectively use the Bit MCP server and follow best practices when working with Bit components.
+
+#### Supported Editors
+
+- **VS Code**: `bit mcp-server rules vscode` (or just `bit mcp-server rules`)
+- **Cursor**: `bit mcp-server rules cursor`
+- **Windsurf**: `bit mcp-server rules windsurf`
+- **Roo Code**: `bit mcp-server rules roo`
+- **Cline**: `bit mcp-server rules cline`
+- **Claude Code**: `bit mcp-server rules claude-code`
+
+#### Configuration Options
+
+- `--global`: Write rules to global configuration (default: workspace-specific)
+- `--print`: Print rules content to screen instead of writing to file
+- `--consumer-project`: Generate rules for consumer projects that only use Bit components as packages
+
+#### Examples
+
+```bash
+# Basic VS Code rules (workspace level)
+bit mcp-server rules
+
+# Global rules for Cursor
+bit mcp-server rules cursor --global
+
+# Consumer project rules for VS Code
+bit mcp-server rules --consumer-project
+
+# Claude Code rules (creates .claude/bit.md)
+bit mcp-server rules claude-code
+
+# Global Claude Code rules
+bit mcp-server rules claude-code --global
+
+# Global rules for Cline (macOS only)
+bit mcp-server rules cline --global
+
+# Workspace-specific rules for Cline
+bit mcp-server rules cline
+
+# Print rules content to screen for manual setup
+bit mcp-server rules --print
+
+# Print consumer project content for Windsurf (requires manual addition to .windsurfrules)
+bit mcp-server rules windsurf --print --consumer-project
+```

package/dist/README.docs.mdx

@@ -0,0 +1,345 @@
+# Bit CLI MCP Server
+
+The Bit CLI MCP Server provides a [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/mcp) interface to Bit's command-line functionality, enabling programmatic access to Bit workspace and component management operations. This server exposes Bit CLI commands as MCP tools, making it possible to automate, script, or integrate Bit operations with other tools and platforms.
+
+## Overview
+
+This server acts as a bridge between MCP clients (such as VS Code, AI tools, or your own applications) and the Bit CLI. It leverages the Bit server API for efficient communication and provides both individual CLI command tools and specialized composite tools for common workflows. The server automatically manages a Bit server instance in the background for optimal performance.
+
+## Installation
+
+### Prerequisites
+
+- Node.js (v18 or later recommended)
+- Bit CLI installed and available in your PATH
+
+### Getting Started
+
+The Bit CLI MCP Server is included with Bit. If you have Bit installed, you can run the server using:
+
+```
+bit mcp-server start
+```
+
+## Usage
+
+### Command-Line Options
+
+```
+bit mcp-server start [options]
+```
+
+Options:
+
+- `--consumer-project`: For non-Bit workspaces that only consume Bit component packages. Enables only "bit_remote_search" and "bit_remote_component_details" tools and automatically adds the "--remote" flag to relevant commands.
+- `--include-additional <commands>`: Add specific commands to the available tools (comma-separated list)
+
+### Integrating with IDEs
+
+The easiest way to integrate the MCP server with your IDE is to use the `setup` command:
+
+```bash
+# Basic setup for VS Code (default)
+bit mcp-server setup
+```
+
+This will automatically configure your VS Code settings to use the Bit MCP server. See the [Automatic Setup](#automatic-integration-setup) section below for more options.
+
+### Automatic Integration Setup
+
+The **recommended way** to integrate the MCP server with your IDE is using the `setup` command:
+
+```bash
+bit mcp-server setup [vscode|cursor|windsurf|roo|cline|claude-code] [options]
+```
+
+This command automatically configures the MCP server settings in your chosen editor. If no editor is specified, it defaults to VS Code.
+
+#### Supported Editors
+
+- **VS Code**: `bit mcp-server setup vscode` (or just `bit mcp-server setup`)
+- **Cursor**: `bit mcp-server setup cursor`
+- **Windsurf**: `bit mcp-server setup windsurf`
+- **Roo Code**: `bit mcp-server setup roo`
+- **Cline**: `bit mcp-server setup cline`
+- **Claude Code**: `bit mcp-server setup claude-code`
+
+#### Configuration Options
+
+- `--global`: Apply configuration globally (user settings) instead of workspace settings
+- `--consumer-project`: Configure for consumer projects
+- `--include-additional <commands>`: Add specific commands to the available tools
+
+#### Examples
+
+```bash
+# Basic VS Code setup (workspace level)
+bit mcp-server setup
+
+# Global setup for Cursor
+bit mcp-server setup cursor --global
+
+# Setup with consumer project mode
+bit mcp-server setup --consumer-project
+
+# Setup for Claude Code (creates .mcp.json file)
+bit mcp-server setup claude-code
+
+# Global setup for Claude Code
+bit mcp-server setup claude-code --global
+```
+
+#### Manual Configuration
+
+If you need to manually configure the settings, here's how to set up VS Code MCP integration:
+
+**For workspace-specific configuration:**
+
+1. Create a `.vscode/mcp.json` file in your workspace folder
+2. Add the following configuration:
+
+```json
+{
+  "servers": {
+    "bit-cli": {
+      "type": "stdio",
+      "command": "bit",
+      "args": ["mcp-server", "start"]
+    }
+  }
+}
+```
+
+**For global configuration:**
+
+1. Open VS Code settings (JSON) by pressing `Ctrl + Shift + P` (or `Cmd + Shift + P` on macOS) and typing `Preferences: Open Settings (JSON)`
+2. Add the following configuration:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "bit-cli": {
+        "type": "stdio",
+        "command": "bit",
+        "args": ["mcp-server", "start"]
+      }
+    }
+  }
+}
+```
+
+#### Claude Code Setup
+
+Claude Code uses `.mcp.json` files for MCP server configuration. The setup command creates these files automatically:
+
+**Workspace Configuration:**
+
+```bash
+bit mcp-server setup claude-code
+```
+
+This creates a `.mcp.json` file in your project root:
+
+```json
+{
+  "mcpServers": {
+    "bit": {
+      "command": "bit",
+      "args": ["mcp-server", "start"]
+    }
+  }
+}
+```
+
+**Global Configuration:**
+
+```bash
+bit mcp-server setup claude-code --global
+```
+
+This creates/updates the global configuration file:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/claude/claude_desktop_config.json`
+
+**Important**: After setup, restart Claude Code for the MCP server to be available.
+
+**Claude Code Rules:**
+
+To provide Bit-specific guidance to Claude Code, use the rules command:
+
+```bash
+bit mcp-server rules claude-code
+```
+
+This creates `.claude/bit.md` with Bit instructions. To integrate with your existing `CLAUDE.md`, add:
+
+```markdown
+@.claude/bit.md
+```
+
+This approach ensures your existing `CLAUDE.md` file is never overwritten.
+
+### Programmatic Usage
+
+```javascript
+import { McpClient } from '@modelcontextprotocol/sdk/client';
+
+async function example() {
+  const client = await McpClient.spawn('bit', ['mcp-server', 'start']);
+
+  // Call a Bit CLI tool via MCP
+  const result = await client.callTool('bit_status', { cwd: '/path/to/workspace' });
+  console.log(result.content[0].text);
+
+  // Close the connection when done
+  await client.close();
+}
+```
+
+## Available Tools
+
+The Bit CLI MCP Server operates in two modes and provides several specialized tools:
+
+### Default Mode
+
+In default mode, the server exposes a minimal set of essential tools focused on core functionality. This ensures optimal performance and safety:
+
+- **Always Available Tools:**
+
+  - `bit_remote_search`: Search for components in remote scopes
+  - `bit_workspace_info`: Get comprehensive workspace information including status, components list, apps, templates, and dependency graph
+  - `bit_component_details`: Get detailed information about a specific component including basic info and optionally its public API schema
+  - `bit_query`: Execute read-only Bit commands that safely inspect workspace and component state without making modifications
+  - `bit_execute`: Execute any Bit command, including those that modify workspace or repository state (use with caution)
+  - `bit_commands_list`: Get all available Bit commands with descriptions and groups (for command discovery)
+  - `bit_command_help`: Get detailed help for a specific Bit command including syntax, arguments, flags, and usage examples
+
+> **Command Discovery vs. Command Help**: Use `bit_commands_list` to discover what commands are available in Bit, then use `bit_command_help` with a specific command name to get detailed usage information including arguments, flags, and examples.
+
+### Consumer Project Mode (--consumer-project)
+
+This mode is designed for applications or projects that are not Bit workspaces but need to consume or work with Bit components as packages. It provides a minimal set of tools focused on component discovery and information:
+
+- `bit_remote_search`: Search for components in remote scopes
+- `bit_remote_component_details`: Get detailed information about a remote component including basic info and its public API schema (combines the functionality of show and schema commands)
+
+In this mode:
+
+1. You don't need a Bit workspace initialization
+2. Only these 2 tools are available (no workspace-specific tools)
+3. The `--remote` flag is automatically added to component detail queries
+4. The `cwd` parameter is still required but can be any directory (not necessarily a Bit workspace)
+5. You can still add additional tools with the `--include-additional` flag
+
+## Tool Parameters
+
+All tools accept a `cwd` parameter specifying the workspace path. Additional parameters vary by command.
+
+### bit_remote_search
+
+Search for multiple components in parallel for efficient discovery:
+
+```json
+{
+  "queries": ["input", "button", "validation"],
+  "cwd": "/path/to/workspace"
+}
+```
+
+**Parameters:**
+
+- `queries` (required): Array of search terms. Use either variations/synonyms of one component type (`["btn", "button"]`) or different components needed for a task (`["table", "pagination", "filter"]`)
+- `cwd` (optional): Path to workspace directory
+- `owners` (optional): Filter by specific owners (auto-extracted from workspace.jsonc if not provided)
+- `skipAutoOwner` (optional): Disable automatic owner extraction
+
+**Examples:**
+
+- Form components: `["input", "button", "validation", "dropdown"]`
+- Layout components: `["header", "navigation", "footer"]`
+- Data display: `["table", "pagination", "filter", "sort"]`
+- Button variations: `["button", "btn", "click"]`
+
+Example tool call for `bit_status`:
+
+```json
+{
+  "cwd": "/path/to/workspace",
+  "warnings": true,
+  "json": true
+}
+```
+
+## Custom Tool Selection
+
+To customize the available tools:
+
+```
+# Add specific tools to the available tools
+bit mcp-server start --include-additional "build,lint,format,create,schema"
+
+# For consumer projects (non-Bit workspaces)
+bit mcp-server start --consumer-project
+
+# Add specific tools to the consumer project set
+bit mcp-server start --consumer-project --include-additional "deps,get,preview"
+```
+
+### Writing AI Assistant Rules
+
+The MCP server provides a `rules` command to create instruction files for AI assistants:
+
+```bash
+bit mcp-server rules [vscode|cursor|windsurf|roo|cline|claude-code] [options]
+```
+
+This command creates rules/instructions markdown files that provide guidance to AI assistants on how to effectively use the Bit MCP server and follow best practices when working with Bit components.
+
+#### Supported Editors
+
+- **VS Code**: `bit mcp-server rules vscode` (or just `bit mcp-server rules`)
+- **Cursor**: `bit mcp-server rules cursor`
+- **Windsurf**: `bit mcp-server rules windsurf`
+- **Roo Code**: `bit mcp-server rules roo`
+- **Cline**: `bit mcp-server rules cline`
+- **Claude Code**: `bit mcp-server rules claude-code`
+
+#### Configuration Options
+
+- `--global`: Write rules to global configuration (default: workspace-specific)
+- `--print`: Print rules content to screen instead of writing to file
+- `--consumer-project`: Generate rules for consumer projects that only use Bit components as packages
+
+#### Examples
+
+```bash
+# Basic VS Code rules (workspace level)
+bit mcp-server rules
+
+# Global rules for Cursor
+bit mcp-server rules cursor --global
+
+# Consumer project rules for VS Code
+bit mcp-server rules --consumer-project
+
+# Claude Code rules (creates .claude/bit.md)
+bit mcp-server rules claude-code
+
+# Global Claude Code rules
+bit mcp-server rules claude-code --global
+
+# Global rules for Cline (macOS only)
+bit mcp-server rules cline --global
+
+# Workspace-specific rules for Cline
+bit mcp-server rules cline
+
+# Print rules content to screen for manual setup
+bit mcp-server rules --print
+
+# Print consumer project content for Windsurf (requires manual addition to .windsurfrules)
+bit mcp-server rules windsurf --print --consumer-project
+```

package/dist/cli-mcp-server.aspect.d.ts

@@ -0,0 +1,2 @@
+import { Aspect } from '@teambit/harmony';
+export declare const CliMcpServerAspect: Aspect;

package/dist/cli-mcp-server.aspect.js

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CliMcpServerAspect = void 0;
+function _harmony() {
+  const data = require("@teambit/harmony");
+  _harmony = function () {
+    return data;
+  };
+  return data;
+}
+const CliMcpServerAspect = exports.CliMcpServerAspect = _harmony().Aspect.create({
+  id: 'teambit.mcp/cli-mcp-server'
+});
+
+//# sourceMappingURL=cli-mcp-server.aspect.js.map