【OpenCode系统性指南】第8篇：MCP入门：连接外部数据源

概念图

引言

想象一下，如果你的电脑每次连接新设备都需要安装专门的驱动程序——鼠标要用鼠标驱动，键盘要用键盘驱动，U盘要用U盘驱动——这将是一个多么混乱的世界。USB 协议的出现彻底改变了这一切：一个标准接口，连接万物。

AI 应用今天面临着同样的困境。每个 AI 工具想要访问文件系统、查询数据库、调用 API，都需要单独开发集成方案。如果有 M 个 AI 应用和 N 个数据源，就需要开发 M × N 个集成。Model Context Protocol（MCP）正是为解决这个问题而生的"AI 的 USB 接口"。

本文将带你系统性地理解 MCP 协议，从核心概念到实战配置，帮助你构建一个真正"万物互联"的 AI 工作环境。

一、什么是 MCP

1.1 AI 的 USB 接口

Model Context Protocol（MCP） 是 Anthropic 在 2024 年底推出的开放协议，旨在标准化 AI 应用与外部数据源、工具之间的连接方式。

类比理解：

USB 协议	MCP 协议
统一硬件连接标准	统一 AI 数据连接标准
鼠标、键盘、U盘	文件系统、数据库、API
即插即用	配置即用
驱动程序	MCP 服务器

1.2 解决 M × N 集成问题

在 MCP 出现之前，AI 集成面临严重的碎片化问题：

传统方案：
┌─────────┐     ┌─────────┐     ┌─────────┐
│ Claude  │────▶│ 文件系统 │     │  数据库  │
└─────────┘     └─────────┘     └─────────┘
┌─────────┐     ┌─────────┐     ┌─────────┐
│ VS Code │────▶│  Git    │────▶│  API    │
└─────────┘     └─────────┘     └─────────┘

M 个应用 × N 个数据源 = M × N 个集成

MCP 的解决方案：

MCP 方案：
┌─────────┐                      ┌─────────┐
│ Claude  │──┐                  ┌│ 文件系统 │
└─────────┘  │   ┌─────────┐   │└─────────┘
┌─────────┐  └──▶│   MCP   │───┤┌─────────┐
│ VS Code │─────▶│  协议   │   ││  数据库  │
└─────────┘      └─────────┘   │└─────────┘
                                │┌─────────┐
                                └│  Git    │
                                 └─────────┘

M + N 个实现（M 个客户端 + N 个服务器）

这意味着：一次开发，处处可用。

二、MCP 架构详解

2.1 三层架构模型

MCP 采用经典的客户端-服务器架构，包含三个核心角色：

┌────────────────────────────────────────────────────┐
│                    Host（宿主）                     │
│  用户交互的应用程序：Claude Desktop、VS Code、Cursor │
│                                                    │
│  ┌──────────────────────────────────────────────┐ │
│  │              Client（客户端）                  │ │
│  │  • 管理 MCP 服务器连接                         │ │
│  │  • 处理协议握手和能力协商                       │ │
│  │  • 维护 1:1 的服务器连接                       │ │
│  └──────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────┘
                        │
                        │ MCP 协议
                        ▼
┌────────────────────────────────────────────────────┐
│              Server（服务器）                       │
│  • 暴露 Tools（工具）                              │
│  • 暴露 Resources（资源）                          │
│  • 暴露 Prompts（提示词）                          │
└────────────────────────────────────────────────────┘

各角色职责：

角色	职责	示例
Host	用户交互入口，承载 AI 会话	Claude Desktop、VS Code、Cursor、OpenCode
Client	协议实现，管理服务器连接	内置于 Host 中，对用户透明
Server	暴露能力，连接外部数据源	filesystem、memory、github

2.2 连接生命周期

MCP 连接遵循标准的生命周期：

初始化：Client 发送 initialize 请求，协商协议版本和能力
运行：双方交换请求和通知
关闭：任意一方发送关闭信号，清理资源

三、三大核心能力

