@tencent-ai/codebuddy-code 2.67.0-next.ed1b89f.20260329 → 2.68.0

package/dist/web-ui/docs/en/cli/mcp.md

@@ -0,0 +1,739 @@
+# MCP (Model Context Protocol) Usage Documentation
+
+## Overview
+
+MCP (Model Context Protocol) is an open standard that allows CodeBuddy to integrate with external tools and data sources. Through MCP, you can extend CodeBuddy's functionality by connecting to various external services, databases, APIs, and more.
+
+## Core Concepts
+
+### MCP Server
+
+An MCP server is an independent process that provides tools, resources, and prompts. CodeBuddy communicates with these servers through different transport protocols.
+
+### MCP Prompts Integration
+
+MCP servers can provide Prompts (prompt templates), which are automatically converted into CodeBuddy's slash commands. When an MCP server is connected:
+
+- Prompts provided by the server are automatically registered as slash commands
+- Command name format: `/server-name:prompt-name`
+- Supports dynamic parameters, collecting user input through an interactive interface
+- Command execution calls the MCP server's `prompts/get` interface to retrieve complete content
+- Supports real-time monitoring of configuration changes, automatically updating the list of available commands
+
+### Transport Types
+
+- **STDIO**: Communication with local processes via standard input/output
+- **SSE**: Communication with remote services via Server-Sent Events
+- **HTTP**: Communication with remote services via HTTP streaming
+
+### Configuration Scope
+
+- **user**: Global user configuration, applied to all projects
+- **project**: Project-level configuration, applied to specific projects
+- **local**: Local configuration, applied only to the current session or workspace
+
+For services with the same name (i.e., configurations with the same name across multiple scopes), the effective priority is: `local > project > user`
+
+### Security Approval Mechanism
+
+MCP servers in the project scope require user approval upon first connection to ensure security. The system displays detailed server information, and users can choose to approve or deny the connection.
+
+#### Approval in Non-Interactive Mode (-p/--print)
+
+In non-interactive mode (such as when using the `-p/--print` parameter), since approval cannot be done through the UI, you need to pre-configure allowed MCP servers using the `--settings` parameter:
+
+```bash
+# Method 1: Allow all project MCP servers
+codebuddy --settings '{"enableAllProjectMcpServers": true}' -p "your prompt"
+
+# Method 2: Allow specific MCP servers
+codebuddy --settings '{"enabledMcpjsonServers": ["server-name-1", "server-name-2"]}' -p "your prompt"
+```
+
+### Tool Permission Management
+
+MCP tools support a complete permission management system that allows precise control over which tools can be used:
+
+#### Permission Rule Types
+
+The permission system supports three rule types (ordered by priority):
+
+1. **Deny rules (deny)** - Block the use of specified tools (highest priority)
+2. **Ask rules (ask)** - Require user confirmation before using tools (overrides allow rules)
+3. **Allow rules (allow)** - Allow tool use without manual approval
+
+#### MCP Permission Rule Format
+
+**Important**: MCP permissions do not support wildcards (*)
+
+##### Server-level Permissions
+```
+mcp__server-name
+```
+- Matches any tool provided by the specified server
+- Server name is the name configured in CodeBuddy
+
+##### Tool-level Permissions
+```
+mcp__server-name__tool-name
+```
+- Matches a specific tool from the specified server
+
+#### Configuration Examples
+
+##### Approve All Tools from a Server
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__github"
+    ]
+  }
+}
+```
+
+##### Approve Only Specific Tools
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__github__get_issue",
+      "mcp__github__list_issues"
+    ]
+  }
+}
+```
+
+##### Deny Specific Tools
+```json
+{
+  "permissions": {
+    "deny": [
+      "mcp__dangerous_server__delete_file"
+    ]
+  }
+}
+```
+
+## Configuration Files
+
+### Configuration File Locations
+
+Configuration files use a priority mechanism. The system searches for files in priority order and reads the first existing file. When writing, if a file already exists, it writes to the first existing file; if none exist, it creates the highest priority file.
+
+#### USER Scope
+
+Priority order (highest to lowest):
+1. `~/.codebuddy/.mcp.json` (recommended)
+2. `~/.codebuddy/mcp.json` (deprecated)
+3. `~/.codebuddy.json` (legacy configuration file)
+
+**Read rules**: The system searches in the above order and reads the first existing file.
+
+**Write rules**:
+- If any of the above files exist, writes to the first existing file
+- If none exist, creates `~/.codebuddy/.mcp.json` (highest priority)
+
+#### PROJECT Scope
+
+Priority order (highest to lowest):
+1. `<project root directory>/.mcp.json` (recommended)
+2. `<project root directory>/mcp.json` (deprecated)
+
+**Read rules**: The system searches in the above order and reads the first existing file.
+
+**Write rules**:
+- If any of the above files exist, writes to the first existing file
+- If none exist, creates `<project root directory>/.mcp.json` (highest priority)
+
+#### LOCAL Scope
+
+Local scope configuration is actually saved in the user scope configuration file, differentiated by project through the `projects` field.
+
+File path: `~/.codebuddy.json#/projects/<workspace_path>`
+
+`#/projects/<workspace_path>` uses JSON Pointer syntax to point to a specific location in the JSON document. For detailed information about JSON Pointer, please refer to: https://datatracker.ietf.org/doc/html/rfc6901
+
+**Note**:
+- The system does not merge multiple configuration files within the same scope; it only uses the first existing file
+
+See the configuration file format section below for examples.
+
+### Configuration File Format
+
+MCP configuration files support the **JSONC (JSON with Comments)** format, allowing comments to be added to configurations for improved readability and maintainability.
+
+#### JSONC Supported Features
+
+- **Single-line comments**: Use `//` to add inline or end-of-line comments
+- **Multi-line comments**: Use `/* */` to add block comments
+- **Trailing commas**: A comma can be added after the last element in arrays and objects
+
+#### Basic Configuration Format
+
+```jsonc
+{
+  // MCP server configuration
+  "mcpServers": {
+    "server-name": {
+      "type": "stdio|sse|http",
+      "command": "command path",
+      "args": ["arg1", "arg2"],
+      "env": {
+        "ENV_VAR": "value"
+      },
+      "url": "http://example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer token"
+      },
+      "description": "Server description"
+    }
+  },
+  // The projects field is only valid in the user scope file and identifies local scope configurations
+  "projects": {
+    "/path/to/project": {
+      "mcpServers": {
+        "local-server": {
+          "type": "stdio",
+          "command": "./local-tool"
+        }
+      }
+    }
+  }
+}
+```
+
+#### Full Example with Comments
+
+```jsonc
+{
+  // MCP Server Configuration for CodeBuddy
+  // This file configures the MCP servers used by the project
+  
+  "mcpServers": {
+    /*
+     * Filesystem Server
+     * Provides file system access capabilities
+     * Docs: https://github.com/modelcontextprotocol/servers
+     */
+    "filesystem": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/path/to/workspace",  // Workspace directory path
+      ],
+      "env": {
+        "DEBUG": "true",  // Enable debug mode
+      },
+    },
+    
+    // HTTP API server example
+    "api-server": {
+      "type": "http",
+      "url": "http://localhost:3000/mcp",  // Local development server
+      "headers": {
+        "Authorization": "Bearer your-token",
+      },
+    },
+  },
+  
+  // Disabled servers list (for reference)
+  "disabledMcpServers": [
+    "deprecated-server",
+  ],
+}
+```
+
+**Note**:
+- Standard JSON format files are still fully compatible
+- Clear error messages are provided when parsing errors occur
+```
+
+**Note**: The `type` field is optional. If not specified, the system will automatically infer based on the configuration content:
+- When the `command` field is present, infers `stdio` type
+- When the `url` field is present, infers `http` type
+
+It is recommended to explicitly specify the `type` field to ensure configuration accuracy.
+
+### Environment Variable Expansion
+
+MCP configuration supports environment variable expansion, allowing you to reference system environment variables in your configuration. This is useful for sharing configurations across teams, managing sensitive information (such as API keys and tokens), and supporting environment-specific configurations (development, testing, production).
+
+#### Supported Syntax
+
+- **`${VAR_NAME}`** - Expands to the value of the environment variable VAR_NAME
+- **`${VAR_NAME:-default_value}`** - Uses the default value if VAR_NAME is not set
+
+#### Variable Naming Rules
+
+- Variable names must start with an uppercase letter or underscore `[A-Z_]`
+- Subsequent characters can only be uppercase letters, digits, or underscores `[A-Z0-9_]*`
+- Variables with lowercase letters, mixed case, or starting with a digit will not be expanded
+
+#### Supported Configuration Fields
+
+Environment variables can be expanded in the following configuration fields:
+
+**STDIO type configuration**:
+- `command` - Executable file path or command
+- `args` - Each argument in the command line arguments list
+- `env` - Environment variable values (keys are not expanded)
+
+**SSE/HTTP/Remote type configuration**:
+- `url` - Service endpoint URL
+- `headers` - HTTP request header values (keys are not expanded)
+
+#### Error Handling
+
+**Behavior when an environment variable is not set**:
+- If the environment variable is not set and **has a default value**, the default value is used
+- If the environment variable is not set and **has no default value**, the original placeholder (`${VAR}`) is preserved, and a WARNING message is reported in diagnostics
+
+This means the configuration will not fail due to missing environment variables; instead, it preserves the placeholder and issues a warning.
+
+#### Example Configurations
+
+**Example 1: STDIO type server with environment variables**
+```json
+{
+  "mcpServers": {
+    "python-tools": {
+      "type": "stdio",
+      "command": "${PYTHON_PATH:-python}",
+      "args": [
+        "-m",
+        "my_mcp_server",
+        "--config",
+        "${CONFIG_DIR:-/etc/config}"
+      ],
+      "env": {
+        "PYTHONPATH": "${PYTHON_LIB_PATH}",
+        "DEBUG": "${DEBUG_MODE:-false}",
+        "API_KEY": "${API_KEY}"
+      }
+    }
+  }
+}
+```
+
+**Example 2: HTTP type server with environment variables and default values**
+```json
+{
+  "mcpServers": {
+    "api-server": {
+      "type": "http",
+      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
+      "headers": {
+        "Authorization": "Bearer ${API_TOKEN}",
+        "X-API-Version": "${API_VERSION:-v1}",
+        "User-Agent": "CodeBuddy/${CODEBUDDY_VERSION:-1.0}"
+      }
+    }
+  }
+}
+```
+
+#### Common Use Cases
+
+1. **Team shared configuration**
+   ```bash
+   # Use environment variables in .mcp.json
+   # Each team member sets environment variables locally
+   export API_TOKEN="their-personal-token"
+   export LOCAL_TOOL_PATH="/home/user/tools"
+   ```
+
+2. **Environment-specific configuration**
+   ```bash
+   # Development environment
+   export API_BASE_URL="http://localhost:3000"
+   
+   # Production environment
+   export API_BASE_URL="https://api.production.com"
+   ```
+
+3. **Managing sensitive information**
+   ```json
+   {
+     "headers": {
+       "Authorization": "Bearer ${MY_API_KEY}"
+     }
+   }
+   ```
+   Store API keys in environment variables instead of writing them directly in configuration files.
+
+#### Diagnostics and Debugging
+
+When environment variables are expanded in configuration, you can understand the expansion results through the following methods:
+
+1. If an environment variable is not set and has no default value, the system will issue a WARNING diagnostic
+2. You can use the `/mcp` command to view MCP server configuration and diagnostic information
+3. Diagnostic messages will list all missing environment variables
+
+**Example diagnostic message**:
+```
+Missing environment variables: API_TOKEN, DATABASE_URL
+```
+
+### Configuration Structure Details
+
+Depending on the transport type, MCP server configurations have different structures:
+
+#### STDIO Type Configuration
+
+Communication with local processes via standard input/output.
+
+| Field | Type | Required | Description |
+|------|------|------|------|
+| `type` | string | Yes | Fixed value `"stdio"` |
+| `command` | string | Yes | Executable file path or command |
+| `args` | Array&lt;string&gt; | No | Command line arguments list |
+| `env` | Object | No | Environment variable key-value pairs |
+| `defer_loading` | boolean | No | Whether to defer tool loading (default false) |
+| `tools` | Object | No | Tool-level configuration, can override server-level settings |
+
+**Example**:
+```json
+{
+  "type": "stdio",
+  "command": "python",
+  "args": ["-m", "my_mcp_server"],
+  "env": {
+    "PYTHONPATH": "/path/to/tools",
+    "DEBUG": "true"
+  }
+}
+```
+
+#### SSE Type Configuration
+
+Communication with remote services via Server-Sent Events.
+
+| Field | Type | Required | Description |
+|------|------|------|------|
+| `type` | string | Yes | Fixed value `"sse"` |
+| `url` | string | Yes | SSE service endpoint URL |
+| `headers` | Object | No | HTTP request header key-value pairs |
+| `defer_loading` | boolean | No | Whether to defer tool loading (default false) |
+| `tools` | Object | No | Tool-level configuration, can override server-level settings |
+
+**Example**:
+```json
+{
+  "type": "sse",
+  "url": "https://api.example.com/mcp/sse",
+  "headers": {
+    "Authorization": "Bearer your-api-token",
+    "X-API-Version": "v1"
+  }
+}
+```
+
+#### HTTP Type Configuration
+
+Communication with remote services via HTTP streaming.
+
+| Field | Type | Required | Description |
+|------|------|------|------|
+| `type` | string | Yes | Fixed value `"http"` |
+| `url` | string | Yes | HTTP service endpoint URL |
+| `headers` | Object | No | HTTP request header key-value pairs |
+| `defer_loading` | boolean | No | Whether to defer tool loading (default false) |
+| `tools` | Object | No | Tool-level configuration, can override server-level settings |
+
+**Example**:
+```json
+{
+  "type": "http",
+  "url": "https://mcp.example.com/api/v1",
+  "headers": {
+    "Authorization": "Bearer secret-token",
+    "Content-Type": "application/json"
+  }
+}
+```
+
+### Deferred Loading (defer_loading)
+
+When an MCP server provides a large number of tools, you can use the `defer_loading` configuration to defer tool loading, reducing context consumption and improving model tool selection accuracy.
+
+#### How It Works
+
+- Tools with `defer_loading: true` are not loaded into the model context during the initial request
+- The model can search for these deferred tools through the `ToolSearch` tool
+- Searched tools are activated and become available in subsequent requests
+- The activation state persists throughout the current session
+
+#### Server-level Configuration
+
+Set all tools on a server to deferred loading:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "type": "stdio",
+      "command": "my-mcp-server",
+      "defer_loading": true
+    }
+  }
+}
+```
+
+#### Tool-level Configuration
+
+You can override the server-level setting for individual tools:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "type": "stdio",
+      "command": "my-mcp-server",
+      "defer_loading": true,
+      "tools": {
+        "frequently_used_tool": {
+          "defer_loading": false
+        }
+      }
+    }
+  }
+}
+```
+
+#### Inheritance Rules
+
+| Server defer_loading | Tool defer_loading | Final Result |
+|---------------------|-------------------|---------|
+| true | Not set | true (inherited) |
+| true | false | false (overridden) |
+| false/Not set | Not set | false |
+| false/Not set | true | true (overridden) |
+
+#### Use Cases
+
+- **Large number of tools**: When an MCP server provides more than 30 tools
+- **Cost reduction**: Reduce token consumption per request
+- **Improved accuracy**: Allow the model to make more accurate selections among fewer tools
+
+## Command Line Usage
+
+### Add MCP Server
+
+#### STDIO Server
+
+```bash
+# Add a local executable
+codebuddy mcp add --scope user my-tool -- /path/to/tool arg1 arg2
+
+# Add a Python script
+codebuddy mcp add --scope project python-tool -- python /path/to/script.py
+```
+
+#### SSE Server
+
+```bash
+# Add an SSE server
+codebuddy mcp add --scope user --transport sse sse-server https://example.com/mcp/sse
+```
+
+#### HTTP Server
+
+```bash
+# Add an HTTP streaming server
+codebuddy mcp add --scope project --transport http http-server https://example.com/mcp/http
+```
+
+### Add Server Using JSON Configuration
+
+```bash
+# Add STDIO type server
+codebuddy mcp add-json --scope user my-server '{"type":"stdio","command":"/usr/local/bin/tool","args":["--verbose"]}'
+
+# Add HTTP type server
+codebuddy mcp add-json --scope user http-server '{"type":"http","url":"https://example.com/mcp","headers":{"Authorization":"Bearer token"}}'
+
+# Add SSE type server
+codebuddy mcp add-json --scope project sse-server '{"type":"sse","url":"https://api.example.com/mcp/sse","headers":{"X-API-Key":"your-api-key"}}'
+
+# Add STDIO server with environment variables
+codebuddy mcp add-json --scope user python-tool '{"type":"stdio","command":"python","args":["-m","my_mcp_server"],"env":{"PYTHONPATH":"/path/to/tools"}}'
+```
+
+### Manage MCP Servers
+
+#### List All Servers
+
+```bash
+# List servers for all scopes
+codebuddy mcp list
+```
+
+#### View Server Details
+
+```bash
+# View specific server information
+codebuddy mcp get my-server
+```
+
+#### Remove Server
+
+```bash
+# Remove a specific server
+codebuddy mcp remove my-server
+
+# Remove a server from a specific scope
+codebuddy mcp remove my-server --scope user
+```
+
+## Best Practices
+
+### 1. Scope Selection
+
+- Use **user** scope to store personal tools and global services
+- Use **project** scope to store project-specific tools
+- Use **local** scope to store temporary or experimental tools
+
+### 2. Security Considerations
+
+- Avoid storing sensitive information in configuration files
+- **Use environment variables to pass authentication information**: Leverage MCP's environment variable expansion feature (`${API_TOKEN}` or `${API_TOKEN:-default}`) to manage sensitive data such as API keys and tokens
+- Regularly review and update server configurations
+- MCP servers in the project scope require user approval before connecting, ensuring security
+- OAuth authorization URLs are validated for security before opening, only supporting http/https protocols
+- Commit configuration files containing environment variable references to version control, but exclude actual environment variable files in `.gitignore`
+
+### 3. Performance Optimization
+
+- Properly configure server timeout durations
+- Avoid running too many STDIO servers simultaneously
+- Use caching mechanisms to reduce redundant connections
+
+### 4. Error Handling
+
+- Monitor server connection status
+- Implement reconnection mechanisms
+- Log and analyze error logs
+
+## Troubleshooting
+
+### Common Issues
+
+#### Server Connection Failure
+
+1. Check if the command path is correct
+2. Verify parameters and environment variables
+3. Confirm network connectivity (for remote servers)
+4. Review server log output
+
+#### Tool Unavailable
+
+1. Confirm that the server has successfully connected
+2. Check tool permission settings
+3. Verify tool compatibility
+
+#### Configuration Not Taking Effect
+
+1. Check configuration file syntax
+2. Confirm scope priority
+3. Restart the CodeBuddy application
+
+## Example Configurations
+
+### Python Tool Server
+
+```json
+{
+  "mcpServers": {
+    "python-tools": {
+      "type": "stdio",
+      "command": "python",
+      "args": ["-m", "my_mcp_server"],
+      "env": {
+        "PYTHONPATH": "/path/to/tools"
+      },
+      "description": "Python toolset"
+    }
+  }
+}
+```
+
+### Remote API Server
+
+```json
+{
+  "mcpServers": {
+    "api-server": {
+      "type": "sse",
+      "url": "https://api.example.com/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer your-token",
+        "X-API-Version": "v1"
+      },
+      "description": "Remote API service"
+    }
+  }
+}
+```
+
+### Node.js Local Server
+
+```json
+{
+  "mcpServers": {
+    "node-server": {
+      "type": "stdio", 
+      "command": "node",
+      "args": ["./mcp-server.js"],
+      "env": {
+        "NODE_ENV": "production"
+      },
+      "description": "Node.js MCP server"
+    }
+  }
+}
+```
+
+## Extension Development
+
+### Creating a Custom MCP Server
+
+1. **Choose Implementation Language**: Python, Node.js, Go, etc.
+2. **Implement MCP Protocol**: Use official SDK or implement yourself
+3. **Define Tool Interfaces**: Describe tool functionality and parameters
+4. **Handle Requests**: Receive and process requests from CodeBuddy
+5. **Return Results**: Return execution results in MCP format
+
+### SDKs and Libraries
+
+- **Python**: `FastMCP`
+- **TypeScript/JavaScript**: `@modelcontextprotocol/sdk`
+- **Other Languages**: Refer to official documentation for implementation
+
+## Configuration Examples
+
+### TAPD
+
+```bash
+codebuddy mcp add --scope user --transport http --header "X-Tapd-Access-Token: TAPD_ACCESS_TOKEN" -- tapd_mcp_http https://mcp-oa.tapd.woa.com/mcp
+```
+
+### Chrome Devtools
+
+```bash
+codebuddy mcp add --scope user chrome-devtools -- npx -y chrome-devtools-mcp@latest
+```
+
+### iWiki
+
+```bash
+codebuddy mcp add --scope user iwiki -- npx -y mcp-remote@latest https://prod.mcp.it.woa.com/app_iwiki_mcp/mcp3
+```
+
+## Related Links
+
+- [MCP Official Documentation](https://modelcontextprotocol.io/)
+- [MCP GitHub Repository](https://github.com/modelcontextprotocol)
+- [CodeBuddy Official Documentation](https://cnb.cool/codebuddy/codebuddy-code/-/blob/main/docs)