@teambit/cli-mcp-server 0.0.90 → 0.0.92

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.docs.mdx CHANGED
@@ -1,102 +1,44 @@
1
1
  # Bit CLI MCP Server
2
2
 
3
- 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.
3
+ The Bit CLI MCP Server provides a [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/mcp) interface to Bit's command-line functionality. It acts as a bridge between MCP clients (such as VS Code, AI tools, or your own applications) and the Bit CLI, enabling programmatic access to Bit workspace and component management operations.
4
4
 
5
- ## Overview
5
+ ## Setup
6
6
 
7
- 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.
7
+ ### Installation
8
8
 
9
- ## Installation
10
-
11
- ### Prerequisites
12
-
13
- - Node.js (v18 or later recommended)
14
- - Bit CLI installed and available in your PATH
15
-
16
- ### Getting Started
17
-
18
- The Bit CLI MCP Server is included with Bit. If you have Bit installed, you can run the server using:
19
-
20
- ```
21
- bit mcp-server start
22
- ```
23
-
24
- ## Usage
25
-
26
- ### Command-Line Options
27
-
28
- ```
29
- bit mcp-server start [options]
30
- ```
31
-
32
- Options:
33
-
34
- - `--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.
35
- - `--include-additional <commands>`: Add specific commands to the available tools (comma-separated list)
36
-
37
- ### Integrating with IDEs
38
-
39
- The easiest way to integrate the MCP server with your IDE is to use the `setup` command:
9
+ The Bit CLI MCP Server is included with Bit. To set it up with your IDE, run:
40
10
 
41
11
  ```bash
42
12
  # Basic setup for VS Code (default)
43
13
  bit mcp-server setup
44
- ```
45
-
46
- 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.
47
14
 
48
- ### Automatic Integration Setup
15
+ # Other supported editors
16
+ bit mcp-server setup [vscode|cursor|windsurf|roo|cline|claude-code]
49
17
 
50
- The **recommended way** to integrate the MCP server with your IDE is using the `setup` command:
51
-
52
- ```bash
53
- bit mcp-server setup [vscode|cursor|windsurf|roo|cline|claude-code] [options]
18
+ # For consumer projects (non-Bit workspaces that only consume Bit components)
19
+ bit mcp-server setup --consumer-project
54
20
  ```
55
21
 
56
- This command automatically configures the MCP server settings in your chosen editor. If no editor is specified, it defaults to VS Code.
57
-
58
- #### Supported Editors
59
-
60
- - **VS Code**: `bit mcp-server setup vscode` (or just `bit mcp-server setup`)
61
- - **Cursor**: `bit mcp-server setup cursor`
62
- - **Windsurf**: `bit mcp-server setup windsurf`
63
- - **Roo Code**: `bit mcp-server setup roo`
64
- - **Cline**: `bit mcp-server setup cline`
65
- - **Claude Code**: `bit mcp-server setup claude-code`
22
+ #### Recommended Setup Steps
66
23
 
67
- #### Configuration Options
68
-
69
- - `--global`: Apply configuration globally (user settings) instead of workspace settings
70
- - `--consumer-project`: Configure for consumer projects
71
- - `--include-additional <commands>`: Add specific commands to the available tools
24
+ After installation, consider these helpful setup steps:
72
25
 
73
- #### Examples
74
-
75
- ```bash
76
- # Basic VS Code setup (workspace level)
77
- bit mcp-server setup
78
-
79
- # Global setup for Cursor
80
- bit mcp-server setup cursor --global
81
-
82
- # Setup with consumer project mode
83
- bit mcp-server setup --consumer-project
84
-
85
- # Setup for Claude Code (creates .mcp.json file)
86
- bit mcp-server setup claude-code
87
-
88
- # Global setup for Claude Code
89
- bit mcp-server setup claude-code --global
90
- ```
26
+ 1. **For new workspaces**: Set your default scope so the search tool knows which organization to search:
27
+ ```bash
28
+ bit scope set <your-org.your-scope>
29
+ ```
91
30
 
92
- #### Manual Configuration
31
+ 2. **Generate rules/instructions** (if you haven't already):
32
+ ```bash
33
+ bit mcp-server rules
34
+ ```
35
+ This provides the AI agent with comprehensive guidance about Bit and MCP server functionality.
93
36
 
94
- If you need to manually configure the settings, here's how to set up VS Code MCP integration:
37
+ 3. **VS Code users**: Make sure to select "agent" mode instead of "ask" mode in the chat interface. For first-time users, open the command palette and search for "MCP: List servers" to find and start the Bit server.
95
38
 
96
- **For workspace-specific configuration:**
39
+ ### Manual Configuration
97
40
 
98
- 1. Create a `.vscode/mcp.json` file in your workspace folder
99
- 2. Add the following configuration:
41
+ For IDEs not supported by the automatic setup, add this MCP server configuration:
100
42
 
101
43
  ```json
102
44
  {
@@ -110,94 +52,39 @@ If you need to manually configure the settings, here's how to set up VS Code MCP
110
52
  }
