使用说明

MCPBot

一个具有多个Gemini AI客户端接口的模型上下文协议（MCP）服务器，所有接口都用Docker容器化。

概述

MCPBot是一个演示模型上下文协议架构的项目，包括：

MCP服务器：提供掷骰子、计算和天气信息的工具
多个客户端：三种不同的客户端实现（Web UI、终端UI和Basic）
基于Docker：完全容器化，便于部署和开发

特性

MCP服务器工具

摇骰子：在用户确认的情况下掷多个骰子
计算器：执行基本算术运算
天气：使用Open-Meteo API获取多个城市的实时天气信息

客户端实现

web界面 (gemini_client.py)：可通过浏览器访问基于WebSocket的现代聊天界面
终端用户界面 (gemini_client_tui.py)：使用Textual的丰富终端界面
基本客户端 (fastmcp_client.py)：用于测试的简单命令行客户端

建筑

┌─────────────────────┐
│   Gemini AI Model   │
│   (via API)         │
└──────────┬──────────┘
           │
           │ Uses tools via MCP
           │
┌──────────▼──────────┐
│   MCP Server        │
│   (Port 8000)       │
│   - Dice Tools      │
│   - Calc Tools      │
│   - Weather Tools   │
└─────────────────────┘
           ▲
           │ MCP Protocol
           │
┌──────────┴──────────┐
│   Client            │
│   (Port 8080)       │
│   - Web/TUI/CLI     │
└─────────────────────┘

先决条件

Docker和Docker Compose
Make（可选，方便命令）
Gemini API密钥(在这里买一个)

快速开始

克隆存储库
```
git clone <your-repo-url>
cd mcpbot
```

设置环境变量

cp .env.example .env

编辑 .env 并添加您的Gemini API密钥：

GEMINI_API_KEY=your_api_key_here
GEMINI_MODEL=gemini-2.5-flash
LOG_FOLDER_PATH=/usr/src/app/logs
INSTRUCTION_PATH=/usr/src/app/data/system_instruction.txt

构建和启动服务
```
make setup-and-go
```
访问web界面 打开浏览器： http://localhost:8080

用法

使用Make命令

该项目包括一个Makefile，便于操作：

# Build all Docker images
make build

# Start the MCP server
make start-server

# Start the client
make start-client

# View logs
make logs

# Stop services
make stop

# Stop and remove all containers
make down

# Clean up everything (containers + images)
make clean-all

# Build and start everything
make setup-and-go

# Clean all, rebuild and start everything
make rebuild

手动Docker编写命令

# Build images
docker-compose build

# Start server
docker-compose up -d mcpserver

# Start client
docker-compose up -d client

# View logs
docker-compose logs -f

# Stop everything
docker-compose down

客户端接口

Web客户端（默认）

统一资源定位符: http://localhost:8080
特性:
- 实时聊天界面
- WebSocket通信
- 消息历史记录
- 重置对话按钮
- 激励支持（工具确认提示）

终端UI客户端

要改用TUI，请修改 client.Dockerfile 使用：

CMD ["python", "gemini_client_tui.py"]

基本CLI客户端

为了测试，请修改 client.Dockerfile 使用：

CMD ["python", "fastmcp_client.py"]

项目结构

mcpbot/
├── src/
│   └── mcpbot/
│       ├── server/
│       │   ├── server.py          # MCP server main
│       │   ├── tools/
│       │   │   ├── dice_tools.py  # Dice rolling tool
│       │   │   ├── calcul_tools.py # Calculator tool
│       │   │   └── weather_tools.py # Weather API tool
│       │   ├── prompts/           # (Future) MCP prompts
│       │   └── resources/         # (Future) MCP resources
│       └── clients/
│           ├── gemini_client.py   # Web interface client
│           ├── gemini_client_tui.py # Terminal UI client
│           ├── fastmcp_client.py  # Basic CLI client
│           └── static/            # Web UI assets
│               ├── index.html
│               ├── styles.css
│               └── app.js
├── dock/
│   ├── data/
│   │   └── system_instruction.txt # AI system prompt
│   └── logs/                      # Application logs
├── docker-compose.yml
├── server.Dockerfile
├── client.Dockerfile
├── Makefile
├── pyproject.toml
└── .env.example

配置

系统说明

通过编辑自定义AI的行为 dock/data/system_instruction.txt:

You are an exceptionally helpful and friendly chatbot. 
Your purpose is to provide concise and accurate information when rolling dice as requested by the user.
You should only use the available tools to answer these types of questions. 
If a question is outside of your capabilities, politely inform the user that you are unable to help with that request.

环境变量

GEMINI_API_KEY：您的Google Gemini API密钥（必需）
GEMINI_MODEL：要使用的模型（默认值：gemini-2.5-flash）
LOG_FOLDER_PATH：日志文件的路径
INSTRUCTION_PATH：系统指令文件的路径

发展

添加新工具

在中创建新的工具文件 src/mcpbot/server/tools/:

from mcp import types
from pydantic import BaseModel, Field

def register_my_tools(mcp):
    @mcp.tool(
        name="my_tool",
        description="Description of what this tool does"
    )
    def handle_my_tool(arguments: dict) -> list[types.TextContent]:
        # Your tool logic here
        return [types.TextContent(type="text", text="Result")]

在中注册 server.py:

from tools.my_tools import register_my_tools
register_my_tools(mcpbot)

日志

应用程序日志存储在 dock/logs/:

服务器日志： mcpserver_log_YYYY-MM-DD.log
客户端日志： mcpclient_log_YYYY-MM-DD.log

技术栈

MCP协议：用于AI工具集成的模型上下文协议
FastMCP：Python MCP服务器框架
谷歌双子座：AI语言模型
快速API：客户端界面的Web框架
文本的：终端UI框架
码头工人：集装箱化
WebSockets：实时通信

故障排除

客户端无法连接到服务器

确保服务器正在运行： docker-compose ps
检查服务器日志： docker-compose logs mcpserver
验证容器之间的网络连接

API关键问题

验证Gemini API密钥是否设置在 .env
检查密钥是否具有适当的权限
确保 .env 文件位于项目根目录中

端口冲突

默认端口：8000（服务器）、8080（客户端）
更改端口 docker-compose.yml 如有需要

贡献

分叉存储库
创建要素分支
进行更改
彻底测试
提交拉取请求

许可证

待办事项

致谢

内置 FastMCP
由...驱动谷歌双子座
天气数据来自开放天气

联系