AI-Agent

13.4 常用 MCP 服务器

Filesystem Server

功能

提供文件系统访问能力，支持读取、写入文件和目录操作。

安装

1
2
3
npm install -g @modelcontextprotocol/server-filesystem
# 或使用 npx
npx -y @modelcontextprotocol/server-filesystem

配置

1
2
3
4
5
6
{
  "name": "filesystem",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
  "enabled": true
}

可用工具

工具 描述
read_file 读取文件内容
write_file 写入文件内容
create_directory 创建目录
list_directory 列出目录内容
move_file 移动/重命名文件
search_files 搜索文件

使用示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// 读取文件
{
  "name": "filesystem:read_file",
  "arguments": {
    "path": "/tmp/test.txt"
  }
}

// 写入文件
{
  "name": "filesystem:write_file",
  "arguments": {
    "path": "/tmp/output.txt",
    "content": "Hello World!"
  }
}

// 列出目录
{
  "name": "filesystem:list_directory",
  "arguments": {
    "path": "/tmp"
  }
}

GitHub Server

功能

提供 GitHub 仓库操作能力，可以管理 issues、pull requests、文件等。

安装

1
npm install -g @modelcontextprotocol/server-github

配置

1
2
3
4
5
6
7
8
9
{
  "name": "github",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
  },
  "enabled": false
}

获取 GitHub Token

  1. 访问 https://github.com/settings/tokens
  2. 点击 “Generate new token (classic)”
  3. 选择所需权限
  4. 生成并复制 token

可用工具

工具 描述
create_issue 创建 issue
create_pull_request 创建 PR
push_files 推送文件
read_file 读取仓库文件
list_issues 列出 issues

使用示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// 创建 Issue
{
  "name": "github:create_issue",
  "arguments": {
    "owner": "facebook",
    "repo": "react",
    "title": "Bug: Component not rendering",
    "body": "描述问题..."
  }
}

// 读取文件
{
  "name": "github:read_file",
  "arguments": {
    "owner": "facebook",
    "repo": "react",
    "path": "README.md",
    "branch": "main"
  }
}

PostgreSQL Server

功能

提供 PostgreSQL 数据库查询能力。

安装

1
npm install -g @modelcontextprotocol/server-postgres

配置

1
2
3
4
5
6
7
8
9
{
  "name": "postgres",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-postgres"],
  "env": {
    "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/dbname"
  },
  "enabled": false
}

可用工具

工具 描述
query 执行 SQL 查询
execute_sql 执行 SQL 语句

使用示例

1
2
3
4
5
6
7
// 查询数据
{
  "name": "postgres:query",
  "arguments": {
    "query": "SELECT * FROM users WHERE age > 18"
  }
}

Brave Search Server

功能

提供网页搜索能力（类似 Tavily）。

安装

1
npm install -g @modelcontextprotocol/server-brave-search

配置

1
2
3
4
5
6
7
8
9
{
  "name": "brave-search",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-brave-search"],
  "env": {
    "BRAVE_SEARCH_API_KEY": "your-api-key"
  },
  "enabled": false
}

可用工具

工具 描述
brave_web_search 网页搜索
brave_search 搜索（别名）

使用示例

1
2
3
4
5
6
7
{
  "name": "brave-search:brave_web_search",
  "arguments": {
    "query": "TypeScript 5.0 新特性",
    "count": 5
  }
}

Puppeteer Server

功能

提供网页自动化能力，可以控制浏览器进行操作。

安装

1
npm install -g @modelcontextprotocol/server-puppeteer

配置

1
2
3
4
5
6
{
  "name": "puppeteer",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
  "enabled": false
}

可用工具

工具 描述
navigate_to 导航到 URL
screenshot 截取屏幕截图
click 点击元素
fill 填写表单
get_pdf 获取 PDF 内容

使用示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// 导航并截图
{
  "name": "puppeteer:navigate_to",
  "arguments": {
    "url": "https://example.com"
  }
}

{
  "name": "puppeteer:screenshot",
  "arguments": {
    "path": "/tmp/screenshot.png"
  }
}

