Site-Calc Investment MCP Server

关键词

投资优化能源管理本地化AI服务数据文件与资源管理LLM 集成

使用说明（Markdown 格式）

  • 项目简介

    • 该仓库实现了一个用于 MCP（Model Context Protocol）的投资规划后端服务器。服务器通过 FastMCP 将投资场景的资源、工具和提示模板暴露给 LLM 客户端，并通过 JSON-RPC 进行请求/响应通信。核心功能包括：场景（Scenario）管理、设备（Device）配置、Timespan 设置、投资参数、任务提交与结果查询，以及将数据文件保存为可供 LLM 使用的本地 CSV/JSON 形式。
    • 服务器端还实现了一个内存中的场景存储（ScenarioStore），以及对外部投资 API 的客户端封装（InvestmentClient），用于提交优化作业并检索结果。

  • 主要功能点

    • MCP 服务与工具注册：提供 16 个 MCP 工具（如 get_version、create_scenario、add_device、set_timespan、submit_scenario 等），并将它们注册到 MCP 服务端，客户端可通过 MCP 调用。
    • 资源与数据处理：支持通过数据加载器解析价格/需求等资源的快捷形式（直接数值、数组、CSV/JSON 文件引用），并提供 save_data_file 将数据写入本地 CSV 以供后续引用。
    • 场景与设备管理：在内存中维护 Draft 场景，支持添加/移除设备、设置时间范围、设置投资参数、审阅场景、列出场景、提交优化作业、查询/取消作业等。
    • 投资分析集成：通过 InvestmentClient 与 Site-Calc API 交互，提交长期优化任务并获取结果（包括 NPV、IRR、Payback 等投资指标）。
    • 结果对比与报告：分析/对比不同场景的投资结果，能够生成用于 DataFrame 或表格展示的对比数据，并支持按需渲染月度/全面的设备结果 summaries。
    • 本地化部署支持：配置通过环境变量指定 API 地址、密钥及数据目录，适合本地开发与离线工作流。
    • Claude Desktop 集成示例：README 中给出 MCP 服务器的集成说明，包含 Claude Desktop 的配置示例，以及通过 MCP 调用工具的流程。

  • 安装步骤

    • 直接安装 MCP 依赖与客户端：
      • pip install site-calc-investment[mcp]
    • 运行 MCP 服务器前，请确保已经具备以下环境变量（在生产环境中由运维/部署流程提供）：
      • INVESTMENT_API_URL：Site-Calc 投资 API 的基地址
      • INVESTMENT_API_KEY：带有 inv_ 前缀的 API Key
      • INVESTMENT_DATA_DIR：本地数据保存目录（可选，未设时使用工作目录）

  • 服务器配置（MCP 客户端配置，不是运行命令） 说明：MCP 客户端需要的只是指向 MCP 服务器的启动命令与参数；以下为用于 Claude Desktop 等工具的典型配置格式（JSON），描述服务器名称、启动命令及参数注释，实际客户端无需直接执行该配置。请将以下配置用于 MCP 客户端对接时的文档化参考： { "server_name": "site-calc-investment", "command": "uvx", "args": ["--from", "site-calc-investment[mcp]", "site-calc-investment-mcp"], "env": { "INVESTMENT_API_URL": "http://your-api-url", "INVESTMENT_API_KEY": "inv_your_key_here", "INVESTMENT_DATA_DIR": "/path/to/data/directory" } // 说明： // - command 和 args 构成启动 MCP 服务的命令与参数。部署时应替换为实际可运行的命令。 // - INVESTMENT_API_URL、INVESTMENT_API_KEY 为与 Site-Calc 投资 API 的认证信息。 // - INVESTMENT_DATA_DIR 指定本地数据保存目录，供 save_data_file 等工具写入使用。 }

  • 基本使用方法

    • 启动与连接
      • 在具备 Python 环境和依赖的机器上运行 MCP 服务器（细节见项目文档和 mcp/server 配置）。
      • 使用兼容的 MCP 客户端（如 Claude Desktop、FAST MCP 客户端等）连接到该 MCP 服务器，按照工具列表逐个调用。
    • 操作流程示例
      • 创建一个草稿场景并设置时间范围
      • 向草稿场景添加设备（Battery、GridImport、GridExport 等）及其属性
      • 设置投资参数（如折现率、CAPEX/OPEX、项目寿命等）
      • 提交优化任务并轮询获取结果
      • 使用 save_data_file 保存价格等数组，随后在 add_device 中引用本地文件
    • 注意事项
      • 本 MCP 服务器通过内存存储管理草稿场景，重启后数据会丢失，适合测试与开发环境。生产环境应考虑持久化存储方案。
      • 与外部 API 的交互需要有效的 API Key，且时间跨度与分辨率需符合投资客户端的限制。

  • 额外信息与兼容性

    • 代码实现了 MCP 协议核心能力：工具注册、请求处理、响应构造、结果汇总，以及与投资 API 的整合。
    • 提供对 Claude Desktop 的集成支持示例，便于将 LLM 与优化工作流对接。
    • 适合搭建本地化的 LLM 辅助投资优化工作流，尤其在需要本地资源访问、数据文件写入以及多场景对比时表现良好。

  • 说明

    • 该实现包含完整的服务器端逻辑、工具注册、数据加载、情景存储、投资 API 连接、结果组织和数据导出等模块，属于可运行且具备完整 MCP 服务能力的实现。

服务器信息

访问项目