mcp-ess-proposal
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-ess-proposal Generate a solar proposal for a residential customer in Selangor with 600 kWh monthly usage"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-proposalMCP 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_leadgenerate_ess_proposal_from_billhello
配置
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 teststests/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 testspython -m unittest discover -s testsdistribution 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(样例数据值)只用于验证,不是官方电价或商业报价,不能作为定价决策依据。
治理
当前治理产物:
MCP Tool Contracts(Core v0.2)
当前 Harness recovery artifacts(Harness 恢复产物):
Available Tools
1 toolgenerate_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
Scored across 1 tool
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.
The single tool name follows a clean snake_case verb_noun pattern: generate_ess_proposal. There are no other names to introduce inconsistency.
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.
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
Related MCP Connectors
Deterministic cost calculators for HVAC, roofing, plumbing, electrical, solar, water heater.
Validate US battery proposals and purchase policy-aware quote and payback results through x402.
Paid Solar PV Design Calculations API via x402. Unpaid tool calls return 402.
Deterministic what-if & scenario simulation for AI agents: projections, sensitivity & break-even.
Related MCP Servers
- AlicenseAqualityDmaintenanceAI-powered BESS quoting & energy sales intelligence for Claude and any MCP client69 npmMIT

security-orchestraofficial
FlicenseNot gradedqualityCmaintenanceProvides 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.-- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- AlicenseNot gradedqualityBmaintenanceEnables 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 PyPIApache 2.0