MCP Server AI Bot

🤖 AI助手平台

与Google Gemini LLM集成的模型上下文协议（MCP）服务器，用于智能客户服务协助。该平台提供自然语言聊天功能和人工智能驱动的客户数据分析和总结。

🌟 特性

• 🔧 MCP工具集成：遵循模型上下文协议的标准化工具接口
• 🤖 人工智能聊天：使用Google Gemini 1.5 Flash进行自然语言交互
• 📊 智能分析：人工智能生成的客户洞察和总结
• 🔒 安全API：外部API调用的承载令牌身份验证
• 🌐 专业Web界面：用于客户服务操作的现代用户界面
• 📖 自动生成的文档：FastAPI自动API文档

📁 项目结构

ai-assistant-platform/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI application entry point
│   ├── server.py               # MCP server setup
│   ├── llm_agent.py            # Gemini LLM integration
│   ├── core/
│   │   ├── __init__.py
│   │   └── config.py           # Configuration management
│   ├── tools/
│   │   ├── __init__.py
│   │   └── user_tools.py       # MCP tools implementation
│   └── static/
│       └── index.html          # Web interface
├── .env                        # Environment variables (not in git)
├── .env.example                # Environment template
├── .gitignore                  # Git ignore rules
├── requirements.txt            # Python dependencies
├── LICENSE                     # MIT License
└── README.md                   # This file

🚀 快速开始

先决条件

• Python 3.10或更高版本
• pip包管理器
• Google Gemini API密钥(在这里买一个)
• 外部API凭证（用于客户数据集成）

安装

1. 克隆仓库

   git clone https://github.com/yourusername/ai-assistant-platform.git
   cd ai-assistant-platform

1. 创建并激活虚拟环境

窗户：

   python -m venv venv
   venv\Scripts\activate

Linux/Mac：

   python -m venv venv
   source venv/bin/activate

1. 安装依赖项

   pip install -r requirements.txt

1. 配置环境变量

   # Copy the example file
   cp .env.example .env

   # Edit .env with your actual credentials
   # On Windows: notepad .env
   # On Linux/Mac: nano .env

所需的环境变量：

   API_KEY=your_api_key_here
   API_URL=https://your-api-url.com
   GEMINI_API_KEY=your_gemini_api_key_here

1. 运行服务器

   # Using uvicorn directly
   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

   # OR using Python module
   python -m app.main

1. 访问应用程序

- 🏠 主页/健康检查：http://localhost:8000/ - 📖 API文件：http://localhost:8000/docs - 🌐 Web界面：http://localhost:8000/ui - 🔧 列出工具：http://localhost:8000/tools

📚 API终点

核心终点

MCP工具端点

请求正文：

{
  "file_number": "ABC123"
}

LLM端点

与LLM聊天

POST /llm/chat

自然语言聊天，可选客户上下文。

请求正文：

{
  "message": "What's my current balance?",
  "file_number": "ABC123"  // Optional
}

答复：

{
  "success": true,
  "response": "Based on your account, your current balance is $1,500.00..."
}

AI摘要

POST /llm/summarize

生成基于人工智能的客户账户摘要。

请求正文：

{
  "file_number": "ABC123"
}

答复：

{
  "success": true,
  "summary": "Account Summary for John Doe:\n\nCurrent Balance: $1,500.00..."
}

🔧 配置

所有配置均通过环境变量进行管理 .env 文件：

# API Configuration
API_KEY=your_api_key_here
API_URL=https://api.example.com
API_TIMEOUT=30

# LLM Configuration
GEMINI_API_KEY=your_gemini_key_here

# Server Configuration
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
DEBUG=false

# MCP Configuration
MCP_SERVER_NAME=company-mcp-server
MCP_SERVER_VERSION=1.0.0

🏗️ 建筑

数据流

User Request → FastAPI → LLM Agent → MCP Tools → External API
                           ↓
                    Gemini AI Processing
                           ↓
                    AI-Enhanced Response

组件

1. FastAPI服务器 (main.py)：处理HTTP请求和路由
2. LLM代理 (llm_agent.py)：管理Gemini AI交互
3. MCP服务器 (server.py)：实现模型上下文协议
4. 用户工具 (user_tools.py)：外部API集成
5. 配置 (config.py)：环境管理

💡 使用示例

示例1：获取客户详细信息