111
53
  ```
112
54
 
113
- **For global configuration:**
55
+ ### Configuration Options
114
56
 
115
- 1. Open VS Code settings (JSON) by pressing `Ctrl + Shift + P` (or `Cmd + Shift + P` on macOS) and typing `Preferences: Open Settings (JSON)`
116
- 2. Add the following configuration:
117
-
118
- ```json
119
- {
120
- "mcp": {
121
- "servers": {
122
- "bit-cli": {
123
- "type": "stdio",
124
- "command": "bit",
125
- "args": ["mcp-server", "start"]
126
- }
127
- }
128
- }
129
- }
130
- ```
57
+ - `--global`: Apply configuration globally (user settings) instead of workspace settings
58
+ - `--consumer-project`: For non-Bit workspaces that only consume Bit components as packages
59
+ - `--include-additional <commands>`: Add specific commands to the available tools (comma-separated list)
131
60
 
132
- #### Claude Code Setup
61
+ ## Usage
133
62
 
134
- Claude Code uses `.mcp.json` files for MCP server configuration. The setup command creates these files automatically:
63
+ ### Running the Server
135
64
 
136
- **Workspace Configuration:**
65
+ To manually start the server:
137
66
 
138
67
  ```bash
139
- bit mcp-server setup claude-code
140
- ```
141
-
142
- This creates a `.mcp.json` file in your project root:
143
-
144
- ```json
145
- {
146
- "mcpServers": {
147
- "bit": {
148
- "command": "bit",
149
- "args": ["mcp-server", "start"]
150
- }
151
- }
152
- }
153
- ```
154
-
155
- **Global Configuration:**
156
-
157
- ```bash
158
- bit mcp-server setup claude-code --global
68
+ bit mcp-server start [options]
159
69
  ```
160
70
 
161
- This creates/updates the global configuration file:
162
-
163
- - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
164
- - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
165
- - **Linux**: `~/.config/claude/claude_desktop_config.json`
166
-
167
- **Important**: After setup, restart Claude Code for the MCP server to be available.
71
+ Options:
72
+ - `--consumer-project`: For non-Bit workspaces that only consume Bit component packages
73
+ - `--include-additional <commands>`: Add specific commands to the available tools (comma-separated list)
168
74
 
169
- **Claude Code Rules:**
75
+ ### Generating AI Rules
170
76
 
171
- To provide Bit-specific guidance to Claude Code, use the rules command:
77
+ Create instruction files for AI assistants:
172
78
 
173
79
  ```bash
