Skip to main content
Glama
mcp-ess-proposal

mcp-ess-proposal

by AlanHuang168

mcp-ess-proposal

mcp-ess-proposal 是一个开源 MCP Server(开源 MCP 服务),用于从结构化输入生成确定性的太阳能与储能初步方案计算结果。

状态

版本(Version): 0.2.0。MCP Tool Contract(MCP 工具契约): Core v0.2。

包版本跟随工具契约版本。首次公开版本使用 0.2.0,而不是 0.1.0,因为 Core v0.2 契约包含严格 Core v0.1 消费者可观察到的变更。

本仓库通过 ai-codeops-harness 治理。Core v0 包含确定性计算核心、中立 fixtures,以及面向已接受 Core v0 工具的 stdio MCP Server Adapter(MCP 服务适配层)。

当前包尚未发布到 package index,也没有创建公开 release tag。

Related MCP server: security-orchestra

快速开始

前置要求:Python 3.11 或更新版本,MCP SDK 2.1 或更新版本。

从源码安装:

python -m pip install -e .

从源码 checkout 运行 MCP 服务:

PYTHONPATH=src python -m mcp_ess_proposal

安装后的等价命令:

mcp-ess-proposal

MCP Client(MCP 客户端)应通过 stdio 连接,并使用结构化输入调用 generate_ess_proposal。示例参数:

{
  "customer_type": "residential",
  "location": "Selangor",
  "monthly_kwh": 600,
  "tariff_myr_per_kwh": 0.60
}

tariff_myr_per_kwh 是可选参数。未提供时,服务会使用内置默认电价数据,并在响应中声明使用的数据来源。

Core 范围

Core v0 包含:

  • MCP Server(MCP 服务)。

  • MCP Tool Contract(MCP 工具契约)。

  • 中立样例数据 fixtures。

  • 基于结构化输入的 Deterministic Calculation(确定性计算)。

Core v0 不包含:

  • Lead(线索)采集。

  • CRM 写入。

  • 私有平台数据库写入。

  • OCR / LLM provider 调用。

  • Prompt(提示词)或 Skill(技能)逻辑。

  • 运行时上传或本地图片处理。

工具契约

已接受的 Core v0 工具契约见 docs/contracts/mcp-tools.md。

Core v0.2 只暴露一个 public tool(公开工具):

  • generate_ess_proposal

调用前需要了解的行为:

  • Consumption precedence(用电量优先级):monthly_kwh 是权威用电量输入,不会被从 monthly_bill_myr 推导出的值覆盖。能只提供一个输入时,建议只提供一个。

  • Consistency validation(一致性校验):如果同时提供 monthly_kwh 和 monthly_bill_myr,且两者偏差超过 10%,工具返回 INCONSISTENT_CONSUMPTION_INPUT,不会静默选择其中一个。错误响应的 details 包含推导电费、解析后的电价和偏差。

  • Tariff source(电价来源):每个成功响应都会返回 tariff_source,取值为 user_provided、default_residential_tiered 或 default_non_residential。

  • Investment scope(投资范围):financial.investment_scope 始终为 pv_only。如果请求备电,系统会给出储能容量建议,但不会计入储能价格,因此 estimated_investment_myr 不是完整系统总投资。

  • Protocol-required normalization(协议要求的规范化):MCP SDK 2.x runtime discovery 的 output schema 会在已接受 oneOf 分支外增加顶层 type: "object"。这是 Contract AMENDMENT-0002 授权的最小协议表示规范化,不改变业务契约语义。

Core v0 排除以下工具:

  • submit_consultation_lead

  • generate_ess_proposal_from_bill

  • hello

配置

Core v0 不需要运行时密钥。

必需环境变量:无。

运行时不会加载 .env 文件,也不会读取 provider、OCR / LLM、CRM 或数据库配置。.env.example 故意不声明任何变量,用于明确零密钥运行契约。

数据