import requests

response = requests.post(
    "http://localhost:8000/test/get_user_details",
    json={"file_number": "CUST123"}
)
print(response.json())

示例2：与上下文聊天

import requests

response = requests.post(
    "http://localhost:8000/llm/chat",
    json={
        "message": "What payment options are available?",
        "file_number": "CUST123"
    }
)
print(response.json()["response"])

示例3：获取AI摘要

import requests

response = requests.post(
    "http://localhost:8000/llm/summarize",
    json={"file_number": "CUST123"}
)
print(response.json()["summary"])

🔌 MCP客户端集成

要将此服务器与MCP客户端（如Claude Desktop）一起使用：

{
  "mcpServers": {
    "company-mcp-server": {
      "command": "python",
      "args": [
        "/path/to/mcp-llm-server/app/main.py"
      ],
      "env": {
        "API_KEY": "your_api_key_here",
        "GEMINI_API_KEY": "your_gemini_key_here",
        "API_URL": "https://api.example.com"
      }
    }
  }
}

🧪 测试

使用Web界面

1. 打开http://localhost:8000/ui
2. 输入文件编号（默认值：14226904）
3. 测试不同功能：

- MCP工具测试 - LLM聊天 - AI摘要

使用curl

# Test health check
curl http://localhost:8000/

# Test MCP tool
curl -X POST http://localhost:8000/test/get_user_details \
  -H "Content-Type: application/json" \
  -d '{"file_number": "14226904"}'

# Test LLM chat
curl -X POST http://localhost:8000/llm/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the current balance?", "file_number": "14226904"}'

🛠️ 发展

添加新的MCP工具

1. 在中定义工具 app/tools/user_tools.py:

   async def new_tool(self, param: str) -> Dict[str, Any]:
       """Your tool implementation"""
       pass

1. 注册 app/server.py:

   @mcp_server.list_tools()
   async def list_tools() -> list[Tool]:
       return [
           Tool(name="new_tool", description="...", inputSchema={...})
       ]

1. 在中添加处理程序 app/server.py:

   @mcp_server.call_tool()
   async def call_tool(name: str, arguments: dict):
       if name == "new_tool":
           result = await user_tools.new_tool(arguments["param"])

以开发模式运行

# Enable debug mode in .env
DEBUG=true

# Run with auto-reload
uvicorn app.main:app --reload --log-level debug

📦 依赖项

• 快速API：用于构建API的现代web框架
• 优维康：FastAPI的ASGI服务器
• 谷歌发电机：谷歌Gemini AI SDK
• httpx：用于外部API的异步HTTP客户端
• python dotenv：环境变量管理
• 主控程序：模型上下文协议SDK

看 requirements.txt 查看完整的版本列表。

🔒 安全最佳实践

1. 永不承诺 .env 文件 -已经在 .gitignore
2. 使用环境变量 为了所有的秘密
3. 旋转API键 定期
4. 使用HTTPS 生产中
5. 实施速率限制 用于生产用途
6. 验证所有输入 处理前
7. 记录安全事件 用于监测

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🤝 贡献

欢迎投稿！请看 贡献.md 作为指导方针。

1. 复刻仓库
2. 创建功能分支(git checkout -b feature/AmazingFeature)
3. 提交您的更改(git commit -m 'Add some AmazingFeature')
4. 推到分支(git push origin feature/AmazingFeature)
5. 打开拉取请求

🐛 故障排除

常见问题

问题: Could not import module "main"

• 解决方案：使用 uvicorn app.main:app 而不是 uvicorn main:app

问题：服务器无法访问 http://0.0.0.0:8000

• 解决方案：使用 http://localhost:8000 或 http://127.0.0.1:8000 浏览器中

问题: API_KEY must be set in environment variables

• 解决方案：创建 .env 文件来自 .env.example 并填写您的密钥

问题：Gemini API错误

• 解决方案：验证您的 GEMINI_API_KEY 有效且有足够的配额

📞 支持

对于问题、疑问或贡献：

• 🐛 通过GitHub Issues报告错误
• 💬 通过GitHub讨论
• 📧 电子邮件：your.email@example.com

🙏 致谢

• 快速API 优秀的web框架
• 谷歌双子座 LLM能力
• 模型上下文协议 用于标准化工具接口

______________________________________________________________________

由...制作❤️ 智能债务催收援助