carboncalc

carboncalc

carboncalc 是一个连接托管版 GreenCalculus MCP 服务的小型本地桥接程序。该服务提供经过溯源的温室气体排放因子语料库，以及基于这些因子构建的确定性计算器。你可以通过标准键查询因子，获取的不只是数值，还有完整的审计信息——发布者、精确的来源引用、检索时间、适用许可，以及各气体分项的总和是否相符；如果你还不知道标准键，也可以通过自然语言描述搜索并解析因子。

该语料库还提供一系列计算器：根据活动数据计算排放量、计算材料的全生命周期隐含碳、计算你提供的投资组合的 PCAF 融资排放量、按两种方法计算 Scope 2 电力排放、按 GLEC 框架计算货运排放、基于支出的 EEIO 初步筛查，以及按距离计算商务旅行排放。另有一个配套工具，用于说明某项因子为何不在语料库中——可能是没有任何发布者发布过、尚未收录、已被拒绝，或缺口与另一个空缺类别相关联。

该桥接程序本身不保存任何因子数据。它会在本地提供上游服务的工具列表，内容与从实时端点捕获的内容完全一致，并将每次工具调用转发至上游，原样返回结果。计算使用调用方提供的输入；工具集中不包含发送或付款工具。

工具

• lookup_factor — 通过标准键查询一个排放因子，并返回完整的审计信息。 必需：key。
• search_factors — 按自由文本、类别或键前缀查找因子。可选：query、 section、key_prefix、limit。
• lookup_factors — 在一次调用中按键查询多个因子，并分别返回审计信息。 必需：keys。
• calculate_activity — 排放量 = 活动量 × 因子，并转换单位以匹配因子的基准单位。 必需：activity、factor_key。
• calculate_embodied — 按 EN 15978 计算材料的全生命周期隐含碳。 必需：materials。
• calculate_pcaf — 计算投资组合的 PCAF Part A 融资排放量。必需：holdings。可选： asset_class。
• calculate_electricity — 根据 GHG Protocol 计算外购电力的 Scope 2 排放，采用基于位置的方法；若提供市场因子或供应商因子，也采用基于市场的方法。 必需：consumption、 location_factor_key。
• calculate_freight — 计算货运和物流排放（GLEC）；应提供 mass 还是 teu，由因子的分母决定。 必需：distance、factor_key。
• calculate_spend — 基于支出的 Scope 3（EEIO）初步筛查：排放量 = 支出 × 强度因子。 必需：spend、factor_key。
• calculate_business_travel — 按距离法计算商务旅行排放。必需：distance、factor_key。可选：passengers。
• resolve_factor — 根据自然语言描述查找最匹配的因子键；描述中应包含国家。必需：description。
• explain_absence — 查询某项因子为何不在语料库中。可选：country、family、 classification。

配置

• GREENCALCULUS_MCP_URL（可选）— 覆盖上游端点。默认为 https://mcp.greencalculus.com。（此覆盖接口是本次重建中自行标注的还原内容。）
• GREENCALCULUS_API_KEY（可选）— 设置后，每个上游请求都会携带 Authorization: Bearer <key> 请求头，使用调用方自己的 GreenCalculus 密钥。未设置时，不会发送密钥请求头。（请求头名称依据原始项目的注册记录确定；Bearer 方案和此环境变量转发方式均为标注的还原内容——原始工具集是在未提供密钥的情况下捕获的。）

转发机制

首次调用工具时，客户端会与上游建立可流式传输的 HTTP 会话：先发送 JSON-RPC initialize 请求（协议版本 2025-03-26， clientInfo 名称为 carboncalc），然后发送 notifications/initialized 通知，最后发送携带调用方参数 且不作更改的 tools/call 请求。上游通过 initialize 响应中的 Mcp-Session-Id 标头返回会话 ID 后，该值会随 该会话的每个后续请求一起发送；此会话会在进程的整个生命周期内复用。响应可能是 普通 JSON，也可能是服务器发送的事件；两种格式都会读取。

成功的上游结果会原样传递， 包括上游设置的任何 isError 标记。 失败情况——JSON-RPC 错误、非 2xx 状态码、 无法读取的响应，或无法完成的请求——会以 isError 结果返回， 其文本以 carboncalc error: 开头（这是本次重建自行添加的标注）。

命令行

每个工具也可作为子命令使用，并接收一个 JSON 参数字符串：

npx @reneturcios/carboncalc lookup_factor '{"key":"grid.gbr.electricity.location_based"}'
npx @reneturcios/carboncalc calculate_freight '{"distance":{"value":500,"unit":"km"},"factor_key":"freight.road_hgv.tonne_km","mass":{"value":10,"unit":"tonne"}}'
npx @reneturcios/carboncalc --version

退出码：成功时为 0，结果为 isError 时为 1， 用法错误时为 2。

MCP 服务

npx -y @reneturcios/carboncalc mcp

MCP 客户端配置：

{
  "mcpServers": {
    "carboncalc": {
      "command": "npx",
      "args": ["-y", "@reneturcios/carboncalc", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/carboncalc
docker run --rm ghcr.io/cloudcorprecords/carboncalc --version

容器的默认命令为 mcp，因此第一种形式会启动 stdio MCP 服务； 其他任何参数都会照常传递给命令行。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全使用存根 JSON-RPC 上游运行，不会发起实时网络调用。

许可证

MIT — 参见 LICENSE。