mirror of
https://github.com/QwenLM/qwen-code.git
synced 2025-12-19 09:33:53 +00:00
Merge pull request #796 from sontoriyama/docs/add-mcp-quick-start-guides
docs: add comprehensive MCP Quick Start guides and examples
This commit is contained in:
pomelo
GitHub
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,3 +54,7 @@ Qwen Code's built-in tools can be broadly categorized as follows:
|
|||||||
Additionally, these tools incorporate:
|
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 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