配置示例

完整配置文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
  "mcp": {
    "enabled": true,
    "servers": [
      {
        "name": "filesystem",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"],
        "enabled": true
      },
      {
        "name": "filesystem-home",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "~"],
        "enabled": true
      },
      {
        "name": "github",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "${GITHUB_TOKEN}"
        },
        "enabled": false
      },
      {
        "name": "postgres",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-postgres"],
        "env": {
          "POSTGRES_CONNECTION_STRING": "${POSTGRES_URL}"
        },
        "enabled": false
      },
      {
        "name": "brave-search",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-brave-search"],
        "env": {
          "BRAVE_SEARCH_API_KEY": "${BRAVE_API_KEY}"
        },
        "enabled": false
      }
    ]
  }
}

工具发现和测试

列出可用工具

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { MCPManager } from "./mcp/index.js";

const mcpManager = new MCPManager();
mcpManager.connectAll();

// 获取所有工具
const tools = mcpManager.getAllTools();

for (const [name, info] of tools.entries()) {
  console.log(`服务器: ${info.server}`);
  console.log(`工具: ${name}`);
  console.log(`描述: ${info.tool.description}`);
  console.log('---');
}

测试工具调用

1
2
3
4
5
6
// 测试文件系统工具
const result = await mcpManager.callTool("filesystem:read_file", {
  path: "/tmp/test.txt"
});

console.log(result.content[0].text);

安全考虑

权限控制

1
2
3
4
5
6
7
// 限制文件系统访问路径
{
  "name": "filesystem-safe",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/safe/path"],
  "enabled": true
}

环境变量隔离

1
2
3
4
5
6
7
8
9
10
// 使用专用 token
{
  "name": "github-read-only",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_TOKEN": "${GITHUB_READ_ONLY_TOKEN}"
  },
  "enabled": false
}

服务器禁用控制

1
2
3
4
5
{
  "name": "sensitive-server",
  "command": "...",
  "enabled": false  // 默认禁用，需要时手动启用
}

故障排除

连接失败

1
错误: 连接到 MCP 服务器 "github" 失败

解决方案：

  1. 检查服务器是否安装：npx -y @modelcontextprotocol/server-github --version
  2. 检查环境变量是否正确设置
  3. 检查网络连接
  4. 查看服务器日志

工具调用失败

1
错误: 工具 "github:create_issue" 不存在

解决方案：

  1. 确认服务器已连接
  2. 检查工具名称是否正确
  3. 查看可用的工具列表

权限错误

1
错误: Permission denied (filesystem)

解决方案：

  1. 检查访问路径的权限
  2. 使用正确的用户运行服务器
  3. 调整服务器配置

小结

本节介绍了常用的 MCP 服务器：

  • Filesystem Server - 文件系统操作
  • GitHub Server - GitHub 仓库管理
  • PostgreSQL Server - 数据库查询
  • Brave Search Server - 网页搜索
  • Puppeteer Server - 浏览器自动化
  • 配置示例和安全考虑

第十三章总结

本章详细介绍了 MCP 集成的实现：

13.1 MCP 协议概述

  • MCP 的定义和设计目标
  • 核心概念（Client、Server、Transport）
  • 三大能力（Tools、Resources、Prompts）

13.2 MCP 服务器连接

  • 服务器配置结构
  • StdioClientTransport 原理
  • 连接和断开流程
  • 多服务器管理

13.3 工具适配器实现

  • 适配器模式设计
  • MCPToolAdapter 类
  • 参数转换和验证
  • 工具注册流程

13.4 常用 MCP 服务器

  • Filesystem Server
  • GitHub Server
  • PostgreSQL Server
  • Brave Search Server
  • Puppeteer Server

通过本章的学习，你已经掌握了如何通过 MCP 协议扩展 Agent 的能力，连接到各种外部服务和数据源。

下一章： 第十四章：总结与展望

导航

上一篇： 13.3 工具适配器实现

下一篇： 14.1 项目完整回顾