174
- bit mcp-server rules claude-code
175
- ```
176
-
177
- This creates `.claude/bit.md` with Bit instructions. To integrate with your existing `CLAUDE.md`, add:
178
-
179
- ```markdown
180
- @.claude/bit.md
80
+ bit mcp-server rules [vscode|cursor|windsurf|roo|cline|claude-code] [options]
181
81
  ```
182
82
 
183
- This approach ensures your existing `CLAUDE.md` file is never overwritten.
184
-
185
- ### Programmatic Usage
186
-
187
- ```javascript
188
- import { McpClient } from '@modelcontextprotocol/sdk/client';
189
-
190
- async function example() {
191
- const client = await McpClient.spawn('bit', ['mcp-server', 'start']);
192
-
193
- // Call a Bit CLI tool via MCP
194
- const result = await client.callTool('bit_status', { cwd: '/path/to/workspace' });
195
- console.log(result.content[0].text);
83
+ Options:
84
+ - `--global`: Write rules to global configuration
85
+ - `--consumer-project`: Generate rules for consumer projects
86
+ - `--print`: Print rules content to screen
196
87
 
197
- // Close the connection when done
198
- await client.close();
199
- }
200
- ```
201
88
 
202
89
  ## Available Tools
203
90
 
@@ -205,203 +92,23 @@ The Bit CLI MCP Server operates in two modes and provides several specialized to
205
92
 
206
93
  ### Default Mode
207
94
 
208
- In default mode, the server exposes a minimal set of essential tools focused on core functionality. This ensures optimal performance and safety:
95
+ In default mode, the server exposes a minimal set of essential tools focused on core functionality:
209
96
 
210
- - **Always Available Tools:**
211
-
212
- - `bit_remote_search`: Search for components in remote scopes
213
- - `bit_workspace_info`: Get comprehensive workspace information including status, components list, apps, templates, and dependency graph
214
- - `bit_component_details`: Get detailed information about multiple components in parallel (up to 5 max) including basic info and optionally their public API schemas
215
- - `bit_create`: Create a new component (source files and config) using a template with proper argument validation and documentation
216
- - `bit_query`: Execute read-only Bit commands that safely inspect workspace and component state without making modifications
217
- - `bit_execute`: Execute any Bit command, including those that modify workspace or repository state (use with caution)
218
- - `bit_commands_list`: Get all available Bit commands with descriptions and groups (for command discovery)
219
- - `bit_command_help`: Get detailed help for a specific Bit command including syntax, arguments, flags, and usage examples
97
+ - `bit_remote_search`: Search for components with automatic organization detection from workspace's defaultScope (e.g., "teambit" from "teambit.defender"). Executes multiple queries in parallel and deduplicates results. Use arrays of related terms or synonyms for better results.
98
+ - `bit_workspace_info`: Get comprehensive workspace information by combining multiple data sources (status, components, apps, templates, dependency graph). Includes current lane information.
99
+ - `bit_component_details`: Get detailed information about multiple components in parallel (up to 5 max to prevent context overload). Includes documentation from .docs.mdx files, example usage from composition files, and optionally the component's public API schema with exported functions/types. Returns partial results with detailed failure information if some components fail.
100
+ - `bit_create`: Create components using templates with batch support. Supports multiple component names in single call and extensive configuration options (namespace, scope, environment). Validates template existence and prevents conflicts.
101
+ - `bit_query`: Execute read-only Bit commands from a curated whitelist of safe commands (status, list, show, info, diff, log, graph, etc.). Prevents accidental workspace modifications.
102
+ - `bit_execute`: Execute any Bit command including those that modify workspace state. Use with caution as it allows all operations including destructive ones.
103
+ - `bit_commands_list`: Get all available Bit commands with descriptions, grouping, and subcommand discovery for comprehensive command exploration.
104
+ - `bit_command_help`: Get detailed help for specific commands including arguments metadata, flag types, usage examples, and subcommand relationships.
220
105
 
221
106
  > **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.
222
107
 
223
108
  ### Consumer Project Mode (--consumer-project)
224
109
 
225
- 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:
226
-
227
- - `bit_remote_search`: Search for components in remote scopes
228
- - `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)
229
-
230
- In this mode:
231
-
232
- 1. You don't need a Bit workspace initialization
233
- 2. Only these 2 tools are available (no workspace-specific tools)
234
- 3. The `--remote` flag is automatically added to component detail queries
235
- 4. The `cwd` parameter is still required but can be any directory (not necessarily a Bit workspace)
236
- 5. You can still add additional tools with the `--include-additional` flag
237
-
238
- ## Tool Parameters
239
-
240
- All tools accept a `cwd` parameter specifying the workspace path. Additional parameters vary by command.
241
-
242
- ### bit_remote_search
243
-
244
- Search for multiple components in parallel for efficient discovery:
245
-
246
- ```json
247
- {
248
- "queries": ["input", "button", "validation"],
249
- "cwd": "/path/to/workspace"
250
- }
251
- ```
252
-
253
- **Parameters:**
254
-
255
- - `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"]`)
256
- - `cwd` (optional): Path to workspace directory
257
- - `owners` (optional): Filter by specific owners (auto-extracted from workspace.jsonc if not provided)
258
- - `skipAutoOwner` (optional): Disable automatic owner extraction
259
-
260
- **Examples:**
110
+ For projects that consume Bit components as packages but aren't Bit workspaces:
261
111
 
262
- - Form components: `["input", "button", "validation", "dropdown"]`
263
- - Layout components: `["header", "navigation", "footer"]`
264
- - Data display: `["table", "pagination", "filter", "sort"]`
265
- - Button variations: `["button", "btn", "click"]`
112
+ - `bit_remote_search`: Search for components across all organizations available to the logged-in user (requires `bit login`). Executes multiple queries in parallel and deduplicates results.
113
+ - `bit_remote_component_details`: Get comprehensive remote component information by combining show and schema commands. Gracefully handles schema failures while providing basic component details.
266
114
 
