MCP EV 助手服务器

一个强大的服务器实现，用于管理电动汽车 (EV) 充电站、行程规划和资源管理。该服务器为电动汽车相关服务提供了一套全面的工具和 API。

目录

• 功能
• 安装
• 配置
• 使用
• API 参考
• 资源管理
• 错误处理
• 开发
• 贡献
• 许可证

功能

1. 电动汽车充电站服务

• 充电站定位器: 根据位置和偏好查找附近的电动汽车充电站
• 插座类型过滤: 搜索特定的充电插座类型（CCS、CHAdeMO、Type 2 等）
• 基于距离的搜索: 指定搜索半径以查找充电站

2. 行程规划

• 路线规划: 规划电动汽车友好的位置间路线
• 充电站集成: 自动包含必要的充电站
• 续航里程考虑: 考虑车辆续航里程和当前电量

3. 资源管理

• PDF 文档管理: 处理电动汽车相关的 PDF 文档（用户指南、手册等）
• 资源订阅: 支持资源订阅以获取实时更新
• 自动文本提取: 具有回退机制的 PDF 文本提取

4. 交互式提示

• 充电站搜索: 用于查找充电站的交互式提示
• 充电时间估算: 根据各种参数计算充电时长
• 路线规划助手: 具有充电考虑的交互式路线规划

安装

1. 克隆仓库

git clone https://github.com/Abiorh001/mcp_ev_assistant_server.git
cd mcp_ev_assistant_server

2. 设置虚拟环境 (推荐)

python -m venv .venv
source .venv/bin/activate  # 在 Linux/Mac 上
# 或
.venv\\Scripts\\activate  # 在 Windows 上

3. 安装依赖

uv sync

配置

1. 环境变量

在项目根目录中创建一个 .env 文件，包含以下变量：

OPENCHARGE_MAP_API_KEY=your_opencharge_map_api_key
GOOGLE_MAP_API_KEY=your_google_map_api_key

2. 服务器配置

创建或更新 servers_config.json:

{
  "mcpServers": {
    "ev_assistant": {
      "command": "/home/$USER/path/mcp_learning/.venv/bin/python",
      "args": ["/home/$USER/path/mcp_ev_assistant_server/ev_assistant_server.py"],
      "env": {
        "OPENCHARGE_MAP_API_KEY": "your_opencharge_map_api_key",
        "GOOGLE_MAP_API_KEY": "your_google_map_api_key"
      }
    }
  }
}

3. 目录结构

mcp_ev_assistant_server/
├── ev_assistant_server.py
├── .env
├── servers_config.json
├── Data/                  # PDF 资源目录
├── agentTools/           # 工具实现
│   ├── charge_station_locator.py
│   └── ev_trip_planner.py
└── core/                 # 核心功能
    ├── schemas.py
    └── logger.py

使用

启动服务器

# 方法 1：直接 Python 执行
python ev_assistant_server.py

API 示例

1. 查找充电站:

result = await client.call_tool("charge_points_locator", {
    "address": "London, UK",
    "max_distance": 10,
    "socket_type": "CCS"
})

2. 规划行程:

result = await client.call_tool("ev_trip_planner", {
    "user_address": "Manchester, UK",
    "user_destination_address": "Liverpool, UK",
    "socket_type": "Type 2"
})

API 参考

工具

1. charge_points_locator

   • 目的: 查找位置附近的电动汽车充电站
   • 参数:
     • address: 要搜索的位置 (字符串, 必需)
     • max_distance: 搜索半径，单位为公里 (整数, 必需)
     • socket_type: 充电插座类型 (字符串, 必需)

2. ev_trip_planner

   • 目的: 规划电动汽车友好的路线
   • 参数:
     • user_address: 起始位置 (字符串, 必需)
     • user_destination_address: 目的地位置 (字符串, 必需)
     • socket_type: 首选充电插座类型 (字符串, 必需)

提示

1. find-charging-stations

   • 必需:
     • location: 搜索位置
   • 可选:
     • radius: 搜索半径，单位为公里
     • socket_type: 充电插座类型

2. charging-time-estimate

   • 必需:
     • vehicle_model: 电动汽车品牌和型号
     • current_charge: 当前电池百分比
     • target_charge: 期望电池百分比
     • charger_power: 充电站功率，单位为千瓦

3. route-planner

   • 必需:
     • start_location: 起始点
     • end_location: 目的地
     • vehicle_range: 车辆满电续航里程
   • 可选:
     • current_charge: 当前电池百分比

资源管理

PDF 资源处理

• 自动发现 /Data 目录中的 PDF 文件
• 支持使用多种回退方法的文本提取
• 处理资源订阅以进行更新

订阅系统

# 订阅资源
await client.subscribe_resource("file:///pdf/ev_manual")

# 取消订阅资源
await client.unsubscribe_resource("file:///pdf/ev_manual")

错误处理

• 全面的错误日志记录
• 用于 PDF 处理的回退机制
• 使用 Pydantic 模式进行输入验证
• 优雅地处理缺失的资源

开发

添加新工具

1. 在 core.schemas 中定义工具模式
2. 在 agentTools 中实现工具函数
3. 将工具添加到 handle_list_tools()
4. 在 handle_call_tool() 中实现工具处理

添加新提示

1. 在 PROMPTS 中定义提示结构
2. 在 handle_get_prompt() 中实现验证
3. 添加必要的模式验证

贡献

1. Fork 仓库
2. 创建您的功能分支 (git checkout -b feature/AmazingFeature)
3. 提交您的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开一个 Pull Request

许可证

本项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。