mirror of
https://github.com/QwenLM/qwen-code.git
synced 2025-12-19 09:33:53 +00:00
feat: restructure docs
This commit is contained in:
pomelo-nwu
11
docs/developers/tools/_meta.ts
Normal file
11
docs/developers/tools/_meta.ts
Normal file
@@ -0,0 +1,11 @@
|
||||
export default {
|
||||
index: 'Introduction',
|
||||
'file-system': 'File System',
|
||||
'multi-file': 'Multi-File Read',
|
||||
shell: 'Shell',
|
||||
'todo-write': 'Todo Write',
|
||||
'web-fetch': 'Web Fetch',
|
||||
'web-search': 'Web Search',
|
||||
memory: 'Memory',
|
||||
'mcp-server': 'MCP Servers',
|
||||
};
|
||||
167
docs/developers/tools/file-system.md
Normal file
167
docs/developers/tools/file-system.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# Qwen Code file system tools
|
||||
|
||||
Qwen Code provides a comprehensive suite of tools for interacting with the local file system. These tools allow the model to read from, write to, list, search, and modify files and directories, all under your control and typically with confirmation for sensitive operations.
|
||||
|
||||
**Note:** All file system tools operate within a `rootDirectory` (usually the current working directory where you launched the CLI) for security. Paths that you provide to these tools are generally expected to be absolute or are resolved relative to this root directory.
|
||||
|
||||
## 1. `list_directory` (ListFiles)
|
||||
|
||||
`list_directory` lists the names of files and subdirectories directly within a specified directory path. It can optionally ignore entries matching provided glob patterns.
|
||||
|
||||
- **Tool name:** `list_directory`
|
||||
- **Display name:** ListFiles
|
||||
- **File:** `ls.ts`
|
||||
- **Parameters:**
|
||||
- `path` (string, required): The absolute path to the directory to list.
|
||||
- `ignore` (array of strings, optional): A list of glob patterns to exclude from the listing (e.g., `["*.log", ".git"]`).
|
||||
- `respect_git_ignore` (boolean, optional): Whether to respect `.gitignore` patterns when listing files. Defaults to `true`.
|
||||
- **Behavior:**
|
||||
- Returns a list of file and directory names.
|
||||
- Indicates whether each entry is a directory.
|
||||
- Sorts entries with directories first, then alphabetically.
|
||||
- **Output (`llmContent`):** A string like: `Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png`
|
||||
- **Confirmation:** No.
|
||||
|
||||
## 2. `read_file` (ReadFile)
|
||||
|
||||
`read_file` reads and returns the content of a specified file. This tool handles text, images (PNG, JPG, GIF, WEBP, SVG, BMP), and PDF files. For text files, it can read specific line ranges. Other binary file types are generally skipped.
|
||||
|
||||
- **Tool name:** `read_file`
|
||||
- **Display name:** ReadFile
|
||||
- **File:** `read-file.ts`
|
||||
- **Parameters:**
|
||||
- `path` (string, required): The absolute path to the file to read.
|
||||
- `offset` (number, optional): For text files, the 0-based line number to start reading from. Requires `limit` to be set.
|
||||
- `limit` (number, optional): For text files, the maximum number of lines to read. If omitted, reads a default maximum (e.g., 2000 lines) or the entire file if feasible.
|
||||
- **Behavior:**
|
||||
- For text files: Returns the content. If `offset` and `limit` are used, returns only that slice of lines. Indicates if content was truncated due to line limits or line length limits.
|
||||
- For image and PDF files: Returns the file content as a base64-encoded data structure suitable for model consumption.
|
||||
- For other binary files: Attempts to identify and skip them, returning a message indicating it's a generic binary file.
|
||||
- **Output:** (`llmContent`):
|
||||
- For text files: The file content, potentially prefixed with a truncation message (e.g., `[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`).
|
||||
- For image/PDF files: An object containing `inlineData` with `mimeType` and base64 `data` (e.g., `{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }`).
|
||||
- For other binary files: A message like `Cannot display content of binary file: /path/to/data.bin`.
|
||||
- **Confirmation:** No.
|
||||
|
||||
## 3. `write_file` (WriteFile)
|
||||
|
||||
`write_file` writes content to a specified file. If the file exists, it will be overwritten. If the file doesn't exist, it (and any necessary parent directories) will be created.
|
||||
|
||||
- **Tool name:** `write_file`
|
||||
- **Display name:** WriteFile
|
||||
- **File:** `write-file.ts`
|
||||
- **Parameters:**
|
||||
- `file_path` (string, required): The absolute path to the file to write to.
|
||||
- `content` (string, required): The content to write into the file.
|
||||
- **Behavior:**
|
||||
- Writes the provided `content` to the `file_path`.
|
||||
- Creates parent directories if they don't exist.
|
||||
- **Output (`llmContent`):** A success message, e.g., `Successfully overwrote file: /path/to/your/file.txt` or `Successfully created and wrote to new file: /path/to/new/file.txt`.
|
||||
- **Confirmation:** Yes. Shows a diff of changes and asks for user approval before writing.
|
||||
|
||||
## 4. `glob` (Glob)
|
||||
|
||||
`glob` finds files matching specific glob patterns (e.g., `src/**/*.ts`, `*.md`), returning absolute paths sorted by modification time (newest first).
|
||||
|
||||
- **Tool name:** `glob`
|
||||
- **Display name:** Glob
|
||||
- **File:** `glob.ts`
|
||||
- **Parameters:**
|
||||
- `pattern` (string, required): The glob pattern to match against (e.g., `"*.py"`, `"src/**/*.js"`).
|
||||
- `path` (string, optional): The directory to search in. If not specified, the current working directory will be used.
|
||||
- **Behavior:**
|
||||
- Searches for files matching the glob pattern within the specified directory.
|
||||
- Returns a list of absolute paths, sorted with the most recently modified files first.
|
||||
- Respects .gitignore and .qwenignore patterns by default.
|
||||
- Limits results to 100 files to prevent context overflow.
|
||||
- **Output (`llmContent`):** A message like: `Found 5 file(s) matching "*.ts" within /path/to/search/dir, sorted by modification time (newest first):\n---\n/path/to/file1.ts\n/path/to/subdir/file2.ts\n---\n[95 files truncated] ...`
|
||||
- **Confirmation:** No.
|
||||
|
||||
## 5. `grep_search` (Grep)
|
||||
|
||||
`grep_search` searches for a regular expression pattern within the content of files in a specified directory. Can filter files by a glob pattern. Returns the lines containing matches, along with their file paths and line numbers.
|
||||
|
||||
- **Tool name:** `grep_search`
|
||||
- **Display name:** Grep
|
||||
- **File:** `ripGrep.ts` (with `grep.ts` as fallback)
|
||||
- **Parameters:**
|
||||
- `pattern` (string, required): The regular expression pattern to search for in file contents (e.g., `"function\\s+myFunction"`, `"log.*Error"`).
|
||||
- `path` (string, optional): File or directory to search in. Defaults to current working directory.
|
||||
- `glob` (string, optional): Glob pattern to filter files (e.g. `"*.js"`, `"src/**/*.{ts,tsx}"`).
|
||||
- `limit` (number, optional): Limit output to first N matching lines. Optional - shows all matches if not specified.
|
||||
- **Behavior:**
|
||||
- Uses ripgrep for fast search when available; otherwise falls back to a JavaScript-based search implementation.
|
||||
- Returns matching lines with file paths and line numbers.
|
||||
- Case-insensitive by default.
|
||||
- Respects .gitignore and .qwenignore patterns.
|
||||
- Limits output to prevent context overflow.
|
||||
- **Output (`llmContent`):** A formatted string of matches, e.g.:
|
||||
|
||||
```
|
||||
Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"):
|
||||
---
|
||||
src/utils.ts:15:export function myFunction() {
|
||||
src/utils.ts:22: myFunction.call();
|
||||
src/index.ts:5:import { myFunction } from './utils';
|
||||
---
|
||||
|
||||
[0 lines truncated] ...
|
||||
```
|
||||
|
||||
- **Confirmation:** No.
|
||||
|
||||
### `grep_search` examples
|
||||
|
||||
Search for a pattern with default result limiting:
|
||||
|
||||
```
|
||||
grep_search(pattern="function\\s+myFunction", path="src")
|
||||
```
|
||||
|
||||
Search for a pattern with custom result limiting:
|
||||
|
||||
```
|
||||
grep_search(pattern="function", path="src", limit=50)
|
||||
```
|
||||
|
||||
Search for a pattern with file filtering and custom result limiting:
|
||||
|
||||
```
|
||||
grep_search(pattern="function", glob="*.js", limit=10)
|
||||
```
|
||||
|
||||
## 6. `edit` (Edit)
|
||||
|
||||
`edit` replaces text within a file. By default it requires `old_string` to match a single unique location; set `replace_all` to `true` when you intentionally want to change every occurrence. This tool is designed for precise, targeted changes and requires significant context around the `old_string` to ensure it modifies the correct location.
|
||||
|
||||
- **Tool name:** `edit`
|
||||
- **Display name:** Edit
|
||||
- **File:** `edit.ts`
|
||||
- **Parameters:**
|
||||
- `file_path` (string, required): The absolute path to the file to modify.
|
||||
- `old_string` (string, required): The exact literal text to replace.
|
||||
|
||||
**CRITICAL:** This string must uniquely identify the single instance to change. It should include at least 3 lines of context _before_ and _after_ the target text, matching whitespace and indentation precisely. If `old_string` is empty, the tool attempts to create a new file at `file_path` with `new_string` as content.
|
||||
|
||||
- `new_string` (string, required): The exact literal text to replace `old_string` with.
|
||||
- `replace_all` (boolean, optional): Replace all occurrences of `old_string`. Defaults to `false`.
|
||||
|
||||
- **Behavior:**
|
||||
- If `old_string` is empty and `file_path` does not exist, creates a new file with `new_string` as content.
|
||||
- If `old_string` is provided, it reads the `file_path` and attempts to find exactly one occurrence unless `replace_all` is true.
|
||||
- If the match is unique (or `replace_all` is true), it replaces the text with `new_string`.
|
||||
- **Enhanced Reliability (Multi-Stage Edit Correction):** To significantly improve the success rate of edits, especially when the model-provided `old_string` might not be perfectly precise, the tool incorporates a multi-stage edit correction mechanism.
|
||||
- If the initial `old_string` isn't found or matches multiple locations, the tool can leverage the Qwen model to iteratively refine `old_string` (and potentially `new_string`).
|
||||
- This self-correction process attempts to identify the unique segment the model intended to modify, making the `edit` operation more robust even with slightly imperfect initial context.
|
||||
- **Failure conditions:** Despite the correction mechanism, the tool will fail if:
|
||||
- `file_path` is not absolute or is outside the root directory.
|
||||
- `old_string` is not empty, but the `file_path` does not exist.
|
||||
- `old_string` is empty, but the `file_path` already exists.
|
||||
- `old_string` is not found in the file after attempts to correct it.
|
||||
- `old_string` is found multiple times, `replace_all` is false, and the self-correction mechanism cannot resolve it to a single, unambiguous match.
|
||||
- **Output (`llmContent`):**
|
||||
- On success: `Successfully modified file: /path/to/file.txt (1 replacements).` or `Created new file: /path/to/new_file.txt with provided content.`
|
||||
- On failure: An error message explaining the reason (e.g., `Failed to edit, 0 occurrences found...`, `Failed to edit because the text matches multiple locations...`).
|
||||
- **Confirmation:** Yes. Shows a diff of the proposed changes and asks for user approval before writing to the file.
|
||||
|
||||
These file system tools provide a foundation for Qwen Code to understand and interact with your local project context.
|
||||
56
docs/developers/tools/index.md
Normal file
56
docs/developers/tools/index.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# Qwen Code tools
|
||||
|
||||
Qwen Code includes built-in tools that the model uses to interact with your local environment, access information, and perform actions. These tools enhance the CLI's capabilities, enabling it to go beyond text generation and assist with a wide range of tasks.
|
||||
|
||||
## Overview of Qwen Code tools
|
||||
|
||||
In the context of Qwen Code, tools are specific functions or modules that the model can request to be executed. For example, if you ask the model to "Summarize the contents of `my_document.txt`," it will likely identify the need to read that file and will request the execution of the `read_file` tool.
|
||||
|
||||
The core component (`packages/core`) manages these tools, presents their definitions (schemas) to the model, executes them when requested, and returns the results to the model for further processing into a user-facing response.
|
||||
|
||||
These tools provide the following capabilities:
|
||||
|
||||
- **Access local information:** Tools allow the model to access your local file system, read file contents, list directories, etc.
|
||||
- **Execute commands:** With tools like `run_shell_command`, the model can run shell commands (with appropriate safety measures and user confirmation).
|
||||
- **Interact with the web:** Tools can fetch content from URLs.
|
||||
- **Take actions:** Tools can modify files, write new files, or perform other actions on your system (again, typically with safeguards).
|
||||
- **Ground responses:** By using tools to fetch real-time or specific local data, responses can be more accurate, relevant, and grounded in your actual context.
|
||||
|
||||
## How to use Qwen Code tools
|
||||
|
||||
To use Qwen Code tools, provide a prompt to the CLI. The process works as follows:
|
||||
|
||||
1. You provide a prompt to the CLI.
|
||||
2. The CLI sends the prompt to the core.
|
||||
3. The core, along with your prompt and conversation history, sends a list of available tools and their descriptions/schemas to the configured model API.
|
||||
4. The model analyzes your request. If it determines that a tool is needed, its response will include a request to execute a specific tool with certain parameters.
|
||||
5. The core receives this tool request, validates it, and (often after user confirmation for sensitive operations) executes the tool.
|
||||
6. The output from the tool is sent back to the model.
|
||||
7. The model uses the tool's output to formulate its final answer, which is then sent back through the core to the CLI and displayed to you.
|
||||
|
||||
You will typically see messages in the CLI indicating when a tool is being called and whether it succeeded or failed.
|
||||
|
||||
## Security and confirmation
|
||||
|
||||
Many tools, especially those that can modify your file system or execute commands (`write_file`, `edit`, `run_shell_command`), are designed with safety in mind. Qwen Code will typically:
|
||||
|
||||
- **Require confirmation:** Prompt you before executing potentially sensitive operations, showing you what action is about to be taken.
|
||||
- **Utilize sandboxing:** All tools are subject to restrictions enforced by sandboxing (see [Sandboxing in Qwen Code](../sandbox.md)). This means that when operating in a sandbox, any tools (including MCP servers) you wish to use must be available _inside_ the sandbox environment. For example, to run an MCP server through `npx`, the `npx` executable must be installed within the sandbox's Docker image or be available in the `sandbox-exec` environment.
|
||||
|
||||
It's important to always review confirmation prompts carefully before allowing a tool to proceed.
|
||||
|
||||
## Learn more about Qwen Code's tools
|
||||
|
||||
Qwen Code's built-in tools can be broadly categorized as follows:
|
||||
|
||||
- **[File System Tools](./file-system.md):** For interacting with files and directories (reading, writing, listing, searching, etc.).
|
||||
- **[Shell Tool](./shell.md) (`run_shell_command`):** For executing shell commands.
|
||||
- **[Web Fetch Tool](./web-fetch.md) (`web_fetch`):** For retrieving content from URLs.
|
||||
- **[Web Search Tool](./web-search.md) (`web_search`):** For searching the web.
|
||||
- **[Multi-File Read Tool](./multi-file.md) (`read_many_files`):** A specialized tool for reading content from multiple files or directories, often used by the `@` command.
|
||||
- **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling information across sessions.
|
||||
- **[Todo Write Tool](./todo-write.md) (`todo_write`):** For creating and managing structured task lists during coding sessions.
|
||||
|
||||
Additionally, these tools incorporate:
|
||||
|
||||
- **[MCP servers](./mcp-server.md)**: MCP servers act as a bridge between the model and your local environment or other services like APIs.
|
||||
866
docs/developers/tools/mcp-server.md
Normal file
866
docs/developers/tools/mcp-server.md
Normal file
@@ -0,0 +1,866 @@
|
||||
# MCP servers with Qwen Code
|
||||
|
||||
This document provides a guide to configuring and using Model Context Protocol (MCP) servers with Qwen Code.
|
||||
|
||||
## What is an MCP server?
|
||||
|
||||
An MCP server is an application that exposes tools and resources to the CLI through the Model Context Protocol, allowing it to interact with external systems and data sources. MCP servers act as a bridge between the model and your local environment or other services like APIs.
|
||||
|
||||
An MCP server enables the CLI to:
|
||||
|
||||
- **Discover tools:** List available tools, their descriptions, and parameters through standardized schema definitions.
|
||||
- **Execute tools:** Call specific tools with defined arguments and receive structured responses.
|
||||
- **Access resources:** Read data from specific resources (though the CLI primarily focuses on tool execution).
|
||||
|
||||
With an MCP server, you can extend the CLI's capabilities to perform actions beyond its built-in features, such as interacting with databases, APIs, custom scripts, or specialized workflows.
|
||||
|
||||
## Core Integration Architecture
|
||||
|
||||
Qwen Code integrates with MCP servers through a sophisticated discovery and execution system built into the core package (`packages/core/src/tools/`):
|
||||
|
||||
### Discovery Layer (`mcp-client.ts`)
|
||||
|
||||
The discovery process is orchestrated by `discoverMcpTools()`, which:
|
||||
|
||||
1. **Iterates through configured servers** from your `settings.json` `mcpServers` configuration
|
||||
2. **Establishes connections** using appropriate transport mechanisms (Stdio, SSE, or Streamable HTTP)
|
||||
3. **Fetches tool definitions** from each server using the MCP protocol
|
||||
4. **Sanitizes and validates** tool schemas for compatibility with the Qwen API
|
||||
5. **Registers tools** in the global tool registry with conflict resolution
|
||||
|
||||
### Execution Layer (`mcp-tool.ts`)
|
||||
|
||||
Each discovered MCP tool is wrapped in a `DiscoveredMCPTool` instance that:
|
||||
|
||||
- **Handles confirmation logic** based on server trust settings and user preferences
|
||||
- **Manages tool execution** by calling the MCP server with proper parameters
|
||||
- **Processes responses** for both the LLM context and user display
|
||||
- **Maintains connection state** and handles timeouts
|
||||
|
||||
### Transport Mechanisms
|
||||
|
||||
The CLI supports three MCP transport types:
|
||||
|
||||
- **Stdio Transport:** Spawns a subprocess and communicates via stdin/stdout
|
||||
- **SSE Transport:** Connects to Server-Sent Events endpoints
|
||||
- **Streamable HTTP Transport:** Uses HTTP streaming for communication
|
||||
|
||||
## How to set up your MCP server
|
||||
|
||||
Qwen Code uses the `mcpServers` configuration in your `settings.json` file to locate and connect to MCP servers. This configuration supports multiple servers with different transport mechanisms.
|
||||
|
||||
### Configure the MCP server in settings.json
|
||||
|
||||
You can configure MCP servers in your `settings.json` file in two main ways: through the top-level `mcpServers` object for specific server definitions, and through the `mcp` object for global settings that control server discovery and execution.
|
||||
|
||||
#### Global MCP Settings (`mcp`)
|
||||
|
||||
The `mcp` object in your `settings.json` allows you to define global rules for all MCP servers.
|
||||
|
||||
- **`mcp.serverCommand`** (string): A global command to start an MCP server.
|
||||
- **`mcp.allowed`** (array of strings): A list of MCP server names to allow. If this is set, only servers from this list (matching the keys in the `mcpServers` object) will be connected to.
|
||||
- **`mcp.excluded`** (array of strings): A list of MCP server names to exclude. Servers in this list will not be connected to.
|
||||
|
||||
**Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"allowed": ["my-trusted-server"],
|
||||
"excluded": ["experimental-server"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Server-Specific Configuration (`mcpServers`)
|
||||
|
||||
The `mcpServers` object is where you define each individual MCP server you want the CLI to connect to.
|
||||
|
||||
### Configuration Structure
|
||||
|
||||
Add an `mcpServers` object to your `settings.json` file:
|
||||
|
||||
```json
|
||||
{ ...file contains other config objects
|
||||
"mcpServers": {
|
||||
"serverName": {
|
||||
"command": "path/to/server",
|
||||
"args": ["--arg1", "value1"],
|
||||
"env": {
|
||||
"API_KEY": "$MY_API_TOKEN"
|
||||
},
|
||||
"cwd": "./server-directory",
|
||||
"timeout": 30000,
|
||||
"trust": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Configuration Properties
|
||||
|
||||
Each server configuration supports the following properties:
|
||||
|
||||
#### Required (one of the following)
|
||||
|
||||
- **`command`** (string): Path to the executable for Stdio transport
|
||||
- **`url`** (string): SSE endpoint URL (e.g., `"http://localhost:8080/sse"`)
|
||||
- **`httpUrl`** (string): HTTP streaming endpoint URL
|
||||
|
||||
#### Optional
|
||||
|
||||
- **`args`** (string[]): Command-line arguments for Stdio transport
|
||||
- **`headers`** (object): Custom HTTP headers when using `url` or `httpUrl`
|
||||
- **`env`** (object): Environment variables for the server process. Values can reference environment variables using `$VAR_NAME` or `${VAR_NAME}` syntax
|
||||
- **`cwd`** (string): Working directory for Stdio transport
|
||||
- **`timeout`** (number): Request timeout in milliseconds (default: 600,000ms = 10 minutes)
|
||||
- **`trust`** (boolean): When `true`, bypasses all tool call confirmations for this server (default: `false`)
|
||||
- **`includeTools`** (string[]): List of tool names to include from this MCP server. When specified, only the tools listed here will be available from this server (allowlist behavior). If not specified, all tools from the server are enabled by default.
|
||||
- **`excludeTools`** (string[]): List of tool names to exclude from this MCP server. Tools listed here will not be available to the model, even if they are exposed by the server. **Note:** `excludeTools` takes precedence over `includeTools` - if a tool is in both lists, it will be excluded.
|
||||
- **`targetAudience`** (string): The OAuth Client ID allowlisted on the IAP-protected application you are trying to access. Used with `authProviderType: 'service_account_impersonation'`.
|
||||
- **`targetServiceAccount`** (string): The email address of the Google Cloud Service Account to impersonate. Used with `authProviderType: 'service_account_impersonation'`.
|
||||
|
||||
### OAuth Support for Remote MCP Servers
|
||||
|
||||
Qwen Code supports OAuth 2.0 authentication for remote MCP servers using SSE or HTTP transports. This enables secure access to MCP servers that require authentication.
|
||||
|
||||
#### Automatic OAuth Discovery
|
||||
|
||||
For servers that support OAuth discovery, you can omit the OAuth configuration and let the CLI discover it automatically:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"discoveredServer": {
|
||||
"url": "https://api.example.com/sse"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The CLI will automatically:
|
||||
|
||||
- Detect when a server requires OAuth authentication (401 responses)
|
||||
- Discover OAuth endpoints from server metadata
|
||||
- Perform dynamic client registration if supported
|
||||
- Handle the OAuth flow and token management
|
||||
|
||||
#### Authentication Flow
|
||||
|
||||
When connecting to an OAuth-enabled server:
|
||||
|
||||
1. **Initial connection attempt** fails with 401 Unauthorized
|
||||
2. **OAuth discovery** finds authorization and token endpoints
|
||||
3. **Browser opens** for user authentication (requires local browser access)
|
||||
4. **Authorization code** is exchanged for access tokens
|
||||
5. **Tokens are stored** securely for future use
|
||||
6. **Connection retry** succeeds with valid tokens
|
||||
|
||||
#### Browser Redirect Requirements
|
||||
|
||||
**Important:** OAuth authentication requires that your local machine can:
|
||||
|
||||
- Open a web browser for authentication
|
||||
- Receive redirects on `http://localhost:7777/oauth/callback`
|
||||
|
||||
This feature will not work in:
|
||||
|
||||
- Headless environments without browser access
|
||||
- Remote SSH sessions without X11 forwarding
|
||||
- Containerized environments without browser support
|
||||
|
||||
#### Managing OAuth Authentication
|
||||
|
||||
Use the `/mcp auth` command to manage OAuth authentication:
|
||||
|
||||
```bash
|
||||
# List servers requiring authentication
|
||||
/mcp auth
|
||||
|
||||
# Authenticate with a specific server
|
||||
/mcp auth serverName
|
||||
|
||||
# Re-authenticate if tokens expire
|
||||
/mcp auth serverName
|
||||
```
|
||||
|
||||
#### OAuth Configuration Properties
|
||||
|
||||
- **`enabled`** (boolean): Enable OAuth for this server
|
||||
- **`clientId`** (string): OAuth client identifier (optional with dynamic registration)
|
||||
- **`clientSecret`** (string): OAuth client secret (optional for public clients)
|
||||
- **`authorizationUrl`** (string): OAuth authorization endpoint (auto-discovered if omitted)
|
||||
- **`tokenUrl`** (string): OAuth token endpoint (auto-discovered if omitted)
|
||||
- **`scopes`** (string[]): Required OAuth scopes
|
||||
- **`redirectUri`** (string): Custom redirect URI (defaults to `http://localhost:7777/oauth/callback`)
|
||||
- **`tokenParamName`** (string): Query parameter name for tokens in SSE URLs
|
||||
- **`audiences`** (string[]): Audiences the token is valid for
|
||||
|
||||
#### Token Management
|
||||
|
||||
OAuth tokens are automatically:
|
||||
|
||||
- **Stored securely** in `~/.qwen/mcp-oauth-tokens.json`
|
||||
- **Refreshed** when expired (if refresh tokens are available)
|
||||
- **Validated** before each connection attempt
|
||||
- **Cleaned up** when invalid or expired
|
||||
|
||||
#### Authentication Provider Type
|
||||
|
||||
You can specify the authentication provider type using the `authProviderType` property:
|
||||
|
||||
- **`authProviderType`** (string): Specifies the authentication provider. Can be one of the following:
|
||||
- **`dynamic_discovery`** (default): The CLI will automatically discover the OAuth configuration from the server.
|
||||
- **`google_credentials`**: The CLI will use the Google Application Default Credentials (ADC) to authenticate with the server. When using this provider, you must specify the required scopes.
|
||||
- **`service_account_impersonation`**: The CLI will impersonate a Google Cloud Service Account to authenticate with the server. This is useful for accessing IAP-protected services (this was specifically designed for Cloud Run services).
|
||||
|
||||
#### Google Credentials
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"googleCloudServer": {
|
||||
"httpUrl": "https://my-gcp-service.run.app/mcp",
|
||||
"authProviderType": "google_credentials",
|
||||
"oauth": {
|
||||
"scopes": ["https://www.googleapis.com/auth/userinfo.email"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Service Account Impersonation
|
||||
|
||||
To authenticate with a server using Service Account Impersonation, you must set the `authProviderType` to `service_account_impersonation` and provide the following properties:
|
||||
|
||||
- **`targetAudience`** (string): The OAuth Client ID allowslisted on the IAP-protected application you are trying to access.
|
||||
- **`targetServiceAccount`** (string): The email address of the Google Cloud Service Account to impersonate.
|
||||
|
||||
The CLI will use your local Application Default Credentials (ADC) to generate an OIDC ID token for the specified service account and audience. This token will then be used to authenticate with the MCP server.
|
||||
|
||||
#### Setup Instructions
|
||||
|
||||
1. **[Create](https://cloud.google.com/iap/docs/oauth-client-creation) or use an existing OAuth 2.0 client ID.** To use an existing OAuth 2.0 client ID, follow the steps in [How to share OAuth Clients](https://cloud.google.com/iap/docs/sharing-oauth-clients).
|
||||
2. **Add the OAuth ID to the allowlist for [programmatic access](https://cloud.google.com/iap/docs/sharing-oauth-clients#programmatic_access) for the application.** Since Cloud Run is not yet a supported resource type in gcloud iap, you must allowlist the Client ID on the project.
|
||||
3. **Create a service account.** [Documentation](https://cloud.google.com/iam/docs/service-accounts-create#creating), [Cloud Console Link](https://console.cloud.google.com/iam-admin/serviceaccounts)
|
||||
4. **Add both the service account and users to the IAP Policy** in the "Security" tab of the Cloud Run service itself or via gcloud.
|
||||
5. **Grant all users and groups** who will access the MCP Server the necessary permissions to [impersonate the service account](https://cloud.google.com/docs/authentication/use-service-account-impersonation) (i.e., `roles/iam.serviceAccountTokenCreator`).
|
||||
6. **[Enable](https://console.cloud.google.com/apis/library/iamcredentials.googleapis.com) the IAM Credentials API** for your project.
|
||||
|
||||
### Example Configurations
|
||||
|
||||
#### Python MCP Server (Stdio)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"pythonTools": {
|
||||
"command": "python",
|
||||
"args": ["-m", "my_mcp_server", "--port", "8080"],
|
||||
"cwd": "./mcp-servers/python",
|
||||
"env": {
|
||||
"DATABASE_URL": "$DB_CONNECTION_STRING",
|
||||
"API_KEY": "${EXTERNAL_API_KEY}"
|
||||
},
|
||||
"timeout": 15000
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Node.js MCP Server (Stdio)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"nodeServer": {
|
||||
"command": "node",
|
||||
"args": ["dist/server.js", "--verbose"],
|
||||
"cwd": "./mcp-servers/node",
|
||||
"trust": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Docker-based MCP Server
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"dockerizedServer": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-e",
|
||||
"API_KEY",
|
||||
"-v",
|
||||
"${PWD}:/workspace",
|
||||
"my-mcp-server:latest"
|
||||
],
|
||||
"env": {
|
||||
"API_KEY": "$EXTERNAL_SERVICE_TOKEN"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### HTTP-based MCP Server
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"httpServer": {
|
||||
"httpUrl": "http://localhost:3000/mcp",
|
||||
"timeout": 5000
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### HTTP-based MCP Server with Custom Headers
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"httpServerWithAuth": {
|
||||
"httpUrl": "http://localhost:3000/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer your-api-token",
|
||||
"X-Custom-Header": "custom-value",
|
||||
"Content-Type": "application/json"
|
||||
},
|
||||
"timeout": 5000
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### MCP Server with Tool Filtering
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"filteredServer": {
|
||||
"command": "python",
|
||||
"args": ["-m", "my_mcp_server"],
|
||||
"includeTools": ["safe_tool", "file_reader", "data_processor"],
|
||||
// "excludeTools": ["dangerous_tool", "file_deleter"],
|
||||
"timeout": 30000
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SSE MCP Server with SA Impersonation
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"myIapProtectedServer": {
|
||||
"url": "https://my-iap-service.run.app/sse",
|
||||
"authProviderType": "service_account_impersonation",
|
||||
"targetAudience": "YOUR_IAP_CLIENT_ID.apps.googleusercontent.com",
|
||||
"targetServiceAccount": "your-sa@your-project.iam.gserviceaccount.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Discovery Process Deep Dive
|
||||
|
||||
When Qwen Code starts, it performs MCP server discovery through the following detailed process:
|
||||
|
||||
### 1. Server Iteration and Connection
|
||||
|
||||
For each configured server in `mcpServers`:
|
||||
|
||||
1. **Status tracking begins:** Server status is set to `CONNECTING`
|
||||
2. **Transport selection:** Based on configuration properties:
|
||||
- `httpUrl` → `StreamableHTTPClientTransport`
|
||||
- `url` → `SSEClientTransport`
|
||||
- `command` → `StdioClientTransport`
|
||||
3. **Connection establishment:** The MCP client attempts to connect with the configured timeout
|
||||
4. **Error handling:** Connection failures are logged and the server status is set to `DISCONNECTED`
|
||||
|
||||
### 2. Tool Discovery
|
||||
|
||||
Upon successful connection:
|
||||
|
||||
1. **Tool listing:** The client calls the MCP server's tool listing endpoint
|
||||
2. **Schema validation:** Each tool's function declaration is validated
|
||||
3. **Tool filtering:** Tools are filtered based on `includeTools` and `excludeTools` configuration
|
||||
4. **Name sanitization:** Tool names are cleaned to meet Qwen API requirements:
|
||||
- Invalid characters (non-alphanumeric, underscore, dot, hyphen) are replaced with underscores
|
||||
- Names longer than 63 characters are truncated with middle replacement (`___`)
|
||||
|
||||
### 3. Conflict Resolution
|
||||
|
||||
When multiple servers expose tools with the same name:
|
||||
|
||||
1. **First registration wins:** The first server to register a tool name gets the unprefixed name
|
||||
2. **Automatic prefixing:** Subsequent servers get prefixed names: `serverName__toolName`
|
||||
3. **Registry tracking:** The tool registry maintains mappings between server names and their tools
|
||||
|
||||
### 4. Schema Processing
|
||||
|
||||
Tool parameter schemas undergo sanitization for API compatibility:
|
||||
|
||||
- **`$schema` properties** are removed
|
||||
- **`additionalProperties`** are stripped
|
||||
- **`anyOf` with `default`** have their default values removed (Vertex AI compatibility)
|
||||
- **Recursive processing** applies to nested schemas
|
||||
|
||||
### 5. Connection Management
|
||||
|
||||
After discovery:
|
||||
|
||||
- **Persistent connections:** Servers that successfully register tools maintain their connections
|
||||
- **Cleanup:** Servers that provide no usable tools have their connections closed
|
||||
- **Status updates:** Final server statuses are set to `CONNECTED` or `DISCONNECTED`
|
||||
|
||||
## Tool Execution Flow
|
||||
|
||||
When the model decides to use an MCP tool, the following execution flow occurs:
|
||||
|
||||
### 1. Tool Invocation
|
||||
|
||||
The model generates a `FunctionCall` with:
|
||||
|
||||
- **Tool name:** The registered name (potentially prefixed)
|
||||
- **Arguments:** JSON object matching the tool's parameter schema
|
||||
|
||||
### 2. Confirmation Process
|
||||
|
||||
Each `DiscoveredMCPTool` implements sophisticated confirmation logic:
|
||||
|
||||
#### Trust-based Bypass
|
||||
|
||||
```typescript
|
||||
if (this.trust) {
|
||||
return false; // No confirmation needed
|
||||
}
|
||||
```
|
||||
|
||||
#### Dynamic Allow-listing
|
||||
|
||||
The system maintains internal allow-lists for:
|
||||
|
||||
- **Server-level:** `serverName` → All tools from this server are trusted
|
||||
- **Tool-level:** `serverName.toolName` → This specific tool is trusted
|
||||
|
||||
#### User Choice Handling
|
||||
|
||||
When confirmation is required, users can choose:
|
||||
|
||||
- **Proceed once:** Execute this time only
|
||||
- **Always allow this tool:** Add to tool-level allow-list
|
||||
- **Always allow this server:** Add to server-level allow-list
|
||||
- **Cancel:** Abort execution
|
||||
|
||||
### 3. Execution
|
||||
|
||||
Upon confirmation (or trust bypass):
|
||||
|
||||
1. **Parameter preparation:** Arguments are validated against the tool's schema
|
||||
2. **MCP call:** The underlying `CallableTool` invokes the server with:
|
||||
|
||||
```typescript
|
||||
const functionCalls = [
|
||||
{
|
||||
name: this.serverToolName, // Original server tool name
|
||||
args: params,
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
3. **Response processing:** Results are formatted for both LLM context and user display
|
||||
|
||||
### 4. Response Handling
|
||||
|
||||
The execution result contains:
|
||||
|
||||
- **`llmContent`:** Raw response parts for the language model's context
|
||||
- **`returnDisplay`:** Formatted output for user display (often JSON in markdown code blocks)
|
||||
|
||||
## How to interact with your MCP server
|
||||
|
||||
### Using the `/mcp` Command
|
||||
|
||||
The `/mcp` command provides comprehensive information about your MCP server setup:
|
||||
|
||||
```bash
|
||||
/mcp
|
||||
```
|
||||
|
||||
This displays:
|
||||
|
||||
- **Server list:** All configured MCP servers
|
||||
- **Connection status:** `CONNECTED`, `CONNECTING`, or `DISCONNECTED`
|
||||
- **Server details:** Configuration summary (excluding sensitive data)
|
||||
- **Available tools:** List of tools from each server with descriptions
|
||||
- **Discovery state:** Overall discovery process status
|
||||
|
||||
### Example `/mcp` Output
|
||||
|
||||
```
|
||||
MCP Servers Status:
|
||||
|
||||
📡 pythonTools (CONNECTED)
|
||||
Command: python -m my_mcp_server --port 8080
|
||||
Working Directory: ./mcp-servers/python
|
||||
Timeout: 15000ms
|
||||
Tools: calculate_sum, file_analyzer, data_processor
|
||||
|
||||
🔌 nodeServer (DISCONNECTED)
|
||||
Command: node dist/server.js --verbose
|
||||
Error: Connection refused
|
||||
|
||||
🐳 dockerizedServer (CONNECTED)
|
||||
Command: docker run -i --rm -e API_KEY my-mcp-server:latest
|
||||
Tools: docker__deploy, docker__status
|
||||
|
||||
Discovery State: COMPLETED
|
||||
```
|
||||
|
||||
### Tool Usage
|
||||
|
||||
Once discovered, MCP tools are available to the Qwen model like built-in tools. The model will automatically:
|
||||
|
||||
1. **Select appropriate tools** based on your requests
|
||||
2. **Present confirmation dialogs** (unless the server is trusted)
|
||||
3. **Execute tools** with proper parameters
|
||||
4. **Display results** in a user-friendly format
|
||||
|
||||
## Status Monitoring and Troubleshooting
|
||||
|
||||
### Connection States
|
||||
|
||||
The MCP integration tracks several states:
|
||||
|
||||
#### Server Status (`MCPServerStatus`)
|
||||
|
||||
- **`DISCONNECTED`:** Server is not connected or has errors
|
||||
- **`CONNECTING`:** Connection attempt in progress
|
||||
- **`CONNECTED`:** Server is connected and ready
|
||||
|
||||
#### Discovery State (`MCPDiscoveryState`)
|
||||
|
||||
- **`NOT_STARTED`:** Discovery hasn't begun
|
||||
- **`IN_PROGRESS`:** Currently discovering servers
|
||||
- **`COMPLETED`:** Discovery finished (with or without errors)
|
||||
|
||||
### Common Issues and Solutions
|
||||
|
||||
#### Server Won't Connect
|
||||
|
||||
**Symptoms:** Server shows `DISCONNECTED` status
|
||||
|
||||
**Troubleshooting:**
|
||||
|
||||
1. **Check configuration:** Verify `command`, `args`, and `cwd` are correct
|
||||
2. **Test manually:** Run the server command directly to ensure it works
|
||||
3. **Check dependencies:** Ensure all required packages are installed
|
||||
4. **Review logs:** Look for error messages in the CLI output
|
||||
5. **Verify permissions:** Ensure the CLI can execute the server command
|
||||
|
||||
#### No Tools Discovered
|
||||
|
||||
**Symptoms:** Server connects but no tools are available
|
||||
|
||||
**Troubleshooting:**
|
||||
|
||||
1. **Verify tool registration:** Ensure your server actually registers tools
|
||||
2. **Check MCP protocol:** Confirm your server implements the MCP tool listing correctly
|
||||
3. **Review server logs:** Check stderr output for server-side errors
|
||||
4. **Test tool listing:** Manually test your server's tool discovery endpoint
|
||||
|
||||
#### Tools Not Executing
|
||||
|
||||
**Symptoms:** Tools are discovered but fail during execution
|
||||
|
||||
**Troubleshooting:**
|
||||
|
||||
1. **Parameter validation:** Ensure your tool accepts the expected parameters
|
||||
2. **Schema compatibility:** Verify your input schemas are valid JSON Schema
|
||||
3. **Error handling:** Check if your tool is throwing unhandled exceptions
|
||||
4. **Timeout issues:** Consider increasing the `timeout` setting
|
||||
|
||||
#### Sandbox Compatibility
|
||||
|
||||
**Symptoms:** MCP servers fail when sandboxing is enabled
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Docker-based servers:** Use Docker containers that include all dependencies
|
||||
2. **Path accessibility:** Ensure server executables are available in the sandbox
|
||||
3. **Network access:** Configure sandbox to allow necessary network connections
|
||||
4. **Environment variables:** Verify required environment variables are passed through
|
||||
|
||||
### Debugging Tips
|
||||
|
||||
1. **Enable debug mode:** Run the CLI with `--debug` for verbose output
|
||||
2. **Check stderr:** MCP server stderr is captured and logged (INFO messages filtered)
|
||||
3. **Test isolation:** Test your MCP server independently before integrating
|
||||
4. **Incremental setup:** Start with simple tools before adding complex functionality
|
||||
5. **Use `/mcp` frequently:** Monitor server status during development
|
||||
|
||||
## Important Notes
|
||||
|
||||
### Security Considerations
|
||||
|
||||
- **Trust settings:** The `trust` option bypasses all confirmation dialogs. Use cautiously and only for servers you completely control
|
||||
- **Access tokens:** Be security-aware when configuring environment variables containing API keys or tokens
|
||||
- **Sandbox compatibility:** When using sandboxing, ensure MCP servers are available within the sandbox environment
|
||||
- **Private data:** Using broadly scoped personal access tokens can lead to information leakage between repositories
|
||||
|
||||
### Performance and Resource Management
|
||||
|
||||
- **Connection persistence:** The CLI maintains persistent connections to servers that successfully register tools
|
||||
- **Automatic cleanup:** Connections to servers providing no tools are automatically closed
|
||||
- **Timeout management:** Configure appropriate timeouts based on your server's response characteristics
|
||||
- **Resource monitoring:** MCP servers run as separate processes and consume system resources
|
||||
|
||||
### Schema Compatibility
|
||||
|
||||
- **Property stripping:** The system automatically removes certain schema properties (`$schema`, `additionalProperties`) for Qwen API compatibility
|
||||
- **Name sanitization:** Tool names are automatically sanitized to meet API requirements
|
||||
- **Conflict resolution:** Tool name conflicts between servers are resolved through automatic prefixing
|
||||
|
||||
This comprehensive integration makes MCP servers a powerful way to extend the CLI's capabilities while maintaining security, reliability, and ease of use.
|
||||
|
||||
## Returning Rich Content from Tools
|
||||
|
||||
MCP tools are not limited to returning simple text. You can return rich, multi-part content, including text, images, audio, and other binary data in a single tool response. This allows you to build powerful tools that can provide diverse information to the model in a single turn.
|
||||
|
||||
All data returned from the tool is processed and sent to the model as context for its next generation, enabling it to reason about or summarize the provided information.
|
||||
|
||||
### How It Works
|
||||
|
||||
To return rich content, your tool's response must adhere to the MCP specification for a [`CallToolResult`](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-result). The `content` field of the result should be an array of `ContentBlock` objects. The CLI will correctly process this array, separating text from binary data and packaging it for the model.
|
||||
|
||||
You can mix and match different content block types in the `content` array. The supported block types include:
|
||||
|
||||
- `text`
|
||||
- `image`
|
||||
- `audio`
|
||||
- `resource` (embedded content)
|
||||
- `resource_link`
|
||||
|
||||
### Example: Returning Text and an Image
|
||||
|
||||
Here is an example of a valid JSON response from an MCP tool that returns both a text description and an image:
|
||||
|
||||
```json
|
||||
{
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Here is the logo you requested."
|
||||
},
|
||||
{
|
||||
"type": "image",
|
||||
"data": "BASE64_ENCODED_IMAGE_DATA_HERE",
|
||||
"mimeType": "image/png"
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"text": "The logo was created in 2025."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
When Qwen Code receives this response, it will:
|
||||
|
||||
1. Extract all the text and combine it into a single `functionResponse` part for the model.
|
||||
2. Present the image data as a separate `inlineData` part.
|
||||
3. Provide a clean, user-friendly summary in the CLI, indicating that both text and an image were received.
|
||||
|
||||
This enables you to build sophisticated tools that can provide rich, multi-modal context to the Qwen model.
|
||||
|
||||
## MCP Prompts as Slash Commands
|
||||
|
||||
In addition to tools, MCP servers can expose predefined prompts that can be executed as slash commands within Qwen Code. This allows you to create shortcuts for common or complex queries that can be easily invoked by name.
|
||||
|
||||
### Defining Prompts on the Server
|
||||
|
||||
Here's a small example of a stdio MCP server that defines prompts:
|
||||
|
||||
```ts
|
||||
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
||||
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
||||
import { z } from 'zod';
|
||||
|
||||
const server = new McpServer({
|
||||
name: 'prompt-server',
|
||||
version: '1.0.0',
|
||||
});
|
||||
|
||||
server.registerPrompt(
|
||||
'poem-writer',
|
||||
{
|
||||
title: 'Poem Writer',
|
||||
description: 'Write a nice haiku',
|
||||
argsSchema: { title: z.string(), mood: z.string().optional() },
|
||||
},
|
||||
({ title, mood }) => ({
|
||||
messages: [
|
||||
{
|
||||
role: 'user',
|
||||
content: {
|
||||
type: 'text',
|
||||
text: `Write a haiku${mood ? ` with the mood ${mood}` : ''} called ${title}. Note that a haiku is 5 syllables followed by 7 syllables followed by 5 syllables `,
|
||||
},
|
||||
},
|
||||
],
|
||||
}),
|
||||
);
|
||||
|
||||
const transport = new StdioServerTransport();
|
||||
await server.connect(transport);
|
||||
```
|
||||
|
||||
This can be included in `settings.json` under `mcpServers` with:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"nodeServer": {
|
||||
"command": "node",
|
||||
"args": ["filename.ts"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Invoking Prompts
|
||||
|
||||
Once a prompt is discovered, you can invoke it using its name as a slash command. The CLI will automatically handle parsing arguments.
|
||||
|
||||
```bash
|
||||
/poem-writer --title="Qwen Code" --mood="reverent"
|
||||
```
|
||||
|
||||
or, using positional arguments:
|
||||
|
||||
```bash
|
||||
/poem-writer "Qwen Code" reverent
|
||||
```
|
||||
|
||||
When you run this command, the CLI executes the `prompts/get` method on the MCP server with the provided arguments. The server is responsible for substituting the arguments into the prompt template and returning the final prompt text. The CLI then sends this prompt to the model for execution. This provides a convenient way to automate and share common workflows.
|
||||
|
||||
## Managing MCP Servers with `qwen mcp`
|
||||
|
||||
While you can always configure MCP servers by manually editing your `settings.json` file, the CLI provides a convenient set of commands to manage your server configurations programmatically. These commands streamline the process of adding, listing, and removing MCP servers without needing to directly edit JSON files.
|
||||
|
||||
### Adding a Server (`qwen mcp add`)
|
||||
|
||||
The `add` command configures a new MCP server in your `settings.json`. Based on the scope (`-s, --scope`), it will be added to either the user config `~/.qwen/settings.json` or the project config `.qwen/settings.json` file.
|
||||
|
||||
**Command:**
|
||||
|
||||
```bash
|
||||
qwen mcp add [options] <name> <commandOrUrl> [args...]
|
||||
```
|
||||
|
||||
- `<name>`: A unique name for the server.
|
||||
- `<commandOrUrl>`: The command to execute (for `stdio`) or the URL (for `http`/`sse`).
|
||||
- `[args...]`: Optional arguments for a `stdio` command.
|
||||
|
||||
**Options (Flags):**
|
||||
|
||||
- `-s, --scope`: Configuration scope (user or project). [default: "project"]
|
||||
- `-t, --transport`: Transport type (stdio, sse, http). [default: "stdio"]
|
||||
- `-e, --env`: Set environment variables (e.g. -e KEY=value).
|
||||
- `-H, --header`: Set HTTP headers for SSE and HTTP transports (e.g. -H "X-Api-Key: abc123" -H "Authorization: Bearer abc123").
|
||||
- `--timeout`: Set connection timeout in milliseconds.
|
||||
- `--trust`: Trust the server (bypass all tool call confirmation prompts).
|
||||
- `--description`: Set the description for the server.
|
||||
- `--include-tools`: A comma-separated list of tools to include.
|
||||
- `--exclude-tools`: A comma-separated list of tools to exclude.
|
||||
|
||||
#### Adding an stdio server
|
||||
|
||||
This is the default transport for running local servers.
|
||||
|
||||
```bash
|
||||
# Basic syntax
|
||||
qwen mcp add <name> <command> [args...]
|
||||
|
||||
# Example: Adding a local server
|
||||
qwen mcp add my-stdio-server -e API_KEY=123 /path/to/server arg1 arg2 arg3
|
||||
|
||||
# Example: Adding a local python server
|
||||
qwen mcp add python-server python server.py --port 8080
|
||||
```
|
||||
|
||||
#### Adding an HTTP server
|
||||
|
||||
This transport is for servers that use the streamable HTTP transport.
|
||||
|
||||
```bash
|
||||
# Basic syntax
|
||||
qwen mcp add --transport http <name> <url>
|
||||
|
||||
# Example: Adding an HTTP server
|
||||
qwen mcp add --transport http http-server https://api.example.com/mcp/
|
||||
|
||||
# Example: Adding an HTTP server with an authentication header
|
||||
qwen mcp add --transport http secure-http https://api.example.com/mcp/ --header "Authorization: Bearer abc123"
|
||||
```
|
||||
|
||||
#### Adding an SSE server
|
||||
|
||||
This transport is for servers that use Server-Sent Events (SSE).
|
||||
|
||||
```bash
|
||||
# Basic syntax
|
||||
qwen mcp add --transport sse <name> <url>
|
||||
|
||||
# Example: Adding an SSE server
|
||||
qwen mcp add --transport sse sse-server https://api.example.com/sse/
|
||||
|
||||
# Example: Adding an SSE server with an authentication header
|
||||
qwen mcp add --transport sse secure-sse https://api.example.com/sse/ --header "Authorization: Bearer abc123"
|
||||
```
|
||||
|
||||
### Listing Servers (`qwen mcp list`)
|
||||
|
||||
To view all MCP servers currently configured, use the `list` command. It displays each server's name, configuration details, and connection status.
|
||||
|
||||
**Command:**
|
||||
|
||||
```bash
|
||||
qwen mcp list
|
||||
```
|
||||
|
||||
**Example Output:**
|
||||
|
||||
```sh
|
||||
✓ stdio-server: command: python3 server.py (stdio) - Connected
|
||||
✓ http-server: https://api.example.com/mcp (http) - Connected
|
||||
✗ sse-server: https://api.example.com/sse (sse) - Disconnected
|
||||
```
|
||||
|
||||
### Removing a Server (`qwen mcp remove`)
|
||||
|
||||
To delete a server from your configuration, use the `remove` command with the server's name.
|
||||
|
||||
**Command:**
|
||||
|
||||
```bash
|
||||
qwen mcp remove <name>
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
qwen mcp remove my-server
|
||||
```
|
||||
|
||||
This will find and delete the "my-server" entry from the `mcpServers` object in the appropriate `settings.json` file based on the scope (`-s, --scope`).
|
||||
44
docs/developers/tools/memory.md
Normal file
44
docs/developers/tools/memory.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# Memory Tool (`save_memory`)
|
||||
|
||||
This document describes the `save_memory` tool for Qwen Code.
|
||||
|
||||
## Description
|
||||
|
||||
Use `save_memory` to save and recall information across your Qwen Code sessions. With `save_memory`, you can direct the CLI to remember key details across sessions, providing personalized and directed assistance.
|
||||
|
||||
### Arguments
|
||||
|
||||
`save_memory` takes one argument:
|
||||
|
||||
- `fact` (string, required): The specific fact or piece of information to remember. This should be a clear, self-contained statement written in natural language.
|
||||
|
||||
## How to use `save_memory` with Qwen Code
|
||||
|
||||
The tool appends the provided `fact` to your context file in the user's home directory (`~/.qwen/QWEN.md` by default). This filename can be configured via `contextFileName`.
|
||||
|
||||
Once added, the facts are stored under a `## Qwen Added Memories` section. This file is loaded as context in subsequent sessions, allowing the CLI to recall the saved information.
|
||||
|
||||
Usage:
|
||||
|
||||
```
|
||||
save_memory(fact="Your fact here.")
|
||||
```
|
||||
|
||||
### `save_memory` examples
|
||||
|
||||
Remember a user preference:
|
||||
|
||||
```
|
||||
save_memory(fact="My preferred programming language is Python.")
|
||||
```
|
||||
|
||||
Store a project-specific detail:
|
||||
|
||||
```
|
||||
save_memory(fact="The project I'm currently working on is called 'qwen-code'.")
|
||||
```
|
||||
|
||||
## Important notes
|
||||
|
||||
- **General usage:** This tool should be used for concise, important facts. It is not intended for storing large amounts of data or conversational history.
|
||||
- **Memory file:** The memory file is a plain text Markdown file, so you can view and edit it manually if needed.
|
||||
69
docs/developers/tools/multi-file.md
Normal file
69
docs/developers/tools/multi-file.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# Multi File Read Tool (`read_many_files`)
|
||||
|
||||
This document describes the `read_many_files` tool for Qwen Code.
|
||||
|
||||
## Description
|
||||
|
||||
Use `read_many_files` to read content from multiple files specified by paths or glob patterns. The behavior of this tool depends on the provided files:
|
||||
|
||||
- For text files, this tool concatenates their content into a single string.
|
||||
- For image (e.g., PNG, JPEG), PDF, audio (MP3, WAV), and video (MP4, MOV) files, it reads and returns them as base64-encoded data, provided they are explicitly requested by name or extension.
|
||||
|
||||
`read_many_files` can be used to perform tasks such as getting an overview of a codebase, finding where specific functionality is implemented, reviewing documentation, or gathering context from multiple configuration files.
|
||||
|
||||
**Note:** `read_many_files` looks for files following the provided paths or glob patterns. A directory path such as `"/docs"` will return an empty result; the tool requires a pattern such as `"/docs/*"` or `"/docs/*.md"` to identify the relevant files.
|
||||
|
||||
### Arguments
|
||||
|
||||
`read_many_files` takes the following arguments:
|
||||
|
||||
- `paths` (list[string], required): An array of glob patterns or paths relative to the tool's target directory (e.g., `["src/**/*.ts"]`, `["README.md", "docs/*", "assets/logo.png"]`).
|
||||
- `exclude` (list[string], optional): Glob patterns for files/directories to exclude (e.g., `["**/*.log", "temp/"]`). These are added to default excludes if `useDefaultExcludes` is true.
|
||||
- `include` (list[string], optional): Additional glob patterns to include. These are merged with `paths` (e.g., `["*.test.ts"]` to specifically add test files if they were broadly excluded, or `["images/*.jpg"]` to include specific image types).
|
||||
- `recursive` (boolean, optional): Whether to search recursively. This is primarily controlled by `**` in glob patterns. Defaults to `true`.
|
||||
- `useDefaultExcludes` (boolean, optional): Whether to apply a list of default exclusion patterns (e.g., `node_modules`, `.git`, non image/pdf binary files). Defaults to `true`.
|
||||
- `respect_git_ignore` (boolean, optional): Whether to respect .gitignore patterns when finding files. Defaults to true.
|
||||
|
||||
## How to use `read_many_files` with Qwen Code
|
||||
|
||||
`read_many_files` searches for files matching the provided `paths` and `include` patterns, while respecting `exclude` patterns and default excludes (if enabled).
|
||||
|
||||
- For text files: it reads the content of each matched file (attempting to skip binary files not explicitly requested as image/PDF) and concatenates it into a single string, with a separator `--- {filePath} ---` between the content of each file. Uses UTF-8 encoding by default.
|
||||
- The tool inserts a `--- End of content ---` after the last file.
|
||||
- For image and PDF files: if explicitly requested by name or extension (e.g., `paths: ["logo.png"]` or `include: ["*.pdf"]`), the tool reads the file and returns its content as a base64 encoded string.
|
||||
- The tool attempts to detect and skip other binary files (those not matching common image/PDF types or not explicitly requested) by checking for null bytes in their initial content.
|
||||
|
||||
Usage:
|
||||
|
||||
```
|
||||
read_many_files(paths=["Your files or paths here."], include=["Additional files to include."], exclude=["Files to exclude."], recursive=False, useDefaultExcludes=false, respect_git_ignore=true)
|
||||
```
|
||||
|
||||
## `read_many_files` examples
|
||||
|
||||
Read all TypeScript files in the `src` directory:
|
||||
|
||||
```
|
||||
read_many_files(paths=["src/**/*.ts"])
|
||||
```
|
||||
|
||||
Read the main README, all Markdown files in the `docs` directory, and a specific logo image, excluding a specific file:
|
||||
|
||||
```
|
||||
read_many_files(paths=["README.md", "docs/**/*.md", "assets/logo.png"], exclude=["docs/OLD_README.md"])
|
||||
```
|
||||
|
||||
Read all JavaScript files but explicitly include test files and all JPEGs in an `images` folder:
|
||||
|
||||
```
|
||||
read_many_files(paths=["**/*.js"], include=["**/*.test.js", "images/**/*.jpg"], useDefaultExcludes=False)
|
||||
```
|
||||
|
||||
## Important notes
|
||||
|
||||
- **Binary file handling:**
|
||||
- **Image/PDF/Audio/Video files:** The tool can read common image types (PNG, JPEG, etc.), PDF, audio (mp3, wav), and video (mp4, mov) files, returning them as base64 encoded data. These files _must_ be explicitly targeted by the `paths` or `include` patterns (e.g., by specifying the exact filename like `video.mp4` or a pattern like `*.mov`).
|
||||
- **Other binary files:** The tool attempts to detect and skip other types of binary files by examining their initial content for null bytes. The tool excludes these files from its output.
|
||||
- **Performance:** Reading a very large number of files or very large individual files can be resource-intensive.
|
||||
- **Path specificity:** Ensure paths and glob patterns are correctly specified relative to the tool's target directory. For image/PDF files, ensure the patterns are specific enough to include them.
|
||||
- **Default excludes:** Be aware of the default exclusion patterns (like `node_modules`, `.git`) and use `useDefaultExcludes=False` if you need to override them, but do so cautiously.
|
||||
259
docs/developers/tools/shell.md
Normal file
259
docs/developers/tools/shell.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# Shell Tool (`run_shell_command`)
|
||||
|
||||
This document describes the `run_shell_command` tool for Qwen Code.
|
||||
|
||||
## Description
|
||||
|
||||
Use `run_shell_command` to interact with the underlying system, run scripts, or perform command-line operations. `run_shell_command` executes a given shell command, including interactive commands that require user input (e.g., `vim`, `git rebase -i`) if the `tools.shell.enableInteractiveShell` setting is set to `true`.
|
||||
|
||||
On Windows, commands are executed with `cmd.exe /c`. On other platforms, they are executed with `bash -c`.
|
||||
|
||||
### Arguments
|
||||
|
||||
`run_shell_command` takes the following arguments:
|
||||
|
||||
- `command` (string, required): The exact shell command to execute.
|
||||
- `description` (string, optional): A brief description of the command's purpose, which will be shown to the user.
|
||||
- `directory` (string, optional): The directory (relative to the project root) in which to execute the command. If not provided, the command runs in the project root.
|
||||
- `is_background` (boolean, required): Whether to run the command in background. This parameter is required to ensure explicit decision-making about command execution mode. Set to true for long-running processes like development servers, watchers, or daemons that should continue running without blocking further commands. Set to false for one-time commands that should complete before proceeding.
|
||||
|
||||
## How to use `run_shell_command` with Qwen Code
|
||||
|
||||
When using `run_shell_command`, the command is executed as a subprocess. You can control whether commands run in background or foreground using the `is_background` parameter, or by explicitly adding `&` to commands. The tool returns detailed information about the execution, including:
|
||||
|
||||
### Required Background Parameter
|
||||
|
||||
The `is_background` parameter is **required** for all command executions. This design ensures that the LLM (and users) must explicitly decide whether each command should run in the background or foreground, promoting intentional and predictable command execution behavior. By making this parameter mandatory, we avoid unintended fallback to foreground execution, which could block subsequent operations when dealing with long-running processes.
|
||||
|
||||
### Background vs Foreground Execution
|
||||
|
||||
The tool intelligently handles background and foreground execution based on your explicit choice:
|
||||
|
||||
**Use background execution (`is_background: true`) for:**
|
||||
|
||||
- Long-running development servers: `npm run start`, `npm run dev`, `yarn dev`
|
||||
- Build watchers: `npm run watch`, `webpack --watch`
|
||||
- Database servers: `mongod`, `mysql`, `redis-server`
|
||||
- Web servers: `python -m http.server`, `php -S localhost:8000`
|
||||
- Any command expected to run indefinitely until manually stopped
|
||||
|
||||
**Use foreground execution (`is_background: false`) for:**
|
||||
|
||||
- One-time commands: `ls`, `cat`, `grep`
|
||||
- Build commands: `npm run build`, `make`
|
||||
- Installation commands: `npm install`, `pip install`
|
||||
- Git operations: `git commit`, `git push`
|
||||
- Test runs: `npm test`, `pytest`
|
||||
|
||||
### Execution Information
|
||||
|
||||
The tool returns detailed information about the execution, including:
|
||||
|
||||
- `Command`: The command that was executed.
|
||||
- `Directory`: The directory where the command was run.
|
||||
- `Stdout`: Output from the standard output stream.
|
||||
- `Stderr`: Output from the standard error stream.
|
||||
- `Error`: Any error message reported by the subprocess.
|
||||
- `Exit Code`: The exit code of the command.
|
||||
- `Signal`: The signal number if the command was terminated by a signal.
|
||||
- `Background PIDs`: A list of PIDs for any background processes started.
|
||||
|
||||
Usage:
|
||||
|
||||
```bash
|
||||
run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.", is_background=false)
|
||||
```
|
||||
|
||||
**Note:** The `is_background` parameter is required and must be explicitly specified for every command execution.
|
||||
|
||||
## `run_shell_command` examples
|
||||
|
||||
List files in the current directory:
|
||||
|
||||
```bash
|
||||
run_shell_command(command="ls -la", is_background=false)
|
||||
```
|
||||
|
||||
Run a script in a specific directory:
|
||||
|
||||
```bash
|
||||
run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script", is_background=false)
|
||||
```
|
||||
|
||||
Start a background development server (recommended approach):
|
||||
|
||||
```bash
|
||||
run_shell_command(command="npm run dev", description="Start development server in background", is_background=true)
|
||||
```
|
||||
|
||||
Start a background server (alternative with explicit &):
|
||||
|
||||
```bash
|
||||
run_shell_command(command="npm run dev &", description="Start development server in background", is_background=false)
|
||||
```
|
||||
|
||||
Run a build command in foreground:
|
||||
|
||||
```bash
|
||||
run_shell_command(command="npm run build", description="Build the project", is_background=false)
|
||||
```
|
||||
|
||||
Start multiple background services:
|
||||
|
||||
```bash
|
||||
run_shell_command(command="docker-compose up", description="Start all services", is_background=true)
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
You can configure the behavior of the `run_shell_command` tool by modifying your `settings.json` file or by using the `/settings` command in the Qwen Code.
|
||||
|
||||
### Enabling Interactive Commands
|
||||
|
||||
To enable interactive commands, you need to set the `tools.shell.enableInteractiveShell` setting to `true`. This will use `node-pty` for shell command execution, which allows for interactive sessions. If `node-pty` is not available, it will fall back to the `child_process` implementation, which does not support interactive commands.
|
||||
|
||||
**Example `settings.json`:**
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"shell": {
|
||||
"enableInteractiveShell": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Showing Color in Output
|
||||
|
||||
To show color in the shell output, you need to set the `tools.shell.showColor` setting to `true`. **Note: This setting only applies when `tools.shell.enableInteractiveShell` is enabled.**
|
||||
|
||||
**Example `settings.json`:**
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"shell": {
|
||||
"showColor": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Setting the Pager
|
||||
|
||||
You can set a custom pager for the shell output by setting the `tools.shell.pager` setting. The default pager is `cat`. **Note: This setting only applies when `tools.shell.enableInteractiveShell` is enabled.**
|
||||
|
||||
**Example `settings.json`:**
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"shell": {
|
||||
"pager": "less"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Interactive Commands
|
||||
|
||||
The `run_shell_command` tool now supports interactive commands by integrating a pseudo-terminal (pty). This allows you to run commands that require real-time user input, such as text editors (`vim`, `nano`), terminal-based UIs (`htop`), and interactive version control operations (`git rebase -i`).
|
||||
|
||||
When an interactive command is running, you can send input to it from the Qwen Code. To focus on the interactive shell, press `ctrl+f`. The terminal output, including complex TUIs, will be rendered correctly.
|
||||
|
||||
## Important notes
|
||||
|
||||
- **Security:** Be cautious when executing commands, especially those constructed from user input, to prevent security vulnerabilities.
|
||||
- **Error handling:** Check the `Stderr`, `Error`, and `Exit Code` fields to determine if a command executed successfully.
|
||||
- **Background processes:** When `is_background=true` or when a command contains `&`, the tool will return immediately and the process will continue to run in the background. The `Background PIDs` field will contain the process ID of the background process.
|
||||
- **Background execution choices:** The `is_background` parameter is required and provides explicit control over execution mode. You can also add `&` to the command for manual background execution, but the `is_background` parameter must still be specified. The parameter provides clearer intent and automatically handles the background execution setup.
|
||||
- **Command descriptions:** When using `is_background=true`, the command description will include a `[background]` indicator to clearly show the execution mode.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
When `run_shell_command` executes a command, it sets the `QWEN_CODE=1` environment variable in the subprocess's environment. This allows scripts or tools to detect if they are being run from within the CLI.
|
||||
|
||||
## Command Restrictions
|
||||
|
||||
You can restrict the commands that can be executed by the `run_shell_command` tool by using the `tools.core` and `tools.exclude` settings in your configuration file.
|
||||
|
||||
- `tools.core`: To restrict `run_shell_command` to a specific set of commands, add entries to the `core` list under the `tools` category in the format `run_shell_command(<command>)`. For example, `"tools": {"core": ["run_shell_command(git)"]}` will only allow `git` commands. Including the generic `run_shell_command` acts as a wildcard, allowing any command not explicitly blocked.
|
||||
- `tools.exclude`: To block specific commands, add entries to the `exclude` list under the `tools` category in the format `run_shell_command(<command>)`. For example, `"tools": {"exclude": ["run_shell_command(rm)"]}` will block `rm` commands.
|
||||
|
||||
The validation logic is designed to be secure and flexible:
|
||||
|
||||
1. **Command Chaining Disabled**: The tool automatically splits commands chained with `&&`, `||`, or `;` and validates each part separately. If any part of the chain is disallowed, the entire command is blocked.
|
||||
2. **Prefix Matching**: The tool uses prefix matching. For example, if you allow `git`, you can run `git status` or `git log`.
|
||||
3. **Blocklist Precedence**: The `tools.exclude` list is always checked first. If a command matches a blocked prefix, it will be denied, even if it also matches an allowed prefix in `tools.core`.
|
||||
|
||||
### Command Restriction Examples
|
||||
|
||||
**Allow only specific command prefixes**
|
||||
|
||||
To allow only `git` and `npm` commands, and block all others:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"core": ["run_shell_command(git)", "run_shell_command(npm)"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `git status`: Allowed
|
||||
- `npm install`: Allowed
|
||||
- `ls -l`: Blocked
|
||||
|
||||
**Block specific command prefixes**
|
||||
|
||||
To block `rm` and allow all other commands:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"core": ["run_shell_command"],
|
||||
"exclude": ["run_shell_command(rm)"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `rm -rf /`: Blocked
|
||||
- `git status`: Allowed
|
||||
- `npm install`: Allowed
|
||||
|
||||
**Blocklist takes precedence**
|
||||
|
||||
If a command prefix is in both `tools.core` and `tools.exclude`, it will be blocked.
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"core": ["run_shell_command(git)"],
|
||||
"exclude": ["run_shell_command(git push)"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `git push origin main`: Blocked
|
||||
- `git status`: Allowed
|
||||
|
||||
**Block all shell commands**
|
||||
|
||||
To block all shell commands, add the `run_shell_command` wildcard to `tools.exclude`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"exclude": ["run_shell_command"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `ls -l`: Blocked
|
||||
- `any other command`: Blocked
|
||||
|
||||
## Security Note for `excludeTools`
|
||||
|
||||
Command-specific restrictions in `excludeTools` for `run_shell_command` are based on simple string matching and can be easily bypassed. This feature is **not a security mechanism** and should not be relied upon to safely execute untrusted code. It is recommended to use `coreTools` to explicitly select commands
|
||||
that can be executed.
|
||||
63
docs/developers/tools/todo-write.md
Normal file
63
docs/developers/tools/todo-write.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# Todo Write Tool (`todo_write`)
|
||||
|
||||
This document describes the `todo_write` tool for Qwen Code.
|
||||
|
||||
## Description
|
||||
|
||||
Use `todo_write` to create and manage a structured task list for your current coding session. This tool helps the AI assistant track progress and organize complex tasks, providing you with visibility into what work is being performed.
|
||||
|
||||
### Arguments
|
||||
|
||||
`todo_write` takes one argument:
|
||||
|
||||
- `todos` (array, required): An array of todo items, where each item contains:
|
||||
- `id` (string, required): A unique identifier for the todo item.
|
||||
- `content` (string, required): The description of the task.
|
||||
- `status` (string, required): The current status (`pending`, `in_progress`, or `completed`).
|
||||
|
||||
## How to use `todo_write` with Qwen Code
|
||||
|
||||
The AI assistant will automatically use this tool when working on complex, multi-step tasks. You don't need to explicitly request it, but you can ask the assistant to create a todo list if you want to see the planned approach for your request.
|
||||
|
||||
The tool stores todo lists in your home directory (`~/.qwen/todos/`) with session-specific files, so each coding session maintains its own task list.
|
||||
|
||||
## When the AI uses this tool
|
||||
|
||||
The assistant uses `todo_write` for:
|
||||
|
||||
- Complex tasks requiring multiple steps
|
||||
- Feature implementations with several components
|
||||
- Refactoring operations across multiple files
|
||||
- Any work involving 3 or more distinct actions
|
||||
|
||||
The assistant will not use this tool for simple, single-step tasks or purely informational requests.
|
||||
|
||||
### `todo_write` examples
|
||||
|
||||
Creating a feature implementation plan:
|
||||
|
||||
```
|
||||
todo_write(todos=[
|
||||
{
|
||||
"id": "create-model",
|
||||
"content": "Create user preferences model",
|
||||
"status": "pending"
|
||||
},
|
||||
{
|
||||
"id": "add-endpoints",
|
||||
"content": "Add API endpoints for preferences",
|
||||
"status": "pending"
|
||||
},
|
||||
{
|
||||
"id": "implement-ui",
|
||||
"content": "Implement frontend components",
|
||||
"status": "pending"
|
||||
}
|
||||
])
|
||||
```
|
||||
|
||||
## Important notes
|
||||
|
||||
- **Automatic usage:** The AI assistant manages todo lists automatically during complex tasks.
|
||||
- **Progress visibility:** You'll see todo lists updated in real-time as work progresses.
|
||||
- **Session isolation:** Each coding session has its own todo list that doesn't interfere with others.
|
||||
54
docs/developers/tools/web-fetch.md
Normal file
54
docs/developers/tools/web-fetch.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Web Fetch Tool (`web_fetch`)
|
||||
|
||||
This document describes the `web_fetch` tool for Qwen Code.
|
||||
|
||||
## Description
|
||||
|
||||
Use `web_fetch` to fetch content from a specified URL and process it using an AI model. The tool takes a URL and a prompt as input, fetches the URL content, converts HTML to markdown, and processes the content with the prompt using a small, fast model.
|
||||
|
||||
### Arguments
|
||||
|
||||
`web_fetch` takes two arguments:
|
||||
|
||||
- `url` (string, required): The URL to fetch content from. Must be a fully-formed valid URL starting with `http://` or `https://`.
|
||||
- `prompt` (string, required): The prompt describing what information you want to extract from the page content.
|
||||
|
||||
## How to use `web_fetch` with Qwen Code
|
||||
|
||||
To use `web_fetch` with Qwen Code, provide a URL and a prompt describing what you want to extract from that URL. The tool will ask for confirmation before fetching the URL. Once confirmed, the tool will fetch the content directly and process it using an AI model.
|
||||
|
||||
The tool automatically converts HTML to text, handles GitHub blob URLs (converting them to raw URLs), and upgrades HTTP URLs to HTTPS for security.
|
||||
|
||||
Usage:
|
||||
|
||||
```
|
||||
web_fetch(url="https://example.com", prompt="Summarize the main points of this article")
|
||||
```
|
||||
|
||||
## `web_fetch` examples
|
||||
|
||||
Summarize a single article:
|
||||
|
||||
```
|
||||
web_fetch(url="https://example.com/news/latest", prompt="Can you summarize the main points of this article?")
|
||||
```
|
||||
|
||||
Extract specific information:
|
||||
|
||||
```
|
||||
web_fetch(url="https://arxiv.org/abs/2401.0001", prompt="What are the key findings and methodology described in this paper?")
|
||||
```
|
||||
|
||||
Analyze GitHub documentation:
|
||||
|
||||
```
|
||||
web_fetch(url="https://github.com/QwenLM/Qwen/blob/main/README.md", prompt="What are the installation steps and main features?")
|
||||
```
|
||||
|
||||
## Important notes
|
||||
|
||||
- **Single URL processing:** `web_fetch` processes one URL at a time. To analyze multiple URLs, make separate calls to the tool.
|
||||
- **URL format:** The tool automatically upgrades HTTP URLs to HTTPS and converts GitHub blob URLs to raw format for better content access.
|
||||
- **Content processing:** The tool fetches content directly and processes it using an AI model, converting HTML to readable text format.
|
||||
- **Output quality:** The quality of the output will depend on the clarity of the instructions in the prompt.
|
||||
- **MCP tools:** If an MCP-provided web fetch tool is available (starting with "mcp\_\_"), prefer using that tool as it may have fewer restrictions.
|
||||
186
docs/developers/tools/web-search.md
Normal file
186
docs/developers/tools/web-search.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# Web Search Tool (`web_search`)
|
||||
|
||||
This document describes the `web_search` tool for performing web searches using multiple providers.
|
||||
|
||||
## Description
|
||||
|
||||
Use `web_search` to perform a web search and get information from the internet. The tool supports multiple search providers and returns a concise answer with source citations when available.
|
||||
|
||||
### Supported Providers
|
||||
|
||||
1. **DashScope** (Official, Free) - Automatically available for Qwen OAuth users (200 requests/minute, 2000 requests/day)
|
||||
2. **Tavily** - High-quality search API with built-in answer generation
|
||||
3. **Google Custom Search** - Google's Custom Search JSON API
|
||||
|
||||
### Arguments
|
||||
|
||||
`web_search` takes two arguments:
|
||||
|
||||
- `query` (string, required): The search query
|
||||
- `provider` (string, optional): Specific provider to use ("dashscope", "tavily", "google")
|
||||
- If not specified, uses the default provider from configuration
|
||||
|
||||
## Configuration
|
||||
|
||||
### Method 1: Settings File (Recommended)
|
||||
|
||||
Add to your `settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"webSearch": {
|
||||
"provider": [
|
||||
{ "type": "dashscope" },
|
||||
{ "type": "tavily", "apiKey": "tvly-xxxxx" },
|
||||
{
|
||||
"type": "google",
|
||||
"apiKey": "your-google-api-key",
|
||||
"searchEngineId": "your-search-engine-id"
|
||||
}
|
||||
],
|
||||
"default": "dashscope"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
|
||||
- DashScope doesn't require an API key (official, free service)
|
||||
- **Qwen OAuth users:** DashScope is automatically added to your provider list, even if not explicitly configured
|
||||
- Configure additional providers (Tavily, Google) if you want to use them alongside DashScope
|
||||
- Set `default` to specify which provider to use by default (if not set, priority order: Tavily > Google > DashScope)
|
||||
|
||||
### Method 2: Environment Variables
|
||||
|
||||
Set environment variables in your shell or `.env` file:
|
||||
|
||||
```bash
|
||||
# Tavily
|
||||
export TAVILY_API_KEY="tvly-xxxxx"
|
||||
|
||||
# Google
|
||||
export GOOGLE_API_KEY="your-api-key"
|
||||
export GOOGLE_SEARCH_ENGINE_ID="your-engine-id"
|
||||
```
|
||||
|
||||
### Method 3: Command Line Arguments
|
||||
|
||||
Pass API keys when running Qwen Code:
|
||||
|
||||
```bash
|
||||
# Tavily
|
||||
qwen --tavily-api-key tvly-xxxxx
|
||||
|
||||
# Google
|
||||
qwen --google-api-key your-key --google-search-engine-id your-id
|
||||
|
||||
# Specify default provider
|
||||
qwen --web-search-default tavily
|
||||
```
|
||||
|
||||
### Backward Compatibility (Deprecated)
|
||||
|
||||
⚠️ **DEPRECATED:** The legacy `tavilyApiKey` configuration is still supported for backward compatibility but is deprecated:
|
||||
|
||||
```json
|
||||
{
|
||||
"advanced": {
|
||||
"tavilyApiKey": "tvly-xxxxx" // ⚠️ Deprecated
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Important:** This configuration is deprecated and will be removed in a future version. Please migrate to the new `webSearch` configuration format shown above. The old configuration will automatically configure Tavily as a provider, but we strongly recommend updating your configuration.
|
||||
|
||||
## Disabling Web Search
|
||||
|
||||
If you want to disable the web search functionality, you can exclude the `web_search` tool in your `settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"exclude": ["web_search"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** This setting requires a restart of Qwen Code to take effect. Once disabled, the `web_search` tool will not be available to the model, even if web search providers are configured.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic search (using default provider)
|
||||
|
||||
```
|
||||
web_search(query="latest advancements in AI")
|
||||
```
|
||||
|
||||
### Search with specific provider
|
||||
|
||||
```
|
||||
web_search(query="latest advancements in AI", provider="tavily")
|
||||
```
|
||||
|
||||
### Real-world examples
|
||||
|
||||
```
|
||||
web_search(query="weather in San Francisco today")
|
||||
web_search(query="latest Node.js LTS version", provider="google")
|
||||
web_search(query="best practices for React 19", provider="dashscope")
|
||||
```
|
||||
|
||||
## Provider Details
|
||||
|
||||
### DashScope (Official)
|
||||
|
||||
- **Cost:** Free
|
||||
- **Authentication:** Automatically available when using Qwen OAuth authentication
|
||||
- **Configuration:** No API key required, automatically added to provider list for Qwen OAuth users
|
||||
- **Quota:** 200 requests/minute, 2000 requests/day
|
||||
- **Best for:** General queries, always available as fallback for Qwen OAuth users
|
||||
- **Auto-registration:** If you're using Qwen OAuth, DashScope is automatically added to your provider list even if you don't configure it explicitly
|
||||
|
||||
### Tavily
|
||||
|
||||
- **Cost:** Requires API key (paid service with free tier)
|
||||
- **Sign up:** https://tavily.com
|
||||
- **Features:** High-quality results with AI-generated answers
|
||||
- **Best for:** Research, comprehensive answers with citations
|
||||
|
||||
### Google Custom Search
|
||||
|
||||
- **Cost:** Free tier available (100 queries/day)
|
||||
- **Setup:**
|
||||
1. Enable Custom Search API in Google Cloud Console
|
||||
2. Create a Custom Search Engine at https://programmablesearchengine.google.com
|
||||
- **Features:** Google's search quality
|
||||
- **Best for:** Specific, factual queries
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **Response format:** Returns a concise answer with numbered source citations
|
||||
- **Citations:** Source links are appended as a numbered list: [1], [2], etc.
|
||||
- **Multiple providers:** If one provider fails, manually specify another using the `provider` parameter
|
||||
- **DashScope availability:** Automatically available for Qwen OAuth users, no configuration needed
|
||||
- **Default provider selection:** The system automatically selects a default provider based on availability:
|
||||
1. Your explicit `default` configuration (highest priority)
|
||||
2. CLI argument `--web-search-default`
|
||||
3. First available provider by priority: Tavily > Google > DashScope
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Tool not available?**
|
||||
|
||||
- **For Qwen OAuth users:** The tool is automatically registered with DashScope provider, no configuration needed
|
||||
- **For other authentication types:** Ensure at least one provider (Tavily or Google) is configured
|
||||
- For Tavily/Google: Verify your API keys are correct
|
||||
|
||||
**Provider-specific errors?**
|
||||
|
||||
- Use the `provider` parameter to try a different search provider
|
||||
- Check your API quotas and rate limits
|
||||
- Verify API keys are properly set in configuration
|
||||
|
||||
**Need help?**
|
||||
|
||||
- Check your configuration: Run `qwen` and use the settings dialog
|
||||
- View your current settings in `~/.qwen-code/settings.json` (macOS/Linux) or `%USERPROFILE%\.qwen-code\settings.json` (Windows)
|
||||
Reference in New Issue
Block a user