使用说明

本项目是用于学习和构建MCP（Model Context Protocol）服务器和客户端的Go语言工作坊示例。它展示了如何使用'mcp-go'库来实现MCP服务器的核心功能，特别聚焦于工具的注册与调用，以及不同传输协议（Stdio、HTTP、SSE）的应用。

项目简介

仓库 'go-training/mcp-workshop' 提供了一系列Go语言示例，旨在指导开发者理解和实现Model Context Protocol (MCP)。这些示例不仅展示了MCP服务器的基本构建方法，还包括了如何集成常见的Web框架（如Gin）以及如何处理认证等进阶话题。它是学习如何为大型语言模型（LLM）应用构建强大上下文服务后端的实用资源。

主要功能点

MCP服务器实现: 包含多个可运行的MCP服务器示例。
工具注册与调用: 演示如何定义MCP工具（Tools），注册对应的处理函数，并使其可被MCP客户端调用。示例中包含了简单的Echo工具、加法工具以及模拟需要认证的HTTP请求工具。
多种传输协议支持: 示例服务器支持通过标准输入输出（Stdio）、HTTP 和 Server-Sent Events (SSE) 与MCP客户端进行通信。
上下文处理: 展示了如何在MCP服务器处理流程中传递请求上下文，例如通过HTTP Header 或环境变量传递认证Token。
基于 'mcp-go' 库: 使用成熟的Go语言MCP库简化开发过程。

安装步骤

克隆仓库:

git clone https://github.com/go-training/mcp-workshop.git
cd mcp-workshop

进入示例目录并构建: 选择一个示例进行构建。例如，进入 '01-example-basic-gin' 或 '02-example-basic-token-passthrough' 目录。
```
cd 01-example-basic-gin # 或 cd 02-example-basic-token-passthrough
go build
```
构建成功后，会在当前目录下生成一个可执行文件（文件名与目录名相同）。

服务器配置信息（供MCP客户端参考）

MCP客户端需要知道如何启动或连接到MCP服务器。以下是根据本项目示例生成的典型配置信息结构及其参数说明。请注意，这不是实际的JSON代码，而是描述客户端配置所需的信息。

配置结构示例

{
  "server_name": "服务器名称",
  "command": "服务器可执行文件路径",
  "args": ["参数1", "参数2", ...],
  // 其他可能的连接配置，取决于客户端实现和传输协议
  // 例如，对于HTTP/SSE: "url": "http://localhost:8080/mcp"
}

本项目示例对应的配置信息

根据您选择运行的示例及其启动方式，对应的配置信息如下：

示例 1: '01-example-basic-gin' (带有'echo_message', 'add_numbers'工具)

服务器名称: 'mcp-with-gin-path-example'
Command: './01-example-basic-gin' (假设您已在 '01-example-basic-gin' 目录下执行 'go build')
Args (根据传输协议选择):
- Stdio 传输: '["--transport", "stdio"]'
  - '--transport': 指定使用 stdio 协议。
- SSE 传输: '["--transport", "sse", "--addr", ":8080"]'
  - '--transport': 指定使用 sse 协议。
  - '--addr': 指定服务器监听的地址和端口，例如 ':8080'。客户端连接时需要知道此地址。
- HTTP 传输: '["--transport", "http", "--addr", ":8080"]'
  - '--transport': 指定使用 http 协议。
  - '--addr': 指定服务器监听的地址和端口，例如 ':8080'。客户端连接时需要知道此地址。
其他可能的连接信息 (HTTP/SSE): 客户端可能需要额外的 URL 配置。对于HTTP，通常是 'http://<addr>/mcp' (例如 'http://localhost:8080/mcp')；对于SSE，通常是 'http://<addr>' (例如 'http://localhost:8080')。

示例 2: '02-example-basic-token-passthrough' (带有'make_authenticated_request', 'show_auth_token'工具)

服务器名称: 'example-server'
Command: './02-example-basic-token-passthrough' (假设您已在 '02-example-basic-token-passthrough' 目录下执行 'go build')
Args (根据传输协议选择):
- Stdio 传输: '["--transport", "stdio"]'
  - '--transport': 指定使用 stdio 协议。注意：对于 Stdio 传输，此示例通过 'API_KEY' 环境变量获取认证 Token。您需要在启动服务器进程前设置该环境变量。
- HTTP 传输: '["--transport", "http", "--addr", ":8080"]'
  - '--transport': 指定使用 http 协议。
  - '--addr': 指定服务器监听的地址和端口，例如 ':8080'。客户端连接时需要知道此地址。注意：对于 HTTP 传输，此示例通过 'Authorization' HTTP Header 获取认证 Token。客户端在发起MCP请求时需要通过客户端库的配置或API提供此Header。
其他可能的连接信息 (HTTP): 客户端可能需要额外的 URL 配置，通常是 'http://<addr>' (例如 'http://localhost:8080')，因为此示例未将MCP端点绑定到特定路径。

基本使用方法

启动服务器: 根据选择的示例和传输协议，使用上面构建的可执行文件和对应的参数启动服务器。例如：

# 启动 01 示例的 stdio 服务器
cd 01-example-basic-gin
./01-example-basic-gin --transport stdio

# 启动 02 示例的 http 服务器
cd 02-example-basic-token-passthrough
./02-example-basic-token-passthrough --transport http --addr :8080

使用MCP客户端连接: 使用任何支持MCP协议的客户端连接到运行中的服务器。客户端需要使用上面提到的服务器配置信息来建立连接。
调用工具: 通过MCP客户端向服务器发起工具调用请求。
- 例如，对于 '01-example-basic-gin' 服务器，您可以调用 'echo_message' 工具，并传递一个 'message' 参数；或者调用 'add_numbers' 工具，传递 'num1' 和 'num2' 参数。
- 对于 '02-example-basic-token-passthrough' 服务器，您可以调用 'show_auth_token' 工具来查看服务器获取到的Token，或者调用 'make_authenticated_request' 工具（需要提供 'message' 参数），它将使用认证Token发起一个HTTP请求并返回结果。

客户端将接收到服务器返回的工具执行结果。

关键词