mirror of
https://github.com/QwenLM/qwen-code.git
synced 2025-12-19 09:33:53 +00:00
docs: add comprehensive MCP Quick Start guides and examples
- Add MCP Quick Start Guide with 5 practical examples - Add 30+ ready-to-use MCP configuration examples - Add MCP testing and validation guide - Update tools documentation index with MCP guide links This documentation makes it easier for users to get started with Model Context Protocol servers in Qwen Code, reducing setup time from hours to minutes. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This commit is contained in:
sontoriyama
534
docs/mcp-example-configs.md
Normal file
534
docs/mcp-example-configs.md
Normal file
@@ -0,0 +1,534 @@
|
||||
# MCP Example Configurations
|
||||
|
||||
Ready-to-use MCP server configurations for common scenarios.
|
||||
|
||||
## 📁 Local Development
|
||||
|
||||
### Basic Setup
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"workspace": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
|
||||
"trust": true,
|
||||
"description": "Full workspace access"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Multi-Directory Project
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"frontend": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"./src",
|
||||
"./public",
|
||||
"./tests"
|
||||
],
|
||||
"trust": true,
|
||||
"description": "Frontend development files"
|
||||
},
|
||||
"config": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"./config",
|
||||
"./.env.example"
|
||||
],
|
||||
"trust": true,
|
||||
"includeTools": ["read_file", "list_directory"],
|
||||
"description": "Configuration files (read-only)"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🧠 Memory & Context
|
||||
|
||||
### Persistent Memory
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"project-memory": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-memory"],
|
||||
"trust": true,
|
||||
"description": "Remember project context across sessions"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Combined with Filesystem
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"files": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
|
||||
"trust": true
|
||||
},
|
||||
"memory": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-memory"],
|
||||
"trust": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🌐 Remote Servers (HTTP/SSE)
|
||||
|
||||
### HTTP MCP Server
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"remote-api": {
|
||||
"httpUrl": "https://api.example.com/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer ${API_TOKEN}",
|
||||
"Content-Type": "application/json"
|
||||
},
|
||||
"timeout": 30000,
|
||||
"description": "Remote MCP API"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SSE Server with OAuth
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"sse-service": {
|
||||
"url": "https://mcp.example.com/sse",
|
||||
"oauth": {
|
||||
"enabled": true,
|
||||
"scopes": ["read", "write"]
|
||||
},
|
||||
"timeout": 60000,
|
||||
"description": "SSE server with OAuth"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🐍 Python MCP Servers
|
||||
|
||||
### Simple Python Server
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"python-tools": {
|
||||
"command": "python",
|
||||
"args": ["-m", "my_mcp_server"],
|
||||
"env": {
|
||||
"PYTHONPATH": "${PWD}",
|
||||
"DEBUG": "false"
|
||||
},
|
||||
"description": "Custom Python MCP tools"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Python with Virtual Environment
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"python-venv": {
|
||||
"command": "./venv/bin/python",
|
||||
"args": ["-m", "mcp_server"],
|
||||
"cwd": "./",
|
||||
"env": {
|
||||
"VIRTUAL_ENV": "${PWD}/venv"
|
||||
},
|
||||
"description": "Python server in virtual environment"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🐳 Docker Containers
|
||||
|
||||
### Basic Docker Server
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"docker-mcp": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"my-mcp-server:latest"
|
||||
],
|
||||
"timeout": 45000,
|
||||
"description": "MCP server in Docker"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Docker with Volume Mounts
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"docker-workspace": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-v",
|
||||
"${PWD}:/workspace",
|
||||
"-w",
|
||||
"/workspace",
|
||||
"-e",
|
||||
"API_KEY",
|
||||
"mcp-tools:latest"
|
||||
],
|
||||
"env": {
|
||||
"API_KEY": "${MY_API_KEY}"
|
||||
},
|
||||
"description": "Docker MCP with workspace access"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🛡️ Security-Focused Configs
|
||||
|
||||
### Read-Only Filesystem
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"readonly-docs": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"./docs",
|
||||
"./README.md"
|
||||
],
|
||||
"includeTools": ["read_file", "list_directory", "search_files"],
|
||||
"excludeTools": [
|
||||
"write_file",
|
||||
"create_directory",
|
||||
"move_file",
|
||||
"delete_file"
|
||||
],
|
||||
"trust": true,
|
||||
"description": "Read-only documentation access"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Untrusted External Server
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"external-api": {
|
||||
"httpUrl": "https://external-mcp.example.com/api",
|
||||
"trust": false,
|
||||
"timeout": 15000,
|
||||
"includeTools": ["search", "analyze"],
|
||||
"description": "External API (requires confirmation)"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 Database Access
|
||||
|
||||
### PostgreSQL MCP Server
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"postgres": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-postgres",
|
||||
"${DATABASE_URL}"
|
||||
],
|
||||
"env": {
|
||||
"DATABASE_URL": "$POSTGRES_CONNECTION_STRING"
|
||||
},
|
||||
"timeout": 30000,
|
||||
"trust": false,
|
||||
"description": "PostgreSQL database access"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🧪 Testing & Development
|
||||
|
||||
### Test Environment
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"test-files": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"./tests",
|
||||
"./fixtures"
|
||||
],
|
||||
"trust": true,
|
||||
"description": "Test files and fixtures"
|
||||
},
|
||||
"test-memory": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-memory"],
|
||||
"trust": true,
|
||||
"description": "Test session memory"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Debug Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"debug-server": {
|
||||
"command": "node",
|
||||
"args": ["--inspect", "mcp-server.js"],
|
||||
"env": {
|
||||
"DEBUG": "*",
|
||||
"LOG_LEVEL": "verbose"
|
||||
},
|
||||
"timeout": 60000,
|
||||
"description": "MCP server with debugging enabled"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🔄 CI/CD Integration
|
||||
|
||||
### GitHub Actions Environment
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"ci-workspace": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"${GITHUB_WORKSPACE}"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_TOKEN": "$GITHUB_TOKEN",
|
||||
"CI": "true"
|
||||
},
|
||||
"trust": true,
|
||||
"description": "CI/CD workspace access"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🌟 Advanced Patterns
|
||||
|
||||
### Multiple Servers Same Type
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"project-a": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "../project-a"],
|
||||
"description": "Project A files"
|
||||
},
|
||||
"project-b": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "../project-b"],
|
||||
"description": "Project B files"
|
||||
},
|
||||
"shared-memory": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-memory"],
|
||||
"description": "Shared knowledge across projects"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Conditional Server Selection
|
||||
|
||||
User-level config (`~/.qwen/settings.json`):
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"global-memory": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-memory"],
|
||||
"trust": true,
|
||||
"description": "Global memory across all projects"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Project-level config (`.qwen/settings.json`):
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"project-files": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
|
||||
"trust": true,
|
||||
"description": "Project-specific files"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📝 Configuration Validation
|
||||
|
||||
### Check Your Config
|
||||
|
||||
```bash
|
||||
# List configured servers
|
||||
qwen mcp list
|
||||
|
||||
# Show server details and schemas
|
||||
qwen mcp list --schema
|
||||
|
||||
# Test connection
|
||||
qwen mcp list --descriptions
|
||||
```
|
||||
|
||||
### Common Mistakes
|
||||
|
||||
❌ **Wrong:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"server": {
|
||||
"command": "mcp-server", // Not in PATH
|
||||
"args": ["./"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
✅ **Correct:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"server": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
|
||||
"description": "Uses npx to ensure server is available"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🎯 Best Practices
|
||||
|
||||
1. **Use descriptive names** - Make server purposes clear
|
||||
2. **Set appropriate timeouts** - Match your server's response time
|
||||
3. **Trust local servers** - Skip confirmation for your own tools
|
||||
4. **Filter tools** - Use `includeTools`/`excludeTools` for security
|
||||
5. **Document configs** - Add descriptions for team members
|
||||
6. **Environment variables** - Keep secrets out of configs
|
||||
7. **Test independently** - Verify servers work before configuring
|
||||
|
||||
## 🔗 Quick Copy-Paste Configs
|
||||
|
||||
### Starter Pack
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"files": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
|
||||
"trust": true
|
||||
},
|
||||
"memory": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-memory"],
|
||||
"trust": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Documentation Project
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"docs": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./docs"],
|
||||
"includeTools": ["read_file", "list_directory"],
|
||||
"trust": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Full-Stack Development
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"frontend": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./frontend"],
|
||||
"trust": true
|
||||
},
|
||||
"backend": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./backend"],
|
||||
"trust": true
|
||||
},
|
||||
"shared": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./shared"],
|
||||
"trust": true
|
||||
},
|
||||
"memory": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-memory"],
|
||||
"trust": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Need help?** Check `qwen mcp --help` or refer to the [complete MCP documentation](./tools/mcp-server.md).
|
||||
418
docs/mcp-quick-start.md
Normal file
418
docs/mcp-quick-start.md
Normal file
@@ -0,0 +1,418 @@
|
||||
# MCP Quick Start Guide - Practical Examples
|
||||
|
||||
This guide provides real-world examples to get you started with Model Context Protocol (MCP) servers in Qwen Code.
|
||||
|
||||
## 🚀 Getting Started in 5 Minutes
|
||||
|
||||
### Step 1: Install MCP Servers
|
||||
|
||||
Install official MCP servers from Anthropic:
|
||||
|
||||
```bash
|
||||
# Filesystem access
|
||||
npm install -g @modelcontextprotocol/server-filesystem
|
||||
|
||||
# Memory & Knowledge Graph
|
||||
npm install -g @modelcontextprotocol/server-memory
|
||||
|
||||
# Sequential thinking
|
||||
npm install -g @modelcontextprotocol/server-sequential-thinking
|
||||
```
|
||||
|
||||
### Step 2: Configure Your First MCP Server
|
||||
|
||||
Create or edit `.qwen/settings.json` in your project:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"filesystem": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
|
||||
"description": "Access project files"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Verify Connection
|
||||
|
||||
```bash
|
||||
qwen mcp list
|
||||
```
|
||||
|
||||
You should see:
|
||||
```
|
||||
✓ filesystem: npx -y @modelcontextprotocol/server-filesystem ./ (stdio) - Connected
|
||||
```
|
||||
|
||||
## 📚 Practical Examples
|
||||
|
||||
### Example 1: Local Development Assistant
|
||||
|
||||
**Use Case:** Work on a Node.js project with file access and memory.
|
||||
|
||||
**Configuration (`.qwen/settings.json`):**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"project-files": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"./src",
|
||||
"./tests",
|
||||
"./docs"
|
||||
],
|
||||
"description": "Access source code, tests, and documentation",
|
||||
"trust": true
|
||||
},
|
||||
"project-memory": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-memory"],
|
||||
"description": "Remember project decisions and context",
|
||||
"trust": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
qwen
|
||||
|
||||
> Remember: This project uses React 18 with TypeScript and follows Airbnb style guide
|
||||
> List all files in the src directory
|
||||
> Read src/App.tsx and suggest improvements
|
||||
```
|
||||
|
||||
### Example 2: Multi-Repository Development
|
||||
|
||||
**Use Case:** Working across multiple codebases simultaneously.
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"frontend": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"../frontend-app"
|
||||
],
|
||||
"description": "Frontend repository access"
|
||||
},
|
||||
"backend": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"../backend-api"
|
||||
],
|
||||
"description": "Backend repository access"
|
||||
},
|
||||
"shared-memory": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-memory"],
|
||||
"description": "Shared knowledge across repositories"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example 3: Documentation-Only Access
|
||||
|
||||
**Use Case:** Safe access to documentation without risking code changes.
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"docs": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"./docs",
|
||||
"./README.md"
|
||||
],
|
||||
"description": "Read-only documentation access",
|
||||
"trust": true,
|
||||
"includeTools": ["read_file", "list_directory"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example 4: Custom Python MCP Server
|
||||
|
||||
**Use Case:** Integrate custom Python tools via MCP.
|
||||
|
||||
**Server File (`mcp_server.py`):**
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
import sys
|
||||
from mcp.server.stdio import stdio_server
|
||||
from mcp.server import Server
|
||||
from mcp.types import Tool, TextContent
|
||||
|
||||
server = Server("custom-tools")
|
||||
|
||||
@server.list_tools()
|
||||
async def list_tools() -> list[Tool]:
|
||||
return [
|
||||
Tool(
|
||||
name="analyze_python_code",
|
||||
description="Static analysis of Python code",
|
||||
inputSchema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"file_path": {"type": "string"}
|
||||
},
|
||||
"required": ["file_path"]
|
||||
}
|
||||
)
|
||||
]
|
||||
|
||||
@server.call_tool()
|
||||
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
|
||||
if name == "analyze_python_code":
|
||||
# Your custom logic here
|
||||
return [TextContent(type="text", text=f"Analysis of {arguments['file_path']}")]
|
||||
|
||||
async def main():
|
||||
async with stdio_server() as (read_stream, write_stream):
|
||||
await server.run(read_stream, write_stream, server.create_initialization_options())
|
||||
|
||||
if __name__ == "__main__":
|
||||
import asyncio
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"python-tools": {
|
||||
"command": "python",
|
||||
"args": ["mcp_server.py"],
|
||||
"env": {
|
||||
"PYTHONPATH": "${PWD}"
|
||||
},
|
||||
"description": "Custom Python analysis tools"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example 5: Docker-Based MCP Server
|
||||
|
||||
**Use Case:** Run MCP servers in isolated containers.
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"containerized-tools": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-v",
|
||||
"${PWD}:/workspace",
|
||||
"-w",
|
||||
"/workspace",
|
||||
"my-mcp-server:latest"
|
||||
],
|
||||
"description": "MCP tools running in Docker"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🔧 Configuration Tips
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Use environment variables for sensitive data:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"api-server": {
|
||||
"command": "node",
|
||||
"args": ["api-server.js"],
|
||||
"env": {
|
||||
"API_KEY": "${MY_API_KEY}",
|
||||
"DATABASE_URL": "$DB_CONNECTION"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Trust Settings
|
||||
|
||||
Trust servers you control to skip confirmation dialogs:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"trusted-server": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
|
||||
"trust": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Tool Filtering
|
||||
|
||||
Limit which tools are available:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"filesystem": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
|
||||
"includeTools": ["read_file", "list_directory"],
|
||||
"excludeTools": ["write_file", "move_file"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🎯 Common Use Cases
|
||||
|
||||
### Code Review Assistant
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"codebase": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
|
||||
"description": "Full codebase access for reviews"
|
||||
},
|
||||
"review-memory": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-memory"],
|
||||
"description": "Remember review comments and patterns"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
qwen
|
||||
|
||||
> Review the changes in src/components/
|
||||
> Remember: We follow the single responsibility principle
|
||||
> Check if all new components have tests
|
||||
```
|
||||
|
||||
### Documentation Generator
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"source": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"],
|
||||
"includeTools": ["read_file", "list_directory"]
|
||||
},
|
||||
"docs-writer": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./docs"],
|
||||
"includeTools": ["write_file", "create_directory"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Learning Assistant
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"tutorials": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"./tutorials",
|
||||
"./examples"
|
||||
],
|
||||
"trust": true
|
||||
},
|
||||
"learning-progress": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-memory"],
|
||||
"description": "Track learning progress and concepts"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🛠️ Troubleshooting
|
||||
|
||||
### Server Won't Connect
|
||||
|
||||
1. **Check the command is accessible:**
|
||||
```bash
|
||||
npx -y @modelcontextprotocol/server-filesystem ./
|
||||
```
|
||||
|
||||
2. **Verify directory permissions:**
|
||||
```bash
|
||||
ls -la ./
|
||||
```
|
||||
|
||||
3. **Check logs:**
|
||||
```bash
|
||||
qwen --debug
|
||||
```
|
||||
|
||||
### No Tools Discovered
|
||||
|
||||
Ensure the server actually provides tools:
|
||||
```bash
|
||||
qwen mcp list --schema
|
||||
```
|
||||
|
||||
### Tools Not Executing
|
||||
|
||||
- Check parameter schemas match
|
||||
- Verify timeout settings (increase if needed)
|
||||
- Test the server independently first
|
||||
|
||||
## 📖 Further Reading
|
||||
|
||||
- [MCP Server Documentation](./tools/mcp-server.md) - Complete reference
|
||||
- [Official MCP Specification](https://modelcontextprotocol.io/) - Protocol details
|
||||
- [MCP Server Examples](https://github.com/modelcontextprotocol/servers) - Community servers
|
||||
|
||||
## 🎓 Next Steps
|
||||
|
||||
1. ✅ Configure your first MCP server
|
||||
2. ✅ Verify connection with `qwen mcp list`
|
||||
3. ✅ Try basic file operations
|
||||
4. ✅ Add memory for persistent context
|
||||
5. ✅ Explore community MCP servers
|
||||
6. ✅ Build your own custom server
|
||||
|
||||
---
|
||||
|
||||
**Pro Tip:** Start with trusted local servers (`trust: true`) for faster iteration, then add confirmation for production use.
|
||||
382
docs/mcp-testing-validation.md
Normal file
382
docs/mcp-testing-validation.md
Normal file
@@ -0,0 +1,382 @@
|
||||
# MCP Testing & Validation Guide
|
||||
|
||||
This guide helps you test and validate your MCP server configurations.
|
||||
|
||||
## ✅ Quick Validation Checklist
|
||||
|
||||
### 1. Check MCP Servers Are Configured
|
||||
|
||||
```bash
|
||||
qwen mcp list
|
||||
```
|
||||
|
||||
**Expected output:**
|
||||
```
|
||||
Configured MCP servers:
|
||||
|
||||
✓ filesystem: npx -y @modelcontextprotocol/server-filesystem ./ (stdio) - Connected
|
||||
✓ memory: npx -y @modelcontextprotocol/server-memory (stdio) - Connected
|
||||
```
|
||||
|
||||
**Status indicators:**
|
||||
- ✓ (green) - Connected successfully
|
||||
- ✗ (red) - Connection failed or not connected
|
||||
|
||||
### 2. Verify Server Is Installed
|
||||
|
||||
Test the server command directly:
|
||||
|
||||
```bash
|
||||
# Filesystem server
|
||||
npx -y @modelcontextprotocol/server-filesystem --help
|
||||
|
||||
# Memory server
|
||||
npx -y @modelcontextprotocol/server-memory --help
|
||||
|
||||
# Custom server
|
||||
python mcp_server.py --help
|
||||
```
|
||||
|
||||
### 3. Check Configuration File Syntax
|
||||
|
||||
Validate your JSON configuration:
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
cat .qwen/settings.json | jq .
|
||||
|
||||
# Windows PowerShell
|
||||
Get-Content .qwen/settings.json | ConvertFrom-Json | ConvertTo-Json
|
||||
```
|
||||
|
||||
### 4. Test Within Qwen Code Session
|
||||
|
||||
Start an interactive session and check MCP status:
|
||||
|
||||
```bash
|
||||
qwen
|
||||
|
||||
# Inside the session:
|
||||
/mcp # Show all MCP servers and tools
|
||||
/mcp desc # Show tool descriptions
|
||||
/mcp schema # Show tool parameter schemas
|
||||
```
|
||||
|
||||
## 🧪 Test Cases
|
||||
|
||||
### Test Case 1: Filesystem Server
|
||||
|
||||
**Configuration:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"test-fs": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
|
||||
"trust": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Validation:**
|
||||
1. List files: Start `qwen` and ask "List all files in this directory"
|
||||
2. Read file: "Read the README.md file"
|
||||
3. Verify output contains actual file contents
|
||||
|
||||
**Expected Tools:**
|
||||
- `read_file` - Read file contents
|
||||
- `write_file` - Write to files
|
||||
- `list_directory` - List directory contents
|
||||
- `create_directory` - Create directories
|
||||
- `move_file` - Move/rename files
|
||||
- `search_files` - Search for files
|
||||
- `get_file_info` - Get file metadata
|
||||
|
||||
### Test Case 2: Memory Server
|
||||
|
||||
**Configuration:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"test-memory": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-memory"],
|
||||
"trust": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Validation:**
|
||||
1. Store information: "Remember that this project uses React 18"
|
||||
2. Query: "What JavaScript framework does this project use?"
|
||||
3. Verify it recalls the information from step 1
|
||||
|
||||
**Expected Tools:**
|
||||
- `create_entities` - Create knowledge entities
|
||||
- `create_relations` - Create relationships between entities
|
||||
- `add_observations` - Add observations to entities
|
||||
- `delete_entities` - Remove entities
|
||||
- `delete_observations` - Remove observations
|
||||
- `delete_relations` - Remove relationships
|
||||
- `read_graph` - Read entire knowledge graph
|
||||
- `search_nodes` - Search for specific nodes
|
||||
- `open_nodes` - Open specific nodes by name
|
||||
|
||||
### Test Case 3: Multiple Servers
|
||||
|
||||
**Configuration:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"files": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
|
||||
"trust": true
|
||||
},
|
||||
"memory": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-memory"],
|
||||
"trust": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Validation:**
|
||||
1. Check both servers are connected: `qwen mcp list`
|
||||
2. Use filesystem tool: "List all JavaScript files"
|
||||
3. Use memory tool: "Remember that we prefer TypeScript"
|
||||
4. Verify both tools work simultaneously
|
||||
|
||||
### Test Case 4: Tool Filtering
|
||||
|
||||
**Configuration:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"readonly-fs": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
|
||||
"includeTools": ["read_file", "list_directory"],
|
||||
"trust": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Validation:**
|
||||
1. Start qwen session
|
||||
2. Run `/mcp desc` to list available tools
|
||||
3. Verify only `read_file` and `list_directory` are present
|
||||
4. Verify `write_file`, `create_directory`, etc. are NOT available
|
||||
|
||||
### Test Case 5: Untrusted Server Confirmation
|
||||
|
||||
**Configuration:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"untrusted": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
|
||||
"trust": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Validation:**
|
||||
1. Ask qwen to read a file
|
||||
2. Confirmation dialog should appear before execution
|
||||
3. Options should include:
|
||||
- Proceed once
|
||||
- Always allow this tool
|
||||
- Always allow this server
|
||||
- Cancel
|
||||
|
||||
## 🔍 Debugging Failed Connections
|
||||
|
||||
### Issue: Server Shows "Disconnected"
|
||||
|
||||
**Diagnostic steps:**
|
||||
|
||||
1. **Test command manually:**
|
||||
```bash
|
||||
npx -y @modelcontextprotocol/server-filesystem ./
|
||||
```
|
||||
|
||||
2. **Check for errors:**
|
||||
```bash
|
||||
qwen --debug
|
||||
```
|
||||
|
||||
3. **Verify paths are correct:**
|
||||
```bash
|
||||
# Check if directory exists
|
||||
ls ./
|
||||
|
||||
# Check if command is in PATH
|
||||
which npx # Linux/macOS
|
||||
where npx # Windows
|
||||
```
|
||||
|
||||
4. **Check permissions:**
|
||||
```bash
|
||||
# Verify read/execute permissions
|
||||
ls -la ./
|
||||
```
|
||||
|
||||
5. **Review environment variables:**
|
||||
```bash
|
||||
echo $PATH
|
||||
echo $PYTHONPATH # For Python servers
|
||||
```
|
||||
|
||||
### Issue: No Tools Discovered
|
||||
|
||||
**Diagnostic steps:**
|
||||
|
||||
1. **Verify server implements MCP protocol:**
|
||||
```bash
|
||||
# For stdio servers, test input/output manually
|
||||
echo '{"jsonrpc": "2.0", "method": "initialize", "id": 1}' | npx -y @modelcontextprotocol/server-filesystem ./
|
||||
```
|
||||
|
||||
2. **Check server logs:**
|
||||
```bash
|
||||
# Some servers log to stderr
|
||||
qwen --debug 2>&1 | grep MCP
|
||||
```
|
||||
|
||||
3. **Verify server version:**
|
||||
```bash
|
||||
npm list -g @modelcontextprotocol/server-filesystem
|
||||
```
|
||||
|
||||
### Issue: Tools Fail to Execute
|
||||
|
||||
**Diagnostic steps:**
|
||||
|
||||
1. **Check parameter format:**
|
||||
- Ensure parameters match the expected schema
|
||||
- Verify JSON encoding is correct
|
||||
|
||||
2. **Increase timeout:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"slow-server": {
|
||||
"command": "...",
|
||||
"timeout": 60000
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Check server implementation:**
|
||||
- Verify the server actually implements the tool
|
||||
- Test the tool independently if possible
|
||||
|
||||
## 📊 Validation Results
|
||||
|
||||
### Expected Server Connection Times
|
||||
|
||||
| Server Type | Typical Connection Time | Timeout Recommendation |
|
||||
|-------------|------------------------|------------------------|
|
||||
| Filesystem | < 1 second | 10-30 seconds |
|
||||
| Memory | < 1 second | 10-30 seconds |
|
||||
| HTTP/SSE | 1-3 seconds | 30-60 seconds |
|
||||
| Custom Python | 2-5 seconds | 30-60 seconds |
|
||||
| Docker | 5-10 seconds | 60-120 seconds |
|
||||
|
||||
### Tool Execution Times
|
||||
|
||||
| Tool Type | Typical Duration | Timeout Recommendation |
|
||||
|-------------------|-----------------|------------------------|
|
||||
| Read file | < 100ms | 5-10 seconds |
|
||||
| List directory | < 500ms | 10-15 seconds |
|
||||
| Search files | 1-5 seconds | 30-60 seconds |
|
||||
| Memory operations | < 1 second | 10-30 seconds |
|
||||
| API calls | 1-10 seconds | 30-120 seconds |
|
||||
|
||||
## 🎯 Success Criteria
|
||||
|
||||
Your MCP configuration is working correctly if:
|
||||
|
||||
✅ `qwen mcp list` shows all servers as "Connected"
|
||||
✅ `/mcp` command in qwen session displays tools
|
||||
✅ Tool executions complete without errors
|
||||
✅ Confirmation dialogs appear for untrusted servers (if `trust: false`)
|
||||
✅ Tool filtering works as expected (include/exclude)
|
||||
✅ Environment variables are properly substituted
|
||||
✅ Timeouts are appropriate for your server's response time
|
||||
|
||||
## 🚀 Performance Tips
|
||||
|
||||
1. **Use `trust: true` for local servers** to skip confirmation dialogs
|
||||
2. **Set appropriate timeouts** - too low causes failures, too high slows down errors
|
||||
3. **Filter tools** - Only enable tools you actually need
|
||||
4. **Test servers independently** before configuring in qwen
|
||||
5. **Use `--debug` flag** during initial setup
|
||||
6. **Monitor resource usage** for long-running or resource-intensive servers
|
||||
|
||||
## 📝 Validation Script Example
|
||||
|
||||
Create a test script to automate validation:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# validate-mcp.sh
|
||||
|
||||
echo "Testing MCP configuration..."
|
||||
|
||||
# Test 1: Check config file exists
|
||||
if [ ! -f .qwen/settings.json ]; then
|
||||
echo "❌ Missing .qwen/settings.json"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ Config file exists"
|
||||
|
||||
# Test 2: Validate JSON syntax
|
||||
if ! cat .qwen/settings.json | jq . > /dev/null 2>&1; then
|
||||
echo "❌ Invalid JSON in settings.json"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ Valid JSON syntax"
|
||||
|
||||
# Test 3: Check servers are configured
|
||||
SERVER_COUNT=$(cat .qwen/settings.json | jq '.mcpServers | length')
|
||||
if [ "$SERVER_COUNT" -eq 0 ]; then
|
||||
echo "❌ No MCP servers configured"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ $SERVER_COUNT MCP server(s) configured"
|
||||
|
||||
# Test 4: Check connection status
|
||||
qwen mcp list | grep -q "Connected"
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✅ At least one server is connected"
|
||||
else
|
||||
echo "❌ No servers connected"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "✅ All validation checks passed!"
|
||||
```
|
||||
|
||||
## 📚 Next Steps
|
||||
|
||||
After validation:
|
||||
|
||||
1. **Start using MCP tools** in your workflow
|
||||
2. **Document your custom configurations** for team members
|
||||
3. **Share your successful configs** with the community
|
||||
4. **Monitor performance** and adjust timeouts as needed
|
||||
5. **Explore more MCP servers** from the community
|
||||
|
||||
---
|
||||
|
||||
**Having issues?** Check the [MCP troubleshooting guide](./tools/mcp-server.md#troubleshooting) or open an issue on GitHub.
|
||||
@@ -54,4 +54,7 @@ Qwen Code's built-in tools can be broadly categorized as follows:
|
||||
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.
|
||||
- **[MCP Quick Start Guide](../mcp-quick-start.md)**: Get started with MCP in 5 minutes with practical examples
|
||||
- **[MCP Example Configurations](../mcp-example-configs.md)**: Ready-to-use configurations for common scenarios
|
||||
- **[MCP Testing & Validation](../mcp-testing-validation.md)**: Test and validate your MCP server setups
|
||||
- **[Sandboxing](../sandbox.md)**: Sandboxing isolates the model and its changes from your environment to reduce potential risk.
|
||||
|
||||
Reference in New Issue
Block a user