mcp_ev_assistant_server

🚀 MCP 电动汽车助手服务器

MCP 电动汽车助手服务器功能强大，可用于管理电动汽车（EV）充电站、进行行程规划以及资源管理。它提供了全面的工具和 API，助力各类电动汽车相关服务的开展。

🚀 快速开始

你可以按照以下步骤快速启动 MCP 电动汽车助手服务器：

克隆仓库

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

安装依赖项

pip install -r requirements.txt

启动服务器

python main.py

✨ 主要特性

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)

高级用法

资源订阅操作示例

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

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

📚 详细文档

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 文件。
• 支持多种文本提取方法。
• 处理资源更新和版本控制。

错误处理

常见错误代码

• 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 文件。