项目简介

本项目是 'overflow2025' monorepo 中的一个组件，具体位于 'pkgs/mcp' 目录下。它实现了一个基于 Model Context Protocol (MCP) 的服务器，允许支持MCP协议的AI客户端（如GitHub Copilot Agent Mode）与之通信。该服务器主要功能是通过工具调用来访问外部资源和功能，特别是与一个单独运行的后端服务进行交互，该后端服务提供了获取天气信息以及通过 Walrus 分布式存储系统进行文件上传和下载的能力。同时集成了x402协议进行付费访问控制。

主要功能点

• MCP协议支持: 实现了Model Context Protocol，能够接收并处理AI客户端通过JSON-RPC发送的请求。
• 工具注册与执行: 注册了一个名为 'get-data-from-resource-server' 的工具，允许AI客户端调用该工具来执行特定任务。
• 外部资源访问: 通过注册的工具，能够调用一个独立的后端服务来获取数据（例如天气信息）或触发文件操作（通过Walrus）。
• x402付费访问集成: 在访问后端服务时，集成了x402协议，支持基于区块链的付费访问控制。
• Stdio传输协议: 使用Stdio作为与客户端通信的传输层。

安装步骤

1. 克隆仓库:

   git clone https://github.com/AO-protocol/overflow2025.git
   cd overflow2025
   

2. 安装依赖: 确保已安装 Node.js (v20+) 和 pnpm。

   pnpm install
   

服务器配置 (供MCP客户端使用)

作为MCP客户端（例如一个支持MCP的IDE插件），你需要配置如何启动和连接到这个MCP服务器进程。配置通常是一个JSON对象，包含以下关键信息：

• server name: 服务器的标识名称（例如：'x402-walrus'）。
• command: 启动MCP服务器进程的命令。对于本项目，命令是 'pnpm'。
• args: 传递给 command 的参数。参数应指定在 'pkgs/mcp' 目录中执行 'dev' 脚本。典型的参数列表是 '--silent', '-C', '<absolute path to this repo>/pkgs/mcp', 'dev'。其中 '<absolute path to this repo>/pkgs/mcp' 需要替换为你本地仓库中 'pkgs/mcp' 目录的绝对路径。
• env: MCP服务器进程运行所需的环境变量。需要在客户端配置中提供这些变量，客户端启动服务器进程时会将它们设置为进程的环境变量。本项目MCP服务器需要以下环境变量：
  • 'PRIVATE_KEY': 用于x402支付的钱包私钥 (Hex格式)。需要一个在 Base Sepolia 网络上有 USDC 的钱包。
  • 'RESOURCE_SERVER_URL': MCP服务器将要调用的后端服务的URL（例如：'http://localhost:4021'，对应于monorepo中启动的 Hono 后端）。
  • 'ENDPOINT_PATH': MCP服务器工具调用后端服务时使用的特定API路径（例如：'/weather' 或 '/download/:blobId'）。

此外，你需要先启动后端服务（通常在本地运行 monorepo 中的 'pkgs/backend' 服务），MCP服务器才能成功调用它。

基本使用方法

1. 按照上述安装步骤设置项目。
2. 创建并配置 'pkgs/backend/.env' 文件（提供 'FACILITATOR_URL', 'NETWORK', 'ADDRESS'）。
3. 创建并配置 'pkgs/mcp/.env' 文件（提供 'PRIVATE_KEY', 'RESOURCE_SERVER_URL', 'ENDPOINT_PATH'）。注意，虽然这里提到了'.env'，但客户端配置中的 'env' 会覆盖或作为主要的配置方式，'.env' 文件主要是为了本地开发和脚本运行方便。
4. 启动后端服务：在项目根目录运行 'pnpm backend dev'。
5. 在支持MCP的AI客户端中，配置该MCP服务器的启动命令和环境变量。
6. 启动AI客户端，客户端将通过配置的命令启动MCP服务器，并与之建立通信。
7. 通过AI客户端与LLM交互，当LLM判断需要获取天气或执行文件操作时，它会通过MCP协议调用该服务器注册的工具，服务器执行工具逻辑（调用后端服务），并将结果返回给LLM，最终由LLM呈现给用户。