TRAE 技术专家推荐：6个技巧让你的 Agent 更听话

def search_issues(    query: str,    repo: str = None,           # 默认搜索所有仓库    state: str = "open",        # 默认只搜索 open 状态    sort: str = "relevance",    # 默认按相关性排序    limit: int = 20             # 默认返回 20 条) -> str:    """    搜索 GitHub Issues。
    参数：    - query: 搜索关键词（必填）    - repo: 限定仓库，格式 owner/repo（可选，默认搜索所有可访问仓库）    - state: Issue 状态，可选 'open'|'closed'|'all'（可选，默认 'open'）    - sort: 排序方式，可选 'relevance'|'created'|'updated'（可选，默认 'relevance'）    - limit: 返回数量上限（可选，默认 20，最大 100）    """    pass

def search_issues(    query: str,    repo: str = None,           # 默认搜索所有仓库    state: str = "open",        # 默认只搜索 open 状态    sort: str = "relevance",    # 默认按相关性排序    limit: int = 20             # 默认返回 20 条) -> str:    """    搜索 GitHub Issues。        参数：    - query: 搜索关键词（必填）    - repo: 限定仓库，格式 owner/repo（可选，默认搜索所有可访问仓库）    - state: Issue 状态，可选 'open'|'closed'|'all'（可选，默认 'open'）    - sort: 排序方式，可选 'relevance'|'created'|'updated'（可选，默认 'relevance'）    - limit: 返回数量上限（可选，默认 20，最大 100）    """    pass

{"repo": {"type": "string","pattern": "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_.-]+$","description": "仓库名，格式为 owner/repo"  }}

{  "limit": {    "type": "integer",    "minimum": 1,    "maximum": 100,    "default": 20,    "description": "返回结果数量上限"  }}

def get_file_content(file_path: str) -> str:    """    获取文件内容。
    参数：    - file_path: 文件路径（支持绝对路径或相对于项目根目录的相对路径）    """    # Schema 定义的是 file_path，但也接受常见变体    # Agent 可能会传 path、filepath、file 等
    # 宽松解析示例（在实际代码中处理）    normalized_path = normalize_path(file_path)
    # 自动处理路径格式ifnot normalized_path.startswith('/'):        normalized_path = os.path.join(project_root, normalized_path)
return read_file(normalized_path)

def list_commits(    repo: str,    branch: str = "main",    page: int = 1,    per_page: int = 30) -> str:    """    列出仓库的提交历史。
    参数：    - repo: 仓库名，格式 owner/repo    - branch: 分支名（默认 'main'）    - page: 页码，从 1 开始（默认 1）    - per_page: 每页数量（默认 30，最大 100）
    返回包含分页信息的结果：{"commits": [...],"pagination": {"page": 1,"per_page": 30,"total_count": 150,"has_next": true      }    }"""    pass

{  "type": "object",  "properties": {    "query": { "type": "string", "description": "搜索关键词" },    "filters": {      "type": "object",      "description": "过滤条件（均为可选）",      "properties": {        "author": { "type": "string" },        "labels": { "type": "array", "items": { "type": "string" } },        "created_after": { "type": "string", "format": "date" }      }    },    "options": {      "type": "object",       "description": "查询选项（均为可选）",      "properties": {        "sort": { "type": "string", "enum": ["relevance", "created", "updated"] },        "limit": { "type": "integer", "default": 20 }      }    }  },  "required": ["query"]}

{  "type": "object",  "properties": {    "file_path": {      "type": "string",      "description": "要写入的文件路径"    },    "content": {      "type": "string",       "description": "要写入的文件内容"    },    "CONFIRM_OVERWRITE": {      "type": "string",      "enum": ["I confirm this will overwrite existing content"],      "description": "确认提醒：此参数的值必须是 'I confirm this will overwrite existing content'。在输出此参数前，请确认：1) 你已经读取过原文件内容 2) 你确定要覆盖而非追加 3) 用户明确要求了此操作"    }  },  "required": ["file_path", "content", "CONFIRM_OVERWRITE"]}

# ✅ 适合 JSON 的场景def get_user_profile(user_id: str) -> str:    return json.dumps({        "id": "usr_123",        "name": "Alice",        "email": "alice@example.com",        "role": "admin",        "created_at": "2024-01-15T10:30:00Z"    })
def list_issues(repo: str) -> str:    return json.dumps({        "issues": [            {"number": 1, "title": "Bug report", "state": "open"},            {"number": 2, "title": "Feature request", "state": "closed"}        ],        "total_count": 2    })

# ✅ 适合 Markdown 的场景def generate_report(data: dict) -> str:return """# 月度报告
## 概要- 总用户数：1,234- 活跃用户：567- 新增用户：89
## 详细分析..."""
def explain_error(error_code: str) -> str:return """## 错误说明
**错误代码**: AUTH_001
**含义**: 认证令牌已过期
**解决方案**:1. 检查令牌是否在有效期内2. 使用 refresh_token 获取新令牌3. 重新进行认证"""

def analyze_code(file_path: str) -> str:return json.dumps({"status": "completed","metrics": {"lines": 150,"complexity": 12,"issues_count": 3        },"summary": """## 代码分析结果
发现 3 个潜在问题：1. 函数 `processData` 复杂度过高2. 缺少错误处理3. 变量命名不规范""","issues": [            {"line": 45, "type": "complexity", "message": "..."},            {"line": 67, "type": "error_handling", "message": "..."},            {"line": 89, "type": "naming", "message": "..."}        ]    })

# ❌ 不好：直接 print 会干扰 MCP 通信def process_data(data: str) -> str:print("Processing...")  # 这会破坏 MCP 协议    result = do_processing(data)    print("Done!")  # 这也会return result
# ✅ 好：使用文件日志import logging
logger = logging.getLogger(__name__)logger.addHandler(logging.FileHandler('/tmp/mcp-tool.log'))
def process_data(data: str) -> str:    logger.info("Processing...")    result = do_processing(data)    logger.info("Done!")return json.dumps({"result": result})

# ❌ 不好：返回低级技术细节def get_user(user_id: str) -> str:    return json.dumps({        "uuid": "550e8400-e29b-41d4-a716-446655440000",  # 难以理解        "256px_image_url": "https://...",               # 过于具体        "mime_type": "image/jpeg",                      # Agent 通常不需要        "created_at_epoch": 1704067200                  # 需要转换    })
# ✅ 好：返回语义化、可理解的信息def get_user(user_id: str) -> str:    return json.dumps({        "name": "Alice Chen",                           # 可直接使用        "image_url": "https://...",                     # 简化字段名        "file_type": "jpeg",                            # 更直观        "created_at": "2024-01-01T00:00:00Z"           # 标准格式    })

# ❌ 不好：缺少上下文def create_issue(repo: str, title: str) -> str:    issue = github.create_issue(repo, title)    return str(issue.number)  # 只返回 issue 编号
# ✅ 好：包含完整上下文def create_issue(repo: str, title: str) -> str:    issue = github.create_issue(repo, title)    return json.dumps({        "status": "success",        "issue": {            "number": issue.number,            "title": issue.title,            "url": issue.html_url,      # Agent 可以直接分享给用户            "state": issue.state,            "created_at": issue.created_at.isoformat()        },        "message": f"Issue #{issue.number} created successfully"    })

def list_commits(repo: str, page: int = 1, per_page: int = 30) -> str:    commits, total = github.get_commits(repo, page, per_page)        return json.dumps({        "commits": [            {                "sha": c.sha[:7],                "message": c.message.split('\n')[0],  # 只取第一行                "author": c.author.login,                "date": c.date.isoformat()            }            for c in commits        ],        "pagination": {            "page": page,            "per_page": per_page,            "total_count": total,            "total_pages": (total + per_page - 1) // per_page,            "has_previous": page > 1,            "has_next": page * per_page < total        }    })

# ❌ 传统方式：抛出异常def get_user(user_id: str):    user = db.find(user_id)    ifnot user:        raise UserNotFoundError(f"User {user_id} not found")    return user
# ✅ Agent 友好：返回描述性错误def get_user(user_id: str) -> str:    """    返回：    - 成功时返回用户信息的 JSON 字符串    - 失败时返回错误描述，包含修正建议    """    user = db.find(user_id)    ifnot user:        return f"""User not found: {user_id}. Possible reasons:1. ID format incorrect - should be 'usr_' followed by 8 characters (e.g., 'usr_a1b2c3d4')2. User may have been deletedTry: Use find_user_by_email() if you have the user's email address."""    return json.dumps(user)

User not found: usr_invalid123

The ID format is incorrect - expected 'usr_' prefix followed by 8 alphanumeric characters.

Please verify the ID format ortry searching by email usingfind_user_by_email().

def get_user_by_id(user_id: str) -> str:    user = db.find_by_id(user_id)    ifnot user:        return f"""User not found with ID: {user_id}
Alternative approaches:1. Search by email: find_user_by_email(email="user@example.com")2. Search by username: find_user_by_username(username="john_doe")  3. List all users: list_users(limit=100) to browse available users"""    return json.dumps(user)

# 可恢复错误：Agent 可以尝试修正def api_call_with_retry_hint(params):    if rate_limited:        return "Rate limited. Please wait 60 seconds and retry."    if invalid_params:        return f"Invalid parameter 'date': expected YYYY-MM-DD format, got '{params['date']}'"
# 不可恢复错误：需要人工介入def sensitive_operation(params):    if not_authorized:        return """Permission denied. This operation requires admin privileges.        ⚠️ This cannot be resolved automatically. Please ask the user to:1. Contact their administrator to request access, or2. Use a different account with appropriate permissions"""

# 返回结构化的错误信息def structured_error_response(error_type, message, suggestions):    return json.dumps({        "status": "error",        "error_type": error_type,        "message": message,        "suggestions": suggestions,        "recoverable": True    })
# 使用示例returnstructured_error_response(    error_type="VALIDATION_ERROR",    message="Invalid email format",    suggestions=[        "Check if the email contains '@' symbol",        "Verify there are no spaces in the email",        "Use find_user_by_id() if you have the user ID instead"    ])

def github_create_issue(repo: str, title: str) -> str:    # 检查必要的配置    github_token = os.environ.get('GITHUB_TOKEN')        ifnot github_token:        return json.dumps({            "status": "configuration_error",            "error": "GitHub token not configured",            "message": """GITHUB_TOKEN environment variable is not set.
To fix this:1. Create a GitHub Personal Access Token at https://github.com/settings/tokens2. Set the environment variable:   - In your shell: export GITHUB_TOKEN=your_token_here   - In MCP config: add "env": {"GITHUB_TOKEN": "your_token_here"}
Required scopes: repo, read:org""",            "recoverable": False,            "requires_user_action": True        })        # 正常执行...

# ❌ 不好：直接暴露底层能力，让 Agent 自己处理list_contacts()         # 返回所有联系人，Agent 需要逐个筛选get_contact(id)         # Agent 需要知道 ID 才能调用
# ✅ 好：针对 Agent 的认知模式设计search_contacts(name="张")           # 直接返回匹配结果message_contact(name="张三")         # 内部处理搜索和发送

# ❌ 每个字段一个工具，需要多次调用get_user_name(user_id)      # 第 1 次调用get_user_email(user_id)     # 第 2 次调用get_user_address(user_id)   # 第 3 次调用get_user_phone(user_id)     # 第 4 次调用

# ❌ 一个工具返回所有信息get_user_all_data(user_id)  # 返回 50 个字段，包含完整的历史记录、偏好设置、活动日志...

# ❌ 差的设计：直接暴露底层 APIget_user_by_email(email)     # 第 1 次调用list_orders(user_id)         # 第 2 次调用get_order_status(order_id)   # 第 3 次调用

# ✅ 好的设计：围绕用户目标设计def track_order(email: str) -> str:    """    追踪用户的最新订单状态。        内部会自动查询用户信息、订单列表和物流状态，    返回格式化的订单追踪结果。    """    # 内部调用三个 API，组装结果    return "Order #12345 shipped via FedEx, arriving Thursday."

# ❌ 不好：直接暴露底层 API，需要多次调用list_users()           # 第 1 次调用list_events()          # 第 2 次调用create_event(...)      # 第 3 次调用
# ✅ 好：合并为面向目标的工具schedule_event(    participants=["alice@example.com", "bob@example.com"],    title="项目讨论",    duration_minutes=30)# 内部自动：查找用户 → 检查空闲时间 → 创建事件

# ❌ 不好：原始日志读取read_logs(file="/var/log/app.log")  # 返回大量无关日志
# ✅ 好：智能日志搜索search_logs(    keyword="error",    time_range="last_1h",    context_lines=3)# 只返回相关日志行及其上下文

# ❌ 不好：需要多次调用才能获取完整信息get_customer_by_id(customer_id)     # 基本信息list_transactions(customer_id)      # 交易记录list_notes(customer_id)             # 服务备注
# ✅ 好：一次性获取客户完整上下文get_customer_context(customer_id)# 返回客户基本信息 + 最近交易 + 重要备注的整合视图

# ✅ 合适的粒度：按场景组织get_user_profile(user_id)       # 返回姓名、邮箱、头像，展示用get_user_billing_info(user_id)  # 返回支付方式、账单地址，需要时才调get_user_activity_summary(user_id, days=7)  # 返回近 7 天活动摘要

# 观察到的调用模式：# 1. get_issue(id)# 2. get_issue_comments(id)  <-- 几乎总是紧跟着调用
# ✅ 考虑合并get_issue_with_comments(issue_id, include_comments=True)

# 原子工具：灵活但需要多步create_branch(repo, branch_name, from_branch)commit_changes(repo, branch, files, message)create_pull_request(repo, branch, title, body)
# 组合工具：一步完成常见工作流def quick_fix_and_pr(    repo: str,    file_path: str,    changes: str,    description: str) -> str:    """    快速修复并创建 PR（一步完成）。        自动执行以下步骤：    1. 创建新分支 (fix/auto-{timestamp})    2. 应用更改并提交    3. 创建 Pull Request        适用于简单的单文件修复。    对于复杂的多文件更改，请使用 create_branch + commit_changes + create_pull_request。    """    pass

# ❌ 不好：多个重叠的编辑工具edit_file_v1(path, content)edit_file_v2(path, changes)replace_line(path, line_number, new_content)replace_regex(path, pattern, replacement)patch_file(path, diff)
# ✅ 好：一个通用的编辑工具edit_file(path, changes, mode="replace")  # mode: replace | patch | regex

def server_info() -> str:    """    获取 MCP Server 的状态和配置信息。        用于诊断问题或验证配置是否正确。    返回版本信息、依赖状态、配置检查结果。    """    return json.dumps({        "version": "1.2.3",  # 动态读取，不要硬编码        "status": "healthy",        "dependencies": {            "github_api": {"status": "ok", "authenticated": True},            "database": {"status": "ok", "connection": "active"}        },        "configuration": {            "GITHUB_TOKEN": "configured"if os.environ.get('GITHUB_TOKEN') else"missing",            "LOG_LEVEL": os.environ.get('LOG_LEVEL', 'info'),            "MAX_RESULTS": os.environ.get('MAX_RESULTS', '100')        },        "issues": [            # 列出检测到的配置问题        ]    })

# /// script# requires-python = ">=3.11"# dependencies = [#     "requests==2.32.5",#     "markdown==3.10",# ]# ///
import requestsimport markdown
def fetch_and_convert(url: str) -> str:    response = requests.get(url)    return markdown.markdown(response.text)

uv run script.py      # 自动安装依赖并执行uvx some-cli-tool     # 直接从 PyPI 运行命令行工具

{  "mcpServers": {    "my-python-server": {      "command": "uv",      "args": ["run", "server.py"],      "cwd": "/path/to/server"    }  }}

## 执行脚本
运行分析脚本：
```bashuv run scripts/analyze.py --input data.json```

# 无需全局安装，直接运行包中的命令npx cowsay "Hello MCP"
# 指定版本运行npx typescript@5.0 --version
# 运行本地 package.json 中的脚本npx tsx script.ts

{  "type": "module",  "dependencies": {    "node-fetch": "^3.3.0",    "marked": "^12.0.0"  }}

# 安装依赖并运行（首次会自动 npm install）npm start# 或使用 npx 运行特定脚本npx tsx src/main.ts

# bunx 类似 npx，但更快bunx cowsay "Hello from Bun"
# 直接运行 TypeScript，无需编译bun run script.ts
# Bun 自动读取 package.json 依赖bun install && bun run start

# 编译为当前平台的可执行文件bun build ./server.ts --compile --outfile my-mcp-server
# 交叉编译到其他平台bun build ./server.ts --compile --target=bun-linux-x64 --outfile my-mcp-server-linuxbun build ./server.ts --compile --target=bun-darwin-arm64 --outfile my-mcp-server-macbun build ./server.ts --compile --target=bun-windows-x64 --outfile my-mcp-server.exe

// deps.ts - 集中管理依赖export { serve } from "https://deno.land/std@0.220.0/http/server.ts";export { parse } from "https://deno.land/std@0.220.0/flags/mod.ts";
// main.tsimport { serve, parse } from "./deps.ts";
const args = parse(Deno.args);serve((req) => new Response("Hello MCP"));

# 显式授予权限deno run --allow-net --allow-read main.ts
# 或使用配置文件deno task start

## 运行时要求
- Python 脚本：使用 `uv run` 执行- TypeScript 脚本：使用 `bun run` 或 `npx tsx` 执行- 不要使用全局安装的包，始终通过包管理器运行

# 从 HTTP MCP Server 生成 CLInpx mcporter generate-cli --command https://mcp.linear.app/mcp
# 从 stdio MCP Server 生成 CLInpx mcporter generate-cli --command "npx -y chrome-devtools-mcp@latest"
# 生成并编译为独立可执行文件npx mcporter generate-cli linear --compile --output dist/linear

## 工具
使用 Linear CLI 进行 Issue 操作：
\`\`\`bash# 搜索 Issueslinear search_issues query="bug" state=open
# 创建 Issuelinear create_issue title="Fix login bug" team=ENG\`\`\`

## 工具 使用 Linear CLI 进行 Issue 操作： \`\`\`bash # 搜索 Issues linear search_issues query="bug" state=open # 创建 Issue linear create_issue title="Fix login bug" team=ENG \`\`\`

# 生成类型定义npx mcporter emit-ts linear --out types/linear.d.ts
# 生成完整的客户端包装器npx mcporter emit-ts linear --mode client --out clients/linear.ts

import { createRuntime, createServerProxy } from "mcporter";
const runtime = await createRuntime();const linear = createServerProxy(runtime, "linear");
// 强类型调用const issues = await linear.searchIssues({ query: "bug", state: "open" });const issue = await linear.createIssue({ title: "Fix login", team: "ENG" });
await runtime.close();