使用说明

项目简介

本项目 'mcp-workshop' 提供了一系列基于 Model Context Protocol (MCP) 的服务器示例，旨在帮助开发者理解和实践 MCP 服务器的构建。仓库包含三个示例 MCP 服务器：

Today Server: 提供当前日期和时间信息。
Download Server: 下载并提取网页内容，转换为 Markdown 格式。
Online Search Server: 使用 Google Programmable Search API 进行在线搜索。

同时，项目也包含了使用这些 MCP 服务器的客户端示例，展示了如何在 LLM 应用中集成和调用 MCP 服务。

主要功能点

资源 (Resources) 访问: 通过工具访问外部数据，例如网页内容和在线搜索结果。
工具 (Tools) 注册与执行: 每个服务器都注册了可供 LLM 客户端调用的工具函数，例如 'today', 'download_webpage', 'google_search'。
标准 MCP 协议: 服务器基于 'mcp.server.fastmcp' 框架构建，遵循 MCP 协议规范，能够与任何兼容 MCP 协议的客户端进行通信。
多种传输协议支持: 示例服务器默认使用 Stdio 传输协议，易于启动和调试。
可扩展性: 项目结构清晰，易于扩展和添加新的 MCP 服务器和工具。

安装步骤

安装 Python 和 Poetry: 确保你的系统已安装 Python (建议 Python 3.8+) 和 Poetry。 Poetry 是一个 Python 依赖管理和打包工具。

克隆仓库: 将 'mcp-workshop' 仓库克隆到本地。

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

安装依赖: 使用 Poetry 安装项目依赖。
```
poetry install
```
如果 Poetry 未安装，请先安装 Poetry: https://python-poetry.org/docs/#installation
配置 Google Search API (可选): 如果你想运行 'online_search' 服务器，需要在 '.env' 文件中配置 Google Programmable Search API 的密钥和引擎 ID。
- 前往 Google Cloud Console 创建项目并启用 "Custom Search API"。
- 创建 API 密钥和搜索引擎 ID，并将它们添加到项目根目录下的 '.env' 文件中，例如：
```
GOOGLE_API_KEY=YOUR_GOOGLE_API_KEY
GOOGLE_ENGINE_ID=YOUR_GOOGLE_ENGINE_ID
```
  注意: '.env' 文件默认未提交到仓库，你需要手动创建。

服务器配置 (MCP 客户端配置)

MCP 客户端需要配置 MCP 服务器的启动命令和参数才能连接和使用服务器提供的工具。以下是针对不同示例服务器的配置信息，客户端需要根据这些信息配置 'MCPServerStdio' 或其他类型的 MCP 服务器连接。

1. Today Server 配置

{
  "server_name": "Today Server",
  "command": "mcp",
  "args": ["run", "src/servers/today/main.py"],
  "env": {"PYTHONPATH": "${PROJECT_ROOT}/src:${PROJECT_ROOT}"}
  // server_name:  服务器名称，客户端用于标识和管理服务器连接
  // command:      启动服务器的命令，这里使用 'mcp run' 运行 Python 脚本
  // args:         命令参数，指定要运行的 Python 脚本路径
  // env:          环境变量配置，PYTHONPATH 确保 Python 能够找到项目代码
  //              ${PROJECT_ROOT} 需要替换为客户端应用的项目根目录的绝对路径
}

2. Download Server 配置

{
  "server_name": "Download Server",
  "command": "mcp",
  "args": ["run", "src/servers/download/main.py"],
  "env": {"PYTHONPATH": "${PROJECT_ROOT}/src:${PROJECT_ROOT}"}
  // 配置项含义同上
}

3. Online Search Server 配置

{
  "server_name": "Online Search Server",
  "command": "mcp",
  "args": ["run", "src/servers/online_search/main.py"],
  "env": {"PYTHONPATH": "${PROJECT_ROOT}/src:${PROJECT_ROOT}"}
  // 配置项含义同上
}

在 MCP 客户端中，你需要根据你使用的客户端库 (如 'pydantic-ai') 的文档，将上述 JSON 配置信息转换为客户端能够识别的 MCP 服务器连接配置。例如，'pydantic-ai' 客户端使用 'MCPServerStdio' 类，你需要将 JSON 配置信息传递给 'MCPServerStdio' 的构造函数。

基本使用方法

启动 MCP 服务器: 在不同的终端窗口中，使用 Poetry 环境分别启动你需要的 MCP 服务器。例如，启动 'today' 服务器：

poetry run mcp run src/servers/today/main.py

启动 'download' 服务器：

poetry run mcp run src/servers/download/main.py

启动 'online_search' 服务器：

poetry run mcp run src/servers/online_search/main.py

注意: 确保在每个服务器的终端窗口中，当前目录是 'mcp-workshop' 项目根目录，或者配置了正确的 'PYTHONPATH' 环境变量。

运行 MCP 客户端: 运行 'src/clients' 目录下的客户端示例，例如 'pydantic_ai' 客户端：
```
poetry run python src/clients/pydantic_ai/main.py
```
或者 'slack' 客户端 (需要配置 Slack App Token 和 Bot Token 环境变量)：
```
poetry run python src/clients/slack/main.py
```
客户端会自动连接到配置的 MCP 服务器，并使用服务器提供的工具来响应用户请求。

通过以上步骤，你可以体验和学习如何使用和构建 MCP 服务器，以及如何在 LLM 应用中集成 MCP 服务以增强其功能。

关键词