267
- ### bit_component_details
268
-
269
- Get detailed information about multiple components in parallel (limited to 5 components max to prevent context overload):
270
-
271
- ```json
272
- {
273
- "componentIds": ["acme.design/ui/button", "acme.design/forms/input"],
274
- "includeSchema": true,
275
- "cwd": "/path/to/workspace"
276
- }
277
- ```
278
-
279
- **Parameters:**
280
-
281
- - `componentIds` (required): Array of component IDs to get details for. Limited to 5 components max. Use full component IDs (e.g., `acme.design/ui/button`)
282
- - `cwd` (required): Path to workspace directory
283
- - `includeSchema` (optional): Include component public API schema (default: false)
284
-
285
- **Examples:**
286
-
287
- - Multiple UI components: `{"componentIds": ["acme.design/ui/button", "acme.design/ui/input", "acme.design/ui/dropdown"], "cwd": "/path/to/workspace"}`
288
- - With schema information: `{"componentIds": ["teambit.base-ui/navigation/link"], "includeSchema": true, "cwd": "/path/to/workspace"}`
289
- - Form components batch: `{"componentIds": ["acme.forms/input", "acme.forms/validation", "acme.forms/submit-button"], "cwd": "/path/to/workspace"}`
290
-
291
- **Response Format:**
292
-
293
- The tool returns a structured response with:
294
-
295
- - `summary`: Statistics about the request (requested, successful, failed counts)
296
- - `components`: Object containing successful component details keyed by component ID
297
- - `failures`: Object containing error messages for failed components (if any)
298
-
299
- **Error Handling:**
300
-
301
- - Returns error if more than 5 components are requested
302
- - Individual component failures don't block the entire request
303
- - Clear error messages indicate which specific components failed and why
304
-
305
- ### bit_create
306
-
307
- Create a new component with template-based generation:
308
-
309
- ```json
310
- {
311
- "templateName": "react",
312
- "componentNames": ["ui/button", "ui/input"],
313
- "namespace": "components",
314
- "scope": "my-org.my-scope",
315
- "cwd": "/path/to/workspace"
316
- }
317
- ```
318
-
319
- **Parameters:**
320
-
321
- - `templateName` (required): The template for generating the component (run `bit templates` for available templates)
322
- - `componentNames` (required): Array of component names to generate
323
- - `cwd` (required): Path to workspace directory
324
- - `namespace` (optional): Sets the component's namespace and nested dirs inside the scope
325
- - `scope` (optional): Sets the component's scope-name (uses default-scope if not provided)
326
- - `aspect` (optional): Aspect-id of the template (helpful when multiple aspects use the same template name)
327
- - `template` (optional): Env-id of the template (alias for --aspect)
328
- - `path` (optional): Relative path in the workspace (default: `<scope>/<namespace>/<name>`)
329
- - `env` (optional): Set the component's environment (overrides env from variants and template)
330
- - `force` (optional): Replace existing files at the target location
331
-
332
- **Examples:**
333
-
334
- - Single React component: `{"templateName": "react", "componentNames": ["ui/button"], "cwd": "/path/to/workspace"}`
335
- - Multiple components with namespace: `{"templateName": "node", "componentNames": ["utils/is-string", "utils/is-number"], "namespace": "utilities", "cwd": "/path/to/workspace"}`
336
- - Component with custom scope: `{"templateName": "mdx", "componentNames": ["docs/getting-started"], "scope": "my-org.docs", "cwd": "/path/to/workspace"}`
337
-
338
- ## Custom Tool Selection
339
-
340
- To customize the available tools:
341
-
342
- ```
343
- # Add specific tools to the available tools
344
- bit mcp-server start --include-additional "build,lint,format,schema"
345
-
346
- # For consumer projects (non-Bit workspaces)
347
- bit mcp-server start --consumer-project
348
-
349
- # Add specific tools to the consumer project set
350
- bit mcp-server start --consumer-project --include-additional "deps,get,preview"
351
- ```
352
-
353
- ### Writing AI Assistant Rules
354
-
355
- The MCP server provides a `rules` command to create instruction files for AI assistants:
356
-
357
- ```bash
358
- bit mcp-server rules [vscode|cursor|windsurf|roo|cline|claude-code] [options]
359
- ```
360
-
361
- 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.
362
-
363
- #### Supported Editors
364
-
365
- - **VS Code**: `bit mcp-server rules vscode` (or just `bit mcp-server rules`)
366
- - **Cursor**: `bit mcp-server rules cursor`
367
- - **Windsurf**: `bit mcp-server rules windsurf`
368
- - **Roo Code**: `bit mcp-server rules roo`
369
- - **Cline**: `bit mcp-server rules cline`
370
- - **Claude Code**: `bit mcp-server rules claude-code`
371
-
372
- #### Configuration Options
373
-
374
- - `--global`: Write rules to global configuration (default: workspace-specific)
375
- - `--print`: Print rules content to screen instead of writing to file
376
- - `--consumer-project`: Generate rules for consumer projects that only use Bit components as packages
377
-
378
- #### Examples
379
-
380
- ```bash
381
- # Basic VS Code rules (workspace level)
382
- bit mcp-server rules
383
-
384
- # Global rules for Cursor
385
- bit mcp-server rules cursor --global
386
-
387
- # Consumer project rules for VS Code
388
- bit mcp-server rules --consumer-project
389
-
390
- # Claude Code rules (creates .claude/bit.md)
391
- bit mcp-server rules claude-code
392
-
393
- # Global Claude Code rules
394
- bit mcp-server rules claude-code --global
395
-
396
- # Global rules for Cline (macOS only)
397
- bit mcp-server rules cline --global
398
-
399
- # Workspace-specific rules for Cline
400
- bit mcp-server rules cline
401
-
402
- # Print rules content to screen for manual setup
403
- bit mcp-server rules --print
404
-
405
- # Print consumer project content for Windsurf (requires manual addition to .windsurfrules)
406
- bit mcp-server rules windsurf --print --consumer-project
407
- ```
@@ -1,102 +1,44 @@
1
1
  # Bit CLI MCP Server
2
2
 
3
- 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.
3
+ The Bit CLI MCP Server provides a [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/mcp) interface to Bit's command-line functionality. It acts as a bridge between MCP clients (such as VS Code, AI tools, or your own applications) and the Bit CLI, enabling programmatic access to Bit workspace and component management operations.
4
4
 
5
- ## Overview
5
+ ## Setup
6
6
 
7
- 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.
7
+ ### Installation
8
8
 