MCP 服务器可以提供三种不同类型的能力，每种能力有不同的控制方和使用场景。

3.1 Tools（工具）

控制方：模型（AI）

Tools 是可被 AI 模型主动调用的函数，类似于 Function Calling。

{
  "name": "read_file",
  "description": "读取指定路径的文件内容",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "文件路径" }
    },
    "required": ["path"]
  }
}

特点：

由 AI 模型决定何时调用
支持参数验证
可返回结构化结果

典型用例：文件读写、API 调用、数据库查询、执行命令

3.2 Resources（资源）

控制方：应用

Resources 是只读的数据源，类似 REST API 的 GET 端点。

{
  "uri": "file:///project/src/main.go",
  "name": "main.go",
  "mimeType": "text/x-go"
}

特点：

应用控制访问时机
支持 URI 定位
可订阅变更通知

典型用例：文件内容、数据库记录、配置信息、日志数据

3.3 Prompts（提示词）

控制方：用户

Prompts 是预定义的提示词模板，用户可选择使用。

{
  "name": "code_review",
  "description": "对指定文件进行代码审查",
  "arguments": [
    { "name": "file", "description": "要审查的文件路径" }
  ]
}

特点：

用户手动触发
支持参数化模板
标准化工作流

典型用例：代码审查模板、文档生成模板、问题分析模板

3.4 能力对比总结

能力	控制方	可变性	典型用途
Tools	AI 模型	可执行操作	执行任务、修改数据
Resources	应用	只读	提供上下文、数据源
Prompts	用户	模板	标准化工作流

四、传输方式

MCP 支持多种传输协议，适用于不同场景。

4.1 stdio 传输

最常用的本地传输方式，通过标准输入/输出通信。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

适用场景：本地进程、快速开发、无需网络

优点：简单可靠、无端口冲突、安全性高

4.2 HTTP/SSE 传输

支持远程服务器的传输方式。

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

适用场景：远程服务、分布式部署、多客户端共享

优点：支持远程访问、易于扩展、便于监控

4.3 传输方式对比

方式	通信渠道	适用场景	安全性
stdio	标准输入/输出	本地进程	高（本机限制）
HTTP/SSE	HTTP + Server-Sent Events	远程服务器	需额外配置

截图说明

五、配置第一个 MCP 服务器

5.1 配置文件位置

不同客户端的配置文件位置：

客户端	配置文件路径
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
VS Code	`.vscode/mcp.json` 或设置中配置
OpenCode	`opencode.json` 的 `mcpServers` 字段

5.2 基础配置格式

{
  "mcpServers": {
    "服务器名称": {
      "command": "启动命令",
      "args": ["参数列表"],
      "env": {
        "环境变量名": "环境变量值"
      }
    }
  }
}

5.3 文件系统服务器配置

文件系统 MCP 服务器是最常用的入门服务器：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects",
        "/Users/username/documents"
      ]
    }
  }
}

参数说明：

-y：自动确认 npx 安装
@modelcontextprotocol/server-filesystem：官方文件系统服务器包
后续参数：允许访问的目录列表（白名单机制）

六、文件系统 MCP 实战

6.1 安装和启动

文件系统服务器通过 npx 运行，无需预安装：

# 直接运行（命令行测试）
npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir

6.2 提供的工具

文件系统服务器提供以下核心工具：

工具名	功能	参数
`read_file`	读取文件内容	`path`: 文件路径
`write_file`	写入文件	`path`, `content`
`list_directory`	列出目录内容	`path`: 目录路径
`create_directory`	创建目录	`path`: 目录路径
`move_file`	移动/重命名文件	`source`, `destination`
`search_files`	搜索文件	`path`, `pattern`
`get_file_info`	获取文件元信息	`path`: 文件路径

6.3 实际使用示例

配置完成后，在 AI 对话中即可使用：

用户：读取 projects/my-app 目录下的所有 Go 文件

AI：我来帮你查找 projects/my-app 目录下的 Go 文件。
[调用 list_directory 和 search_files 工具]

