MCP 电动汽车助手服务器

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

目录

• 特性
• 安装
• 配置
• 使用方法
• API 参考
• 资源管理
• 错误处理
• 开发
• 贡献指南
• 许可证

特性

1. 电动汽车充电站服务

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

2. 行程规划

• 路线规划: 规划适合电动汽车的行驶路线
• 充电站停靠点整合: 自动包含必要的充电停靠点
• 范围考虑: 考虑车辆续航里程和当前电量水平

3. 资源管理

• PDF 文档管理: 处理 /Data 目录中的 PDF 文件
• 资源订阅系统: 支持资源的订阅与取消订阅

4. 错误处理

• 全面错误日志记录: 记录详细的错误信息
• 多级 fallback 机制: 在 PDF 处理中提供多种备用方法
• 输入验证: 使用 Pydantic 模式进行数据校验
• 优雅的资源缺失处理

安装

克隆仓库

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

安装依赖项

pip install -r requirements.txt

启动服务器

python main.py

配置

环境变量

设置以下环境变量以配置服务器行为：

• EV_ASSISTANT_API_KEY: API 访问密钥
• EV_ASSISTANT_DATA_PATH: PDF 资源目录路径

示例配置文件

# config.py
API_KEY = "your_api_key_here"
DATA_DIRECTORY = "/path/to/data/files"

使用方法

添加新工具

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

示例代码片段

# tools_example.py
def new_tool_function():
    # 处理逻辑
    pass

# 在 handle_list_tools 中注册工具
TOOLS.append(new_tool_function)

API 参考

充电站搜索接口

async def search_charging_stations(location: str, radius: int = 50):
    """
    根据位置和半径查找附近的充电站。
    
    参数:
        location (str): 搜索位置
        radius (int, 可选): 搜索半径，单位为公里，默认为 50 公里
        
    返回:
        list: 包含充电站详细信息的列表
    """
    pass

资源订阅 API

async def subscribe_resource(resource_uri: str):
    """
    订阅指定的资源。
    
    参数:
        resource_uri (str): 要订阅的资源 URI
        
    返回:
        bool: 表示订阅是否成功的布尔值
    """
    pass

async def unsubscribe_resource(resource_uri: str):
    """
    取消订阅指定的资源。
    
    参数:
        resource_uri (str): 要取消订阅的资源 URI
        
    返回:
        bool: 表示取消订阅是否成功的布尔值
    """
    pass

资源管理

PDF 资源处理

• 自动发现 /Data 目录中的 PDF 文件
• 支持多种文本提取方法
• 处理资源更新和版本控制

示例订阅操作

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

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

错误处理

常见错误代码

• 401 Unauthorized: 未授权访问
• 503 Service Unavailable: 服务不可用
• 429 Too Many Requests: 请求过多

日志示例

INFO: Server started on port 8000
DEBUG: Successfully parsed configuration file
ERROR: Failed to connect to database: connection refused

开发

创建新功能模块

1. 在 core 目录下创建新的 Python 文件
2. 实现所需的功能逻辑
3. 更新 __init__.py 以包含新模块
4. 测试新功能并修复发现的错误

示例测试代码

def test_new_feature():
    assert new_function() == expected_output

贡献指南

1. ** fork 仓库**
2. ** 创建功能分支** (git checkout -b feature/AmazingFeature)
3. ** 提交更改** (git commit -m '添加某个 Amazing 功能')
4. ** 推送到分支** (git push origin feature/AmazingFeature)
5. ** 提交 Pull Request**

许可证

本项目在 MIT 许可证下发布，详情请参阅 LICENSE 文件。