9
- ## Installation
10
-
11
- ### Prerequisites
12
-
13
- - Node.js (v18 or later recommended)
14
- - Bit CLI installed and available in your PATH
15
-
16
- ### Getting Started
17
-
18
- The Bit CLI MCP Server is included with Bit. If you have Bit installed, you can run the server using:
19
-
20
- ```
21
- bit mcp-server start
22
- ```
23
-
24
- ## Usage
25
-
26
- ### Command-Line Options
27
-
28
- ```
29
- bit mcp-server start [options]
30
- ```
31
-
32
- Options:
33
-
34
- - `--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.
35
- - `--include-additional <commands>`: Add specific commands to the available tools (comma-separated list)
36
-
37
- ### Integrating with IDEs
38
-
39
- The easiest way to integrate the MCP server with your IDE is to use the `setup` command:
9
+ The Bit CLI MCP Server is included with Bit. To set it up with your IDE, run:
40
10
 
41
11
  ```bash
42
12
  # Basic setup for VS Code (default)
43
13
  bit mcp-server setup
44
- ```
45
-
46
- 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.
47
14
 
48
- ### Automatic Integration Setup
15
+ # Other supported editors
16
+ bit mcp-server setup [vscode|cursor|windsurf|roo|cline|claude-code]
49
17
 
50
- The **recommended way** to integrate the MCP server with your IDE is using the `setup` command:
51
-
52
- ```bash
53
- bit mcp-server setup [vscode|cursor|windsurf|roo|cline|claude-code] [options]
18
+ # For consumer projects (non-Bit workspaces that only consume Bit components)
19
+ bit mcp-server setup --consumer-project
54
20
  ```
55
21
 
56
- This command automatically configures the MCP server settings in your chosen editor. If no editor is specified, it defaults to VS Code.
57
-
58
- #### Supported Editors
59
-
60
- - **VS Code**: `bit mcp-server setup vscode` (or just `bit mcp-server setup`)
61
- - **Cursor**: `bit mcp-server setup cursor`
62
- - **Windsurf**: `bit mcp-server setup windsurf`
63
- - **Roo Code**: `bit mcp-server setup roo`
64
- - **Cline**: `bit mcp-server setup cline`
65
- - **Claude Code**: `bit mcp-server setup claude-code`
22
+ #### Recommended Setup Steps
66
23
 
67
- #### Configuration Options
68
-
69
- - `--global`: Apply configuration globally (user settings) instead of workspace settings
70
- - `--consumer-project`: Configure for consumer projects
71
- - `--include-additional <commands>`: Add specific commands to the available tools
24
+ After installation, consider these helpful setup steps:
72
25
 
73
- #### Examples
74
-
75
- ```bash
76
- # Basic VS Code setup (workspace level)
77
- bit mcp-server setup
78
-
79
- # Global setup for Cursor
80
- bit mcp-server setup cursor --global
81
-
82
- # Setup with consumer project mode
83
- bit mcp-server setup --consumer-project
84
-
85
- # Setup for Claude Code (creates .mcp.json file)
86
- bit mcp-server setup claude-code
87
-
88
- # Global setup for Claude Code
89
- bit mcp-server setup claude-code --global
90
- ```
26
+ 1. **For new workspaces**: Set your default scope so the search tool knows which organization to search:
27
+ ```bash
28
+ bit scope set <your-org.your-scope>
29
+ ```
91
30
 
92
- #### Manual Configuration
31
+ 2. **Generate rules/instructions** (if you haven't already):
32
+ ```bash
33
+ bit mcp-server rules
34
+ ```
35
+ This provides the AI agent with comprehensive guidance about Bit and MCP server functionality.
93
36
 
94
- If you need to manually configure the settings, here's how to set up VS Code MCP integration:
37
+ 3. **VS Code users**: Make sure to select "agent" mode instead of "ask" mode in the chat interface. For first-time users, open the command palette and search for "MCP: List servers" to find and start the Bit server.
95
38
 
96
- **For workspace-specific configuration:**
39
+ ### Manual Configuration
97
40
 
98
- 1. Create a `.vscode/mcp.json` file in your workspace folder
99
- 2. Add the following configuration:
41
+ For IDEs not supported by the automatic setup, add this MCP server configuration:
100
42
 
101
43
  ```json
102
44
  {
@@ -110,94 +52,39 @@ If you need to manually configure the settings, here's how to set up VS Code MCP
110
52
  }
111
53
  ```
112
54
 
113
- **For global configuration:**
55
+ ### Configuration Options
114
56
 
115
- 1. Open VS Code settings (JSON) by pressing `Ctrl + Shift + P` (or `Cmd + Shift + P` on macOS) and typing `Preferences: Open Settings (JSON)`
116
- 2. Add the following configuration:
117
-
118
- ```json
119
- {
120
- "mcp": {
121
- "servers": {
122
- "bit-cli": {
123
- "type": "stdio",
124
- "command": "bit",
125
- "args": ["mcp-server", "start"]
126
- }
127
- }
128
- }
129
- }
130
- ```
57
+ - `--global`: Apply configuration globally (user settings) instead of workspace settings
58
+ - `--consumer-project`: For non-Bit workspaces that only consume Bit components as packages
59
+ - `--include-additional <commands>`: Add specific commands to the available tools (comma-separated list)
131
60
 
132
- #### Claude Code Setup
61
+ ## Usage
133
62
 
134
- Claude Code uses `.mcp.json` files for MCP server configuration. The setup command creates these files automatically:
63
+ ### Running the Server
135
64
 
136
- **Workspace Configuration:**
65
+ To manually start the server:
137
66
 
138
67
  ```bash
