---
name: mcp-usage
description: How to use MCP (Model Context Protocol) tools. Available tools, calling patterns, and best practices.
allowed-tools: mcp_call, mcp_list_servers, mcp_tool_schema, mcp_reload, Read, Write, Edit, Glob, Grep, execute_command
---

# MCP Usage Guide

> How to use MCP tools in this environment.

---

## 1. Available Tools

### mcp_list_servers

列出所有已连接的 MCP 服务器及其工具。

```
mcp_list_servers()
```

返回示例：

```json
{
  "success": true,
  "servers": [{ "name": "fetch", "tools": [{ "name": "fetch", "description": "..." }] }]
}
```

### mcp_tool_schema

查询工具的完整参数结构，直接返回可复制的调用示例。

```
mcp_tool_schema({ server: "服务器名", tool: "工具名" })
```

返回示例：

```json
{
  "success": true,
  "result": {
    "name": "fetch",
    "description": "Fetches a URL from the internet...",
    "required": ["url"],
    "example": "{\"url\": \"https://example.com\"}",
    "fullExample": "mcp_call({ server: \"fetch\", tool: \"fetch\", args_json: '{\"url\": \"https://...\"}' })"
  }
}
```

### mcp_call

调用 MCP 服务器的工具。

```
mcp_call({
  server: "服务器名",
  tool: "工具名",
  args_json: '{"参数名": "参数值"}'
})
```

**重要**：

- `args_json` 必须是有效的 JSON 字符串
- 必填参数不能为空
- 如果不知道参数结构，先用 `mcp_tool_schema` 查询

### mcp_reload

重新加载 MCP 配置。当 `.agent/mcp_config.json` 修改后使用。

```
mcp_reload()
```

---

## 2. Calling Patterns

### 简单参数调用

```javascript
// 调用 fetch 工具获取网页
mcp_call({
  server: 'fetch',
  tool: 'fetch',
  args_json: '{"url": "https://news.baidu.com"}',
});
```

### 多个参数调用

```javascript
// 调用搜索工具
mcp_call({
  server: 'bing-cn-mcp-server',
  tool: 'bing_search',
  args_json: '{"query": "关键词", "count": 10}',
});
```

### 复杂参数调用

对于复杂参数（嵌套对象、数组等）：

1. 先查询参数结构：

```
mcp_tool_schema({ server: "服务器", tool: "工具" })
```

2. 根据返回的 `example` 或 `fullExample` 构造调用

---

## 3. Error Handling

### 参数为空

如果忘记传参数，会返回错误：

```json
{
  "success": false,
  "error": "参数为空！必须提供: url",
  "hint": "正确格式: {\"url\": \"具体值\"}"
}
```

### 参数格式错误

如果 JSON 格式不正确：

```json
{
  "success": false,
  "error": "args_json 格式错误，不是有效的 JSON"
}
```

### 服务器不存在

```json
{
  "success": false,
  "error": "MCP server 'xxx' not found"
}
```

---

## 4. Configuration

MCP 服务器配置在 `.agent/mcp_config.json`：

```json
{
  "mcpServers": {
    "服务器名": {
      "type": "sse",
      "url": "https://...",
      "headers": {
        "Authorization": "Bearer xxx"
      }
    }
  }
}
```

添加或修改配置后，调用 `mcp_reload()` 重载。

---

## 5. Best Practices

- [ ] 不知道参数时，先用 `mcp_tool_schema` 查询
- [ ] `args_json` 必须是有效的 JSON 字符串（用单引号包裹整个 JSON）
- [ ] 必填参数必须提供
- [ ] 修改配置后用 `mcp_reload()` 重载
- [ ] 使用前先 `mcp_list_servers` 查看可用服务器

---

## 6. Quick Reference

| 场景           | 操作                                                    |
| -------------- | ------------------------------------------------------- |
| 查看可用服务器 | `mcp_list_servers()`                                    |
| 查询参数结构   | `mcp_tool_schema({ server: "x", tool: "y" })`           |
| 调用工具       | `mcp_call({ server: "x", tool: "y", args_json: '{}' })` |
| 重载配置       | `mcp_reload()`                                          |

---

> **Tip:** 当工具调用失败时，仔细阅读错误信息，它会告诉你缺少什么参数或格式问题。
