Skip to main content
Glama
AlanHuang168

mcp-ess-proposal

by AlanHuang168
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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: pvwatts-mcp

快速开始

前置要求：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.

ParametersJSON Schema
NameRequiredDescriptionDefault
locationYesCustomer location label. Core v0 treats it as metadata unless tariff data supports location-specific logic.
budget_myrNoOptional budget cap in MYR.
monthly_kwhNoMonthly electricity consumption in kWh. At least one of monthly_bill_myr or monthly_kwh is required.
need_backupNoWhether backup power is requested.
customer_typeYesCustomer segment used to select calculation assumptions.
monthly_bill_myrNoMonthly electricity bill amount in MYR. At least one of monthly_bill_myr or monthly_kwh is required.
tariff_myr_per_kwhNoOptional user-supplied average electricity tariff in MYR per kWh. When provided it is used for this calculation and overrides bundled default tariff data. Ownership of the tariff dataset and default tariff remains with the server fixtures.
special_requirementsNoOptional free-form requirements. Core v0 may only use deterministic keyword checks documented in implementation.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It adds two meaningful traits: 'deterministic calculation' (reproducible output, no randomness) and 'preliminary' (output is an early estimate, not a final commitment). It does not discuss side effects, but as a generation tool the absence of mutating language is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence communicates the tool's purpose, inputs, and method without any filler. The core action is front-loaded, and every word serves a purpose. This is an appropriately concise definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich input schema (all 8 parameters documented, required fields, anyOf constraint) and the presence of an output schema, the description adds the essential purpose and behavioral context. No needed information for correct invocation is missing, and there are no sibling tools causing routing ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description only groups parameters at a high level ('customer and consumption inputs') without adding syntax, constraints, or meaning beyond what the schema already provides. It neither harms nor significantly enriches parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Generate') and a clear resource ('preliminary solar and energy-storage proposal'), and further specifies inputs ('structured customer and consumption inputs') and method ('deterministic calculation'). It leaves no ambiguity about what the tool does, even without sibling tools to differentiate against.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when this tool is appropriate: generating a preliminary proposal from structured inputs. While it does not explicitly state when not to use it or name alternatives, there are no sibling tools, so exclusions are unnecessary and the implied usage is straightforward.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev0.2.0
    • First observedgenerate_ess_proposal
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0
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

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • pvwatts-mcp

    cwoodcox
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables solar energy potential assessment by converting parcel centroid and acreage into annual/monthly generation estimates using the NREL PVWatts v8 API, suitable for revenue modeling and infographic headlines.
    -

  • datacenter-mcp-server

    log-wade
    A
    license
    A
    quality
    B
    maintenance
    Provides professional-grade data center engineering calculations including cooling, power, GPU thermal optimization, UPS/battery sizing, tier classification, and commissioning workflows, compliant with ASHRAE and Uptime Institute standards.
    8
    21
    1
    MIT
  • security-orchestra by RobotFleet-HQ

    security-orchestraofficial

    RobotFleet-HQ
    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.
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/AlanHuang168/mcp-ess-proposal'

If you have feedback or need assistance with the MCP directory API, please join our Discord server