Core v0 数据 fixtures 见 docs/data/fixtures.md。这些值是用于验证的中立样例,不是官方电价或商业报价。

运行路径

  • Host / MCP Client 通过 stdio 启动 mcp_ess_proposal。

  • src/mcp_ess_proposal/server.py 注册 generate_ess_proposal。

  • MCP handler 接收结构化参数并委托给 src/mcp_ess_proposal/calculator.py。

  • calculator.py 使用 models.py 和由 data.py 加载的包内 fixtures。

  • 服务返回符合契约形状的 structured content(结构化内容)。

calculator.py、models.py、data.py 和 fixtures 不依赖 MCP SDK。

开发

Core v0 的 MCP 服务通过 stdio 运行:

PYTHONPATH=src python -m mcp_ess_proposal

服务只注册已接受的 generate_ess_proposal 工具。Remote HTTP(远程 HTTP)、authentication(鉴权)、OCR / LLM、provider 集成和私有适配器均不属于 Core v0。

本地验证:

python -m compileall src tests
PYTHONPATH=src python -m unittest discover -s tests

tests/test_server.py、tests/test_stdio_runtime.py 和 tests/test_stdio_runtime_v0_2.py 需要 mcp SDK;该依赖会随包安装。其余测试不依赖 MCP SDK。

持续集成

.github/workflows/ci.yml 在 Python 3.11 上运行单一 test-only job(仅测试任务)。它执行:

  • python -m compileall src tests

  • python -m unittest discover -s tests

  • distribution build(分发构建)

  • installed-wheel check(已安装 wheel 检查),确认包内 fixtures 存在

该 workflow 只请求 read-only repository permissions(只读仓库权限),不包含 secrets、部署或发布步骤。

许可证

本项目使用 MIT License。见 LICENSE。

支持边界

  • Supported(支持):stdio transport、已接受的 generate_ess_proposal 工具、Python 3.11 或更新版本、MCP SDK 2.1 或更新版本。

  • Not implemented(未实现):储能定价、完整系统总投资、电池 ROI。financial.investment_scope 会明确标记这一点。

  • Not supported(不支持):Remote HTTP(远程 HTTP)transport、authentication(鉴权)、provider / OCR / LLM 集成、CRM 或数据库写入、Lead(线索)采集。这些都在 Core v0 之外,本仓库当前不规划实现。

  • Fixture values(样例数据值)只用于验证,不是官方电价或商业报价,不能作为定价决策依据。

治理

当前治理产物:

当前 Harness recovery artifacts(Harness 恢复产物):

Available Tools

1 tool
generate_ess_proposalA

Generate a preliminary solar and energy-storage proposal from structured customer and consumption inputs using deterministic calculation.

Inputs: location (required), customer_type (required), budget_myr, monthly_kwh, +4 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only one tool is exposed, so there is no possibility of confusing it with another tool. The tool's purpose is clearly stated and unambiguous.

    Naming Consistency5/5

    The single tool name follows a clean snake_case verb_noun pattern: generate_ess_proposal. There are no other names to introduce inconsistency.

    Tool Count3/5

    A single tool makes the server feel thin and leaves no room for composing related proposal operations. The scope is focused, but the tool surface is borderline for an MCP server.

    Completeness4/5

    The server covers the core proposal-generation workflow directly. Minor gaps exist around supporting operations like input validation or scenario comparison, but agents can work around them because the one tool returns a complete result.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Provides deterministic, standards-based calculations for data center critical power infrastructure. Enables site selection, generator sizing, UPS sizing, NFPA 110 compliance, and more via 50+ AI agents and 8 compound chains.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables home solar energy planning by estimating PV output, validating consumption plans against generation and battery constraints, and automatically shifting flexible loads to ensure power availability during scheduled outages.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to size hybrid renewable energy systems by simulating candidate designs hour-by-hour for a full year, filtering out constraint violations, and ranking remaining options by net present cost and related techno-economic metrics.
      20 PyPI
      Apache 2.0