Brest MCP Server

Brest MCP 服务

一个面向 Brest 地区的稳健型模型上下文协议（MCP）服务实现，为基于 MCP 的交互提供基础设施，并内置调试和监控功能。

目录

• 描述
• 功能
• 前提条件
• 技术
• 安装
• 用法
  • 运行服务
  • 使用客户端
  • AI Agent 集成
• 开发
• 故障排除
• 贡献
• 许可证

描述

Brest MCP Server 是面向 Brest 地区的模型上下文协议（MCP）服务实现。它为管理基于 MCP 的交互提供稳健的基础设施，并包含用于调试和监控的 MCP 检查器。

本项目旨在简化 MCP 服务的部署和管理，并着重确保简单易用和可靠性。

功能

• 🚀 MCP 协议实现：全面符合模型上下文协议标准
• 🔍 内置检查器：通过集成的 Web 界面调试和监控 MCP 服务
• 🤖 AI Agent 集成：支持 A2A 协议和 Agent 间通信
• 🐍 基于 Python：使用 Python 3.12+ 构建，遵循现代开发实践
• 📦 UV 包管理：快速、可靠的依赖管理
• 🔧 开发工具：包含客户端工具和调试实用程序

前提条件

安装 Brest MCP Server 前，请确保具备以下条件：

• Python 3.12.3 或更高版本
• Node.js（用于 MCP Inspector）
• Git（用于克隆代码库）
• uv 包管理器（安装说明见下文）

技术

• 语言：Python 3.12.3 或兼容版本
• 依赖管理：uv
• 检查器：通过 Node.js（npx）运行的 MCP Inspector
• 环境：由 uv 管理的虚拟环境
• 协议：模型上下文协议（MCP）和 A2A（Agent-to-Agent）

安装

要在本地安装并配置 Brest MCP Server，请按以下步骤操作：

1. 安装 uv（如果尚未安装）：

   • 在 Linux/macOS 上：

     curl -LsSf https://astral.sh/uv/install.sh | sh
     

   • 在 Windows 上：

     powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
     

2. 克隆代码库：

   git clone https://github.com/Nijal-AI/Brest-mcp-server.git
   cd Brest-mcp-server
   

3. 创建并激活虚拟环境：

   uv venv
   source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
   

4. 安装依赖：

   uv sync
   

用法

运行服务

要在本地运行服务，请按以下步骤操作：

1. 确保已激活虚拟环境：

   source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
   

2. 通过 MCP Inspector 启动服务：

   npx @modelcontextprotocol/inspector uv run brest-mcp
   

3. 在浏览器中访问 MCP Inspector：

   • 代理：http://localhost:3000
   • Web 界面：http://localhost:5173

输出示例：

Starting MCP inspector...
Proxy server listening on port 3000
🔍 MCP Inspector is up and running at http://localhost:5173 🚀

使用客户端

如果想使用 Brest MCP Server 与 AI Agent 通信，可以使用 tools 目录中提供的客户端：

uv run python tools/client.py src/server.py

AI Agent 集成

你也可以通过 A2A 协议，使用 Brest MCP Server 与 AI Agent 聊天。

1. 设置 Agent：

   echo "MCP_TRANSPORT=stdio" > src/.env
   

2. 运行 Agent：

   uv run agent
   

3. 与 A2A samples 演示配合使用（可选）：

   # 设置
   git clone https://github.com/google-a2a/a2a-samples.git
   echo "GOOGLE_API_KEY=your_api_key_here" > a2a-samples/demo/ui/.env
   
   # 运行
   cd a2a-samples/demo/ui
   uv run main.py
   

   然后访问 http://localhost:12000，进入“Agents”并连接位于 localhost:10030 的 Brest Expert Agent。你也可以添加其他 Agent，然后进入 Home 并创建新对话，与一个或多个 Agent 交流。

开发

如果你是希望参与贡献或开发高级功能的开发者，请按照以下额外步骤操作：

1. 确保已设置虚拟环境并安装依赖项：

   uv venv
   uv sync
   

2. 使用 MCP Inspector 调试和监控服务：

   npx @modelcontextprotocol/inspector uv run brest-mcp
   

3. 参阅 pyproject.toml 文件，了解依赖项和配置的详细信息。

故障排除

常见问题

虚拟环境激活失败

• 确保已正确安装 uv，且它位于 PATH 中
• 尝试重新创建虚拟环境：uv venv --force

MCP Inspector 无法启动

• 确保已安装 Node.js：node --version
• 清除 npm 缓存：npm cache clean --force
• 尝试全局安装 inspector：npm install -g @modelcontextprotocol/inspector

与 A2A samples 的连接错误

• 确认 Google API 密钥已正确设置在 .env 文件中
• 检查 Brest Expert Agent 是否正在 localhost:10030 上运行
• 确保所有必需的端口均可用，且未被防火墙阻止

依赖项安装失败

• 将 uv 更新到最新版本：uv self update
• 清除缓存：uv cache clean
• 尝试以详细输出模式安装：uv sync -v

获取帮助

如果你遇到此处未涵盖的问题：

1. 查看 GitHub 上的 Issues 部分
2. 查阅 MCP 协议文档
3. 创建新 issue，并附上详细的错误消息和环境信息

贡献

欢迎贡献！如需提出更改：

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/your-feature-name
3. 进行更改，并确保测试通过
4. 遵循项目定义的编码规范
5. 提交 pull request，并清楚描述你的更改

详细指南请参阅 CONTRIBUTING.md 文件。

许可证

本项目采用 MIT License。详情请参阅 LICENSE 文件。