找到以下 Go 文件：
- main.go
- handler.go
- service.go
- model.go

需要我读取哪个文件的内容？

6.4 安全机制

文件系统服务器实现了多层安全保护：

目录白名单：只能访问配置中指定的目录
路径验证：阻止目录遍历攻击（如 ../../../etc/passwd）
只读选项：可通过参数限制为只读模式

七、常用 MCP 服务器推荐

7.1 官方服务器列表

服务器	用途	安装命令
filesystem	文件读写操作	`npx -y @modelcontextprotocol/server-filesystem`
memory	知识图谱持久化记忆	`npx -y @modelcontextprotocol/server-memory`
git	Git 仓库操作	`uvx mcp-server-git`
fetch	网页内容抓取	`uvx mcp-server-fetch`
github	GitHub API 集成	Docker: `ghcr.io/github/github-mcp-server`

7.2 服务器详解

Memory Server：基于本地知识图谱的记忆系统

存储实体、关系、观察
跨会话持久化
适合需要"记住"信息的场景

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Git Server：Git 操作的 MCP 封装

status、diff、log、branch
commit、push、pull
适合版本控制工作流

{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/path/to/repo"]
    }
  }
}

GitHub Server：GitHub 官方 MCP 服务器

60+ 工具覆盖完整 GitHub API
Issue、PR、Actions 集成
代码搜索、仓库管理

7.3 社区资源

社区维护了丰富的 MCP 服务器生态：

Awesome MCP Servers：github.com/punkpeye/awesome-mcp-servers
涵盖：数据库、云服务、开发工具、API 集成等类别

八、MCP 与 OpenCode 集成

OpenCode 原生支持 MCP 协议，配置方式与其他客户端类似。

8.1 配置位置

在 opencode.json 中添加 mcpServers 字段：

{
  "providers": { ... },
  "agents": { ... },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/projects"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

8.2 工具继承机制

配置的 MCP 工具会自动添加到 Coder Agent：

// OpenCode 源码：工具集组装
func CoderAgentTools(...) []tools.BaseTool {
    return append(
        []tools.BaseTool{
            tools.NewBashTool(permissions),
            tools.NewEditTool(...),
            // 内置工具...
        },
        GetMcpTools(ctx, permissions)...,  // MCP 工具自动继承
    )
}

这意味着 MCP 工具与内置工具享有同等地位，AI 可无缝调用。

小结

MCP 是 AI 的 USB：一个协议连接所有数据源，解决 M × N 集成碎片化问题
三层架构：Host（宿主）→ Client（客户端）→ Server（服务器），职责清晰
三大能力：Tools（工具-模型控制）、Resources（资源-应用控制）、Prompts（提示词-用户控制）
双传输模式：stdio 适合本地，HTTP/SSE 适合远程
配置简单：JSON 配置即可启用，无需编程
生态丰富：官方提供 filesystem、memory、git、github 等服务器，社区持续扩展

【OpenCode系统性指南】第8篇：MCP入门：连接外部数据源

【OpenCode系统性指南】第8篇：MCP入门：连接外部数据源

引言

一、什么是 MCP

1.1 AI 的 USB 接口

1.2 解决 M × N 集成问题

二、MCP 架构详解

2.1 三层架构模型

2.2 连接生命周期

三、三大核心能力

3.1 Tools（工具）

3.2 Resources（资源）

3.3 Prompts（提示词）

3.4 能力对比总结

四、传输方式

4.1 stdio 传输

4.2 HTTP/SSE 传输

4.3 传输方式对比

五、配置第一个 MCP 服务器

5.1 配置文件位置

5.2 基础配置格式

5.3 文件系统服务器配置

六、文件系统 MCP 实战

6.1 安装和启动

6.2 提供的工具

6.3 实际使用示例

6.4 安全机制

七、常用 MCP 服务器推荐

7.1 官方服务器列表

7.2 服务器详解

7.3 社区资源

八、MCP 与 OpenCode 集成

8.1 配置位置

8.2 工具继承机制

小结

延伸阅读