139
- bit mcp-server setup claude-code
140
- ```
141
-
142
- This creates a `.mcp.json` file in your project root:
143
-
144
- ```json
145
- {
146
- "mcpServers": {
147
- "bit": {
148
- "command": "bit",
149
- "args": ["mcp-server", "start"]
150
- }
151
- }
152
- }
153
- ```
154
-
155
- **Global Configuration:**
156
-
157
- ```bash
158
- bit mcp-server setup claude-code --global
68
+ bit mcp-server start [options]
159
69
  ```
160
70
 
161
- This creates/updates the global configuration file:
162
-
163
- - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
164
- - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
165
- - **Linux**: `~/.config/claude/claude_desktop_config.json`
166
-
167
- **Important**: After setup, restart Claude Code for the MCP server to be available.
71
+ Options:
72
+ - `--consumer-project`: For non-Bit workspaces that only consume Bit component packages
73
+ - `--include-additional <commands>`: Add specific commands to the available tools (comma-separated list)
168
74
 
169
- **Claude Code Rules:**
75
+ ### Generating AI Rules
170
76
 
171
- To provide Bit-specific guidance to Claude Code, use the rules command:
77
+ Create instruction files for AI assistants:
172
78
 
173
79
  ```bash
174
- bit mcp-server rules claude-code
175
- ```
176
-
177
- This creates `.claude/bit.md` with Bit instructions. To integrate with your existing `CLAUDE.md`, add:
178
-
179
- ```markdown
180
- @.claude/bit.md
80
+ bit mcp-server rules [vscode|cursor|windsurf|roo|cline|claude-code] [options]
181
81
  ```
182
82
 
183
- This approach ensures your existing `CLAUDE.md` file is never overwritten.
184
-
185
- ### Programmatic Usage
186
-
187
- ```javascript
188
- import { McpClient } from '@modelcontextprotocol/sdk/client';
189
-
190
- async function example() {
191
- const client = await McpClient.spawn('bit', ['mcp-server', 'start']);
192
-
193
- // Call a Bit CLI tool via MCP
194
- const result = await client.callTool('bit_status', { cwd: '/path/to/workspace' });
195
- console.log(result.content[0].text);
83
+ Options:
84
+ - `--global`: Write rules to global configuration
85
+ - `--consumer-project`: Generate rules for consumer projects
86
+ - `--print`: Print rules content to screen
196
87
 
197
- // Close the connection when done
198
- await client.close();
199
- }
200
- ```
201
88
 
202
89
  ## Available Tools
203
90
 
@@ -205,203 +92,23 @@ The Bit CLI MCP Server operates in two modes and provides several specialized to
205
92
 
206
93
  ### Default Mode
207
94
 
208
- In default mode, the server exposes a minimal set of essential tools focused on core functionality. This ensures optimal performance and safety:
95
+ In default mode, the server exposes a minimal set of essential tools focused on core functionality:
209
96
 
210
- - **Always Available Tools:**
211
-
212
- - `bit_remote_search`: Search for components in remote scopes
213
- - `bit_workspace_info`: Get comprehensive workspace information including status, components list, apps, templates, and dependency graph
214
- - `bit_component_details`: Get detailed information about multiple components in parallel (up to 5 max) including basic info and optionally their public API schemas
215
- - `bit_create`: Create a new component (source files and config) using a template with proper argument validation and documentation
216
- - `bit_query`: Execute read-only Bit commands that safely inspect workspace and component state without making modifications
217
- - `bit_execute`: Execute any Bit command, including those that modify workspace or repository state (use with caution)
218
- - `bit_commands_list`: Get all available Bit commands with descriptions and groups (for command discovery)
219
- - `bit_command_help`: Get detailed help for a specific Bit command including syntax, arguments, flags, and usage examples
97
+ - `bit_remote_search`: Search for components with automatic organization detection from workspace's defaultScope (e.g., "teambit" from "teambit.defender"). Executes multiple queries in parallel and deduplicates results. Use arrays of related terms or synonyms for better results.
98
+ - `bit_workspace_info`: Get comprehensive workspace information by combining multiple data sources (status, components, apps, templates, dependency graph). Includes current lane information.
99
+ - `bit_component_details`: Get detailed information about multiple components in parallel (up to 5 max to prevent context overload). Includes documentation from .docs.mdx files, example usage from composition files, and optionally the component's public API schema with exported functions/types. Returns partial results with detailed failure information if some components fail.
100
+ - `bit_create`: Create components using templates with batch support. Supports multiple component names in single call and extensive configuration options (namespace, scope, environment). Validates template existence and prevents conflicts.
101
+ - `bit_query`: Execute read-only Bit commands from a curated whitelist of safe commands (status, list, show, info, diff, log, graph, etc.). Prevents accidental workspace modifications.
102
+ - `bit_execute`: Execute any Bit command including those that modify workspace state. Use with caution as it allows all operations including destructive ones.
103
+ - `bit_commands_list`: Get all available Bit commands with descriptions, grouping, and subcommand discovery for comprehensive command exploration.
104
+ - `bit_command_help`: Get detailed help for specific commands including arguments metadata, flag types, usage examples, and subcommand relationships.
220
105
 
221
106
  > **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.
222
107
 
223
108
  ### Consumer Project Mode (--consumer-project)
224
109
 
225
- 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:
226
-
227
- - `bit_remote_search`: Search for components in remote scopes
228
- - `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)
229
-
230
- In this mode:
231
-
232
- 1. You don't need a Bit workspace initialization
233
- 2. Only these 2 tools are available (no workspace-specific tools)
234
- 3. The `--remote` flag is automatically added to component detail queries
235
- 4. The `cwd` parameter is still required but can be any directory (not necessarily a Bit workspace)
236
- 5. You can still add additional tools with the `--include-additional` flag
237
-
238
- ## Tool Parameters
239
-
240
- All tools accept a `cwd` parameter specifying the workspace path. Additional parameters vary by command.
241
-
242
- ### bit_remote_search
243
-
244
- Search for multiple components in parallel for efficient discovery:
245
-
246
- ```json
247
- {
248
- "queries": ["input", "button", "validation"],
249
- "cwd": "/path/to/workspace"
250
- }
251
- ```
252
-
253
- **Parameters:**
254
-
255
- - `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"]`)
256
- - `cwd` (optional): Path to workspace directory
257
- - `owners` (optional): Filter by specific owners (auto-extracted from workspace.jsonc if not provided)
258
- - `skipAutoOwner` (optional): Disable automatic owner extraction
259
-
260
- **Examples:**
110
+ For projects that consume Bit components as packages but aren't Bit workspaces:
261
111
 
262
- - Form components: `["input", "button", "validation", "dropdown"]`
263
- - Layout components: `["header", "navigation", "footer"]`
264
- - Data display: `["table", "pagination", "filter", "sort"]`
265
- - Button variations: `["button", "btn", "click"]`
112
+ - `bit_remote_search`: Search for components across all organizations available to the logged-in user (requires `bit login`). Executes multiple queries in parallel and deduplicates results.
113
+ - `bit_remote_component_details`: Get comprehensive remote component information by combining show and schema commands. Gracefully handles schema failures while providing basic component details.
266
114
 
267
- ### bit_component_details
268
-
269
- Get detailed information about multiple components in parallel (limited to 5 components max to prevent context overload):
270
-
271
- ```json
272
- {
273
- "componentIds": ["acme.design/ui/button", "acme.design/forms/input"],
274
- "includeSchema": true,
275
- "cwd": "/path/to/workspace"
276
- }
277
- ```
278
-
279
- **Parameters:**
280
-
281
- - `componentIds` (required): Array of component IDs to get details for. Limited to 5 components max. Use full component IDs (e.g., `acme.design/ui/button`)
282
- - `cwd` (required): Path to workspace directory
283
- - `includeSchema` (optional): Include component public API schema (default: false)
284
-
285
- **Examples:**
286
-
287
- - Multiple UI components: `{"componentIds": ["acme.design/ui/button", "acme.design/ui/input", "acme.design/ui/dropdown"], "cwd": "/path/to/workspace"}`
288
- - With schema information: `{"componentIds": ["teambit.base-ui/navigation/link"], "includeSchema": true, "cwd": "/path/to/workspace"}`
289
- - Form components batch: `{"componentIds": ["acme.forms/input", "acme.forms/validation", "acme.forms/submit-button"], "cwd": "/path/to/workspace"}`
290
-
291
- **Response Format:**
292
-
293
- The tool returns a structured response with:
294
-
295
- - `summary`: Statistics about the request (requested, successful, failed counts)
296
- - `components`: Object containing successful component details keyed by component ID
297
- - `failures`: Object containing error messages for failed components (if any)
298
-
299
- **Error Handling:**
300
-
301
- - Returns error if more than 5 components are requested
302
- - Individual component failures don't block the entire request
303
- - Clear error messages indicate which specific components failed and why
304
-
305
- ### bit_create
306
-
307
- Create a new component with template-based generation:
308
-
309
- ```json
310
- {
311
- "templateName": "react",
312
- "componentNames": ["ui/button", "ui/input"],
313
- "namespace": "components",
314
- "scope": "my-org.my-scope",
315
- "cwd": "/path/to/workspace"
316
- }
317
- ```
318
-
319
- **Parameters:**
320
-
321
- - `templateName` (required): The template for generating the component (run `bit templates` for available templates)
322
- - `componentNames` (required): Array of component names to generate
323
- - `cwd` (required): Path to workspace directory
324
- - `namespace` (optional): Sets the component's namespace and nested dirs inside the scope
325
- - `scope` (optional): Sets the component's scope-name (uses default-scope if not provided)
326
- - `aspect` (optional): Aspect-id of the template (helpful when multiple aspects use the same template name)
327
- - `template` (optional): Env-id of the template (alias for --aspect)
328
- - `path` (optional): Relative path in the workspace (default: `<scope>/<namespace>/<name>`)
329
- - `env` (optional): Set the component's environment (overrides env from variants and template)
330
- - `force` (optional): Replace existing files at the target location
331
-
332
- **Examples:**
333
-
334
- - Single React component: `{"templateName": "react", "componentNames": ["ui/button"], "cwd": "/path/to/workspace"}`
335
- - Multiple components with namespace: `{"templateName": "node", "componentNames": ["utils/is-string", "utils/is-number"], "namespace": "utilities", "cwd": "/path/to/workspace"}`
336
- - Component with custom scope: `{"templateName": "mdx", "componentNames": ["docs/getting-started"], "scope": "my-org.docs", "cwd": "/path/to/workspace"}`
337
-
338
- ## Custom Tool Selection
339
-
340
- To customize the available tools:
341
-
342
- ```
343
- # Add specific tools to the available tools
344
- bit mcp-server start --include-additional "build,lint,format,schema"
345
-
346
- # For consumer projects (non-Bit workspaces)
347
- bit mcp-server start --consumer-project
348
-
349
- # Add specific tools to the consumer project set
350
- bit mcp-server start --consumer-project --include-additional "deps,get,preview"
351
- ```
352
-
353
- ### Writing AI Assistant Rules
354
-
355
- The MCP server provides a `rules` command to create instruction files for AI assistants:
356
-
357
- ```bash
358
- bit mcp-server rules [vscode|cursor|windsurf|roo|cline|claude-code] [options]
359
- ```
360
-
361
- 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.
362
-
363
- #### Supported Editors
364
-
365
- - **VS Code**: `bit mcp-server rules vscode` (or just `bit mcp-server rules`)
366
- - **Cursor**: `bit mcp-server rules cursor`
367
- - **Windsurf**: `bit mcp-server rules windsurf`
368
- - **Roo Code**: `bit mcp-server rules roo`
369
- - **Cline**: `bit mcp-server rules cline`
370
- - **Claude Code**: `bit mcp-server rules claude-code`
371
-
372
- #### Configuration Options
373
-
374
- - `--global`: Write rules to global configuration (default: workspace-specific)
375
- - `--print`: Print rules content to screen instead of writing to file
376
- - `--consumer-project`: Generate rules for consumer projects that only use Bit components as packages
377
-
378
- #### Examples
379
-
380
- ```bash
381
- # Basic VS Code rules (workspace level)
382
- bit mcp-server rules
383
-
384
- # Global rules for Cursor
385
- bit mcp-server rules cursor --global
386
-
387
- # Consumer project rules for VS Code
388
- bit mcp-server rules --consumer-project
389
-
390
- # Claude Code rules (creates .claude/bit.md)
391
- bit mcp-server rules claude-code
392
-
393
- # Global Claude Code rules
394
- bit mcp-server rules claude-code --global
395
-
396
- # Global rules for Cline (macOS only)
397
- bit mcp-server rules cline --global
398
-
399
- # Workspace-specific rules for Cline
400
- bit mcp-server rules cline
401
-
402
- # Print rules content to screen for manual setup
403
- bit mcp-server rules --print
404
-
405
- # Print consumer project content for Windsurf (requires manual addition to .windsurfrules)
406
- bit mcp-server rules windsurf --print --consumer-project
407
- ```
@@ -1,5 +1,5 @@
1
1
  ;
2
- import * as overview_0 from '/home/circleci/Library/Caches/Bit/capsules/8891be5ad/teambit.mcp_cli-mcp-server@0.0.90/dist/README.docs.mdx';
2
+ import * as overview_0 from '/home/circleci/Library/Caches/Bit/capsules/8891be5ad/teambit.mcp_cli-mcp-server@0.0.92/dist/README.docs.mdx';
3
3
 
4
4
  export const compositions = [];
5
5
  export const overview = [overview_0];
package/package.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "@teambit/cli-mcp-server",
3
- "version": "0.0.90",
3
+ "version": "0.0.92",
4
4
  "homepage": "https://bit.cloud/teambit/mcp/cli-mcp-server",
5
5
  "main": "dist/index.js",
6
6
  "componentId": {
7
7
  "scope": "teambit.mcp",
8
8
  "name": "cli-mcp-server",
9
- "version": "0.0.90"
9
+ "version": "0.0.92"
10
10
  },
11
11
  "dependencies": {
12
12
  "comment-json": "4.2.5",
@@ -21,7 +21,7 @@
21
21
  "@teambit/cli": "0.0.1268",
22
22
  "@teambit/legacy.constants": "0.0.15",
23
23
  "@teambit/logger": "0.0.1361",
24
- "@teambit/mcp.mcp-config-writer": "0.0.4",
24
+ "@teambit/mcp.mcp-config-writer": "0.0.5",
25
25
  "@teambit/scope.network": "0.0.69"
26
26
  },
27
27
  "devDependencies": {