MCP Ev Assistant Server

🚀 MCP 電動汽車助手服務器

MCP 電動汽車助手服務器是一款功能強大的服務器，可用於管理電動汽車（EV）充電站、規劃行程以及進行資源管理。它提供了全面的工具和 API，為電動汽車相關服務提供有力支持。

🚀 快速開始

克隆倉庫

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)

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