MCP EV Assistant Server

MCP EV 助手服务

用于管理电动汽车（EV）充电站、行程规划和资源管理的强大服务实现。此服务为 EV 相关服务提供了全面的工具和 API。

目录

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

功能

1. EV 充电站服务

• 充电站定位器：根据位置和偏好查找附近的 EV 充电站
• 插头类型筛选：搜索特定类型的充电插头（CCS、CHAdeMO、Type 2 等）
• 按距离搜索：指定搜索半径以查找充电站

2. 行程规划

• 路线规划：规划适合 EV 的地点间路线
• 充电站点整合：自动纳入所需的充电站点
• 续航里程考量：考虑车辆续航里程和当前电量

3. 资源管理

• PDF 文档管理：处理 EV 相关 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  # On Linux/Mac
# or
.venv\\Scripts\\activate  # On 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 resources directory
├── agentTools/           # Tool implementations
│   ├── charge_station_locator.py
│   └── ev_trip_planner.py
└── core/                 # Core functionality
    ├── schemas.py
    └── logger.py

用法

启动服务

# Method 1: Direct Python execution
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

   • 用途：查找位置附近的 EV 充电站
   • 参数：
     • address：要搜索的周边位置（字符串，必填）
     • max_distance：搜索半径，单位为千米（整数，必填）
     • socket_type：充电插头类型（字符串，必填）

2. ev_trip_planner

   • 用途：规划适合 EV 的路线
   • 参数：
     • user_address：起始位置（字符串，必填）
     • user_destination_address：目的地位置（字符串，必填）
     • socket_type：首选充电插头类型（字符串，必填）

提示词

1. find-charging-stations

   • 必填：
     • location：搜索位置
   • 可选：
     • radius：搜索半径，单位为 km
     • socket_type：充电插头类型

2. charging-time-estimate

   • 必填：
     • vehicle_model：EV 品牌和型号
     • current_charge：当前电池电量百分比
     • target_charge：目标电池电量百分比
     • charger_power：充电站功率，单位为 kW

3. route-planner

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

资源管理

PDF 资源处理

• 自动发现 /Data 目录中的 PDF 文件
• 支持通过多种备用方法提取文本
• 处理资源订阅更新

订阅系统

# Subscribe to a resource
await client.subscribe_resource("file:///pdf/ev_manual")

# Unsubscribe from a resource
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 文件。