carbonstop-agent-mcp

MCP (Model Context Protocol) server for Carbonstop Agent internal skill APIs.

This package is for server-side Agent scenarios. It wraps Carbonstop Java internal Agent APIs and forwards the Agent session identity to the gateway.

CBAM monitoring plan v1.1 provides 18 tools registered by default, including one trusted-host-only material-task tool, with no separate MCP feature flag. Runtime must exclude the host-only tool from model tool bindings and reject direct model calls; see the monitoring integration contract for enforcement requirements, backend prerequisites, materials callbacks, and recovery behavior.

Install

This Agent package is published as @carbonstopper/agent-mcp; the existing @carbonstopper/mcp package remains the Carbon Cloud open-platform-key version.

npm install -g @carbonstopper/agent-mcp

Or run directly:

# stdio mode
npx @carbonstopper/agent-mcp --stdio

# Streamable HTTP mode
npx @carbonstopper/agent-mcp --http --port 3000

The default transport is stdio. For deployed Agent services, start Streamable HTTP mode:

npx @carbonstopper/agent-mcp --http --port 3000 --path /mcp

After global install:

# stdio mode
carbonstop-agent-mcp --stdio

# Streamable HTTP mode
carbonstop-agent-mcp --http --port 3000

Quick Start

1. Configure the Agent internal key:

export CARBONSTOP_AGENT_INTERNAL_KEY="your-agent-internal-key"

2. Start the MCP server:

npx @carbonstopper/agent-mcp

The npm release includes the default gateway base URL injected during the release build. For local debugging or environment override, set:

export CARBONSTOP_AGENT_BASE_URL="https://your-gateway-host"

CARBONSTOP_BASE_URL is also accepted as a compatibility fallback.

Backend requests use CARBONSTOP_TIMEOUT seconds, defaulting to 60. enterprise_report_generate, enterprise_report_regenerate, and enterprise_report_file_record_retry always use at least 120 seconds, and a larger CARBONSTOP_TIMEOUT value also applies to them. CBAM Excel report generation instead has one 120-second end-to-end MCP budget: the asynchronous task-start request uses an exact 20-second timeout, followed by at most 100 seconds of internal status polling, with every status request capped by the remaining total budget. CBAM Word document publication is one synchronous request with an exact 120-second timeout and no polling. Report/document write requests are never automatically retried, so timeout, network, HTTP 429, or HTTP 5xx failures cannot start the same operation twice. Configure the Agent MCP client, reverse proxy, and gateway timeouts above 120 seconds.

Streamable HTTP

Use Streamable HTTP when a LangChain/LangGraph Agent should call the MCP server by URL instead of spawning a local npx process.

export CARBONSTOP_AGENT_INTERNAL_KEY="your-agent-internal-key"
export CARBONSTOP_AGENT_BASE_URL="https://your-gateway-host"
export CARBONSTOP_MCP_TRANSPORT="http"
export CARBONSTOP_MCP_HTTP_HOST="0.0.0.0"
export CARBONSTOP_MCP_HTTP_PORT="3000"
export CARBONSTOP_MCP_HTTP_PATH="/mcp"
export CARBONSTOP_MCP_HTTP_TOKEN="optional-mcp-access-token"

npx @carbonstopper/agent-mcp

LangChain MCP configuration:

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "carbonstop-agent": {
        "transport": "streamable_http",
        "url": "https://your-domain.com/mcp",
        "headers": {
            "Authorization": "Bearer optional-mcp-access-token"
        }
    }
})

If CARBONSTOP_MCP_HTTP_TOKEN is not set, the MCP HTTP endpoint does not require a token. Prefer private networking or a token for deployed services.

Logging

The server writes structured JSON logs to stderr so stdio MCP protocol output is not polluted.

export CARBONSTOP_LOG_LEVEL="info"
export CARBONSTOP_LOG_BODY="false"

Log levels:

• debug: include backend request attempts and argument summaries.
• info: include tool calls, backend responses, and HTTP MCP requests.
• warn: include retries, non-2xx backend responses, unauthorized requests, and not-found requests.
• error: include local exceptions and failed backend requests.
• silent: disable logs.

Default settings are CARBONSTOP_LOG_LEVEL=info and CARBONSTOP_LOG_BODY=false.

Logged events include:

• tool_call_start, tool_call_success, tool_call_partial_success, tool_call_batch_failed, tool_call_validation_error, tool_call_backend_error, tool_call_error
• backend_request, backend_response, backend_retry, backend_error
• mcp_http_request, mcp_http_not_found, mcp_http_unauthorized, mcp_http_error

By default, request bodies are summarized rather than printed. Logs include ids such as sessionId, messageId, traceId, taskId, selected ids like accountId and reportId, inputKeys, text lengths, backend status, and duration. CARBONSTOP_AGENT_INTERNAL_KEY, authorization headers, and MCP tokens are never logged.

For temporary debugging, set CARBONSTOP_LOG_BODY=true. Text previews are still truncated to avoid large or sensitive logs.

Error Responses

When a backend skill returns a business failure, the MCP server returns a JSON error payload to the Agent instead of prefixing the backend body with plain text. Structured validation details are preserved for automatic repair:

{
  "success": false,
  "statusCode": 200,
  "message": "stage 字段不接受当前取值，请使用生命周期阶段代码值",
  "error": {
    "errorCode": "ENUM_NOT_SUPPORTED",
    "fieldPath": "emissionSources[0].stage",
    "retryable": true,
    "suggestedFix": {
      "fieldPath": "emissionSources[0].stage",
      "value": "0"
    }
  },
  "failedItems": []
}

For batch add/update failures, read failedItems[] first. For single write failures, read error.fieldPath, error.supportedValues, error.supportedLabels, and error.suggestedFix.

MCP-local cross-field validation failures are never sent to the backend. They return isError=true with the same JSON object in text content and structuredContent:

{
  "code": "FACTOR_MODE_CONFLICT",
  "path": "orgList[0].sourceList[0].factorId",
  "message": "factorId cannot be combined with fdType=2; omit fdType or use fdType=1 for a library factor",
  "executionState": "not_dispatched"
}

Ordinary missing-field and field-type errors are rejected by the MCP SDK as JSON-RPC -32602 invalid-argument errors. Enterprise emission factor-mode rules are also published in tools/list.inputSchema using Draft-07 allOf, not, if, and then, so schema-aware clients can reject an invalid call before dispatch.

See docs/schema-audit.md for the 70-tool contract inventory, compatibility matrix, and remaining review items.

MCP Client Config

Claude Code / Claude Desktop

{
  "mcpServers": {
    "carbonstop-agent": {
      "command": "npx",
      "args": ["@carbonstopper/agent-mcp"],
      "env": {
        "CARBONSTOP_AGENT_INTERNAL_KEY": "your-agent-internal-key"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "carbonstop-agent": {
      "command": "npx",
      "args": ["@carbonstopper/agent-mcp"],
      "env": {
        "CARBONSTOP_AGENT_INTERNAL_KEY": "your-agent-internal-key"
      }
    }
  }
}

For local debugging against a non-default gateway, add:

"CARBONSTOP_AGENT_BASE_URL": "http://localhost:8080"

Authentication

• The MCP server does not use Carbon Cloud open platform API keys.
• Each tool call must include sessionId; the Agent should pass the session id received from the server-side Agent invocation.
• The MCP server forwards:
  • X-Agent-Internal-Key: ${CARBONSTOP_AGENT_INTERNAL_KEY}
  • X-Agent-Session-Id: ${sessionId}
• The same sessionId is kept in the JSON body for audit, idempotency, trace, and business context.

Available Tools

Only Agent-facing project collaboration, memory, product carbon, enterprise carbon, CBAM, factor search, and unit dictionary tools are exposed in this release.

| Tool | Description | | --- | --- | | session_carbon_objects | Recover product-carbon accounts, enterprise-carbon computations, and CBAM reports bound to the current session. module is optional and supports footprint3, enterprise, and cbam. One session may contain multiple cbamReports[]; always select and pass the exact reportId. | | cbam_reference_search | Query accessible organizations/factories and CBAM country, currency, enum, category, default-value, and report-scoped tax-candidate data. | | cbam_report_search | Search visible CBAM reports by name, organization, factory, year, and pagination. | | cbam_report_read | Unified report read with view=snapshot/section/item/result/readiness/carbon_tax_status; routes to six read-only Java endpoints. | | cbam_factory_read | Read one complete CBAM factory form before a full update. | | cbam_factory_save | Create or fully update a shared factory with action=create/update. Requires existing Agent approval and wrapper-injected confirmed=true; never automatically retried. | | cbam_report_save | Create or fully update report general information with action=create/update. Every create adds another report to the same session instead of replacing an earlier report. | | cbam_process_manage | Save, delete, or reorder self-produced process definitions with action=save/delete/reorder. | | cbam_precursor_manage | Save or delete manually entered purchased precursors. | | cbam_source_flow_manage | Save or delete process source-flow rows; backend recalculates direct emissions. | | cbam_heat_power_update | Update heat-power input data; backend owns calculated output fields. | | cbam_product_data_update | Update process or precursor activity/emission data using dataType=process/precursor. | | cbam_sale_product_manage | Save or delete sale products while protecting backend-calculated emissions and tax fields. | | cbam_carbon_tax_manage | Save/delete tax rows or start the asynchronous full CBAM result calculation (process totals, sale-product allocation, then taxes) with action=save/delete/calculate. | | cbam_data_quality_update | Update the complete report data-quality form. | | cbam_report_generate | After existing Agent approval, start backend CBAM file generation with wrapper-injected confirmed=true, wait internally for completion, and return the Carbon Cloud download record. The status route is not exposed to the Agent. | | cbam_document_read | Read a stable authoritative snapshot for the CBAM operator-emissions or monitoring-plan Word document. Use manifest, then package, and call chunk only for tokens returned by a non-empty chunk plan. | | cbam_document_publish | After existing Agent approval, permanently publish a generated DOCX artifact and register it in Carbon Cloud download management. The wrapper injects artifact/approval/idempotency fields; publication is synchronous and has no model-facing polling tool. | | user_memory_recall | Recall the current user's cross-session preferences, constraints, domain habits, and format habits. Requires sessionId, current messageId, and query; supports optional memoryTypes and limit. Current instructions and business data always take precedence. | | user_memory_get | Read one memory and its latest version before an exact update or forget action. Requires sessionId, messageId, and memoryId. | | user_memory_upsert | Create or version-update one stable user memory after an explicit remember request or confirmation. Requires scope, type, memoryKey, and content; an exact update requires memoryId, while expectedVersion is recommended but may be omitted or set to 0. | | user_memory_forget | Forget one exact memory after explicit confirmation. Requires the latest memoryId, expectedVersion, and confirmed=true; bulk forgetting is not supported. | | project_memory_recall | Recall only the current collaboration project's shared decisions, accounting rules, data-source principles, and delivery conventions. The project is derived from sessionId; personal memory is never included. | | project_memory_get | Read one shared project memory and its latest version. The caller must be an active member of the project session. | | project_memory_upsert | Create or update one confirmed shared project memory. The request has no project or scope selector; MCP sends PROJECT and the backend derives the trusted project from the session. | | project_memory_forget | Forget one exact shared project memory after explicit confirmation. Only the project owner may complete this action. | | project_overview | Read a bounded live overview selected by project type: product settings/calculations/tasks or enterprise settings/emission sources/current-member-related collection tasks, plus recent shared sessions. It is never a complete enterprise task list. | | project_member_list | List active project members using only sessionId. Returns safe member display fields and marks members that may be selected as enterprise collection-task assignees. | | project_task_search | Discover product collaboration tasks or enterprise tasks through one project-scoped entry. Product filters use todo/doing/done, mineOnly, and overdueOnly; enterprise views are fill (我填报的), approve (我审批的), and Owner/Admin-only all (项目全部范围), with optional taskType and pending_fill/pending_approval/rejected/completed filters. Omitting view defaults to fill, not all; all remains paginated. | | project_task_read | Read one trusted task. Product tasks return source/replies/logs; enterprise tasks return taskType, source/submissions/reviewer and rejection fields/logs. Results identify the variant with businessType and taskKind. | | project_session_search | Search shared sessions in the current project before reading another member's conversation. | | project_session_read | Read visible user/assistant turns from one trusted project session; hidden prompts, raw tool payloads, and reasoning are excluded. | | project_calculation_search | Discover project calculations by calculation name, product name, or functional unit. A no-match response contains recent safe candidates for semantic selection. | | project_calculation_read | Read one calculation's project-safe summary and emission aggregates by projectCalculationId, never by product-carbon accountId. | | project_emission_source_read | Read one project's emission-source activity data, factor summary, emissions, and transport segments using trusted project relation and emission-source IDs. | | project_enterprise_source_search | Discover enterprise-carbon emission sources in the current project's server-locked accounting year. Supports trusted computation/category/scope filters, emission-source-name keyword, pagination, and per-type taskAvailabilities. The keyword does not search organization, computation, or category names. | | project_enterprise_source_read | Read one exact enterprise-carbon emission source and its taskAvailabilities by a trusted emissionSourceId; project, company, and accounting year come from sessionId. | | project_enterprise_task_create | Create 1-50 confirmed enterprise emission-source activity-data collection tasks transactionally. The backend fixes taskType=activity_data_collection; MCP exposes no task-type input and never automatically retries the write. | | modeling_re_modeling | Re-run product carbon AI modeling for an existing account. Requires accountId and idempotencyKey. | | modeling_detail | Get product carbon model details. | | modeling_account_detail | Get structured account/model detail before editing. Requires accountId. | | modeling_account_update_structured | Update carbon account/model master information such as account name, product name, specification, functional unit, period, lifecycle scope, or account-level remark. Requires accountId and idempotencyKey. | | modeling_emission_detail | Get one emission source detail before a precise update. Requires accountId and emissionId. | | modeling_emission_add_structured | Add one new emission source to an existing carbon account. Requires accountId, idempotencyKey, and emissionSource. | | modeling_emission_batch_add_structured | Add multiple new emission sources to an existing carbon account in one transaction. Requires accountId, idempotencyKey, and emissionSources. | | modeling_emission_update_structured | Update one emission source under a carbon account, including source amount, unit, factor, transport, lifecycle stage, type, or source remark. Requires accountId, emissionId, and idempotencyKey. | | modeling_emission_batch_update_structured | Update multiple emission sources under the same carbon account in one transaction. Requires accountId, idempotencyKey, and emissionUpdates. | | modeling_emission_delete_structured | Delete one emission source under a carbon account after the Agent has identified the exact emissionId. Requires accountId, emissionId, and idempotencyKey. | | modeling_execute_structured | Create a new product carbon model from structured product, emission source, transport, and factor data. Requires idempotencyKey, productName, unitName, and emissionSources. | | factor_search | Search CCDB factors for standalone lookup, comparison, selection, or modeling. Uses PRODUCT priority by default, accepts explicit ENTERPRISE, and supports one keyword per call. | | unit_list | Get the Agent unit dictionary for structured modeling. | | report_generate | Generate a product carbon report. Requires accountId and idempotencyKey. | | report_regenerate | Regenerate an existing product carbon report. Requires reportId and idempotencyKey. | | report_detail | Get product carbon report detail and latest report URL. | | company_org_subject_query | List existing enterprise carbon organization subjects. | | company_org_subject_batch_add | Batch create or match organization subjects. Optional orgList[].superiorsShares defaults to 100. Requires idempotencyKey. | | company_org_subject_batch_update | Batch rename organization subjects or update superiorsShares. Every item requires orgId and orgName; omit superiorsShares to preserve it. Requires idempotencyKey. | | enterprise_computation_exists | Check whether enterprise carbon accounting exists for a target year. | | enterprise_computation_create_or_update | Create or initialize yearly enterprise carbon accounting. When a new subject is created, optional orgList[].superiorsShares defaults to 100. Requires year, orgList, and idempotencyKey. | | enterprise_computation_batch_add | Add subjects to an existing yearly enterprise carbon accounting. When a new subject is created, optional orgList[].superiorsShares defaults to 100. Requires year, orgList, and idempotencyKey. | | enterprise_computation_batch_delete | Delete subject-year computations by computationIdList. Requires idempotencyKey. | | enterprise_computation_update_base_info | Update enterprise accounting base settings such as GWP or period type. Requires year and idempotencyKey. | | enterprise_computation_detail | Get full enterprise accounting detail as compact columns + rows tables, including exact computationId and sourceId values. | | enterprise_computation_period_list | Get authoritative quarterly/monthly period names, values, and statuses before adding emission sources. Requires year. | | enterprise_emission_category_list | Get authoritative GHG/ISO category trees and their second-level mapping before creating or updating emission sources. | | enterprise_report_org_tree | Get reportable enterprise organization tree nodes for a year. | | enterprise_report_generate | Generate one or more enterprise carbon Word/Excel report versions. Requires versionTypeList, calculatePeriod, orgId, and idempotencyKey; waits at least 120 seconds for the backend and does not automatically retry failures. | | enterprise_report_regenerate | Regenerate the complete enterprise report output through the report generation backend. Use only for an explicit whole-report regeneration request and use a new idempotencyKey. | | enterprise_report_file_record_retry | Retry one failed enterprise report file record by reportFileRecordId; this is not whole-report regeneration. Requires idempotencyKey; waits at least 120 seconds and does not automatically retry failures. | | enterprise_emission_batch_save | Pure-insert enterprise emission sources. Do not pass sourceId. Every source requires a request-unique clientSourceKey. Requires year, orgList, and idempotencyKey. | | enterprise_emission_batch_update | Batch update existing enterprise emission sources. Requires exact sourceId from detail. Do not send emissionQuantity; the backend recalculates it. | | enterprise_emission_batch_delete | Batch delete enterprise emission sources by sourceIdList. Requires idempotencyKey. |

Temporarily hidden tools:

| Tool | Reason | | --- | --- | | modeling_execute | Hidden so Agent prefers the structured modeling API for new model creation. | | modeling_update | Hidden so Agent uses structured account/emission update tools and batch add/update tools instead of broad natural-language updates. | | workspace_authorize_file | Sandbox workspace file APIs are kept internal until the Agent file flow is enabled. | | workspace_file_download_url | Sandbox workspace file APIs are kept internal until the Agent file flow is enabled. | | workspace_upload_artifact | Sandbox workspace file APIs are kept internal until the Agent file flow is enabled. |

User Memory Workflow

Long-term memory is guidance for Agent behavior, not a business-data store. The current user request, current page/session context, and current carbon-accounting data always override stored memory.

1. Use user_memory_recall when a prior stable preference or constraint is relevant. Before a direct upsert or forget, recall the target topic once unless the same topic was already recalled in the current turn. A successful count=0 response is not an error.
2. Use user_memory_upsert only for an explicit "remember this" request or a clearly confirmed lasting preference. Do not store one-off task details, changing business facts, identifiers, emission values, credentials, or sensitive personal information.
3. If recall finds the same independently updatable memory slot, reuse its memoryKey. For an exact update, also reuse its memoryId, call user_memory_get, and preferably pass the latest version as expectedVersion. If no matching slot exists, omit memoryId and expectedVersion. For compatibility, expectedVersion may be omitted or set to 0, in which case the backend reads and conditionally updates the latest version.
4. A memoryKey identifies an independently updatable stable slot. Never include mutable attitudes or states such as like/dislike or enabled/disabled.
5. For a single-valued attribute, use one fixed key without the changing value: "favorite color is yellow" and "favorite color is now blue" both use preference.favorite_color; Chinese and English response preferences both use format.response.language.
6. For a multi-valued collection, include the canonical lowercase English object so entries can coexist: white uses preference.color.white and red uses preference.color.red; both liking and disliking white reuse preference.color.white. Different wording or languages for the same object must reuse the same key.
7. Use user_memory_forget only for one memory explicitly selected by the user. If the exact memory is unknown, recall first; when multiple items match, ask the user to select one. Read its latest version with user_memory_get, then pass confirmed=true; never enumerate or loop to simulate "forget everything".

USER memories apply across the user's sessions. USER_PROJECT memories apply only to the project bound to the current session; the Agent must not submit companyId, userId, or projectId. MCP forwards only whitelisted fields and supplies X-Agent-Internal-Key internally.

Memory write and forget requests are not automatically retried. A version conflict requires a fresh user_memory_get; the Agent must not blindly repeat the stale request. Tool logs contain identifiers, versions, types, content lengths, and result metadata, but never memory content. Memory detail responses are reduced to Agent-safe fields and omit database ids and source session/message ids.

Project-scoped sessions must use the project_memory_* tools. They never fall back to user_memory_*: recall is restricted to the current project's shared memory, all upserts are forced to PROJECT, and forgetting is owner-only. Confirmed project accounting boundaries, factor/data-source rules, quality requirements, stable terminology, and delivery conventions are suitable project memories; member-specific preferences, private data, transient task status, and changing calculation values are not.

Project Runtime Workflow

The project_* tools are available only in project-scoped sessions. The backend derives the trusted project and current membership from sessionId. Read-tool schemas intentionally contain no projectId, companyId, userId, accountId, or idempotencyKey. The enterprise collection-task write also omits all tenant/project selectors, but requires idempotencyKey and confirmed=true.

1. Use project_overview for a compact status summary, not as a complete resource index. Its enterprise tasks are current-member-related and bounded; an Owner/Admin must use project_task_search with view=all and follow pagination for a complete project task list.
2. If a task is not already identified by trusted source_context, call project_task_search, then project_task_read. Use product filters (todo/doing/done, mineOnly, overdueOnly) only in product-carbon projects. In enterprise-carbon projects, use view=fill for 我填报的, view=approve for 我审批的, or view=all for the complete project task list; all is Owner/Admin-only, and omitting view still means fill. Use enterprise task statuses only with enterprise views. Use project_calculation_search only for product-carbon project calculations.
3. Natural-language matching is lightweight. When fallback=true, no string match was found and the returned items are discovery candidates. Compare their names and summaries; if several fit, ask the user to choose instead of selecting the first item.
4. Search pages default to 10 and are capped at 20. pageNum, limit, and turnLimit accept either numbers or numeric strings and are normalized before dispatch. Blank search keywords are treated as omitted. Session-search keywords are capped at 100 characters and search session titles and conversation text.
5. All returned project resource data is read-only context. A projectCalculationId is a project relation id, not an accountId, and must never be passed to existing write tools.
6. For project_task_read, obtain projectTaskId from source_context.target.taskId, project_overview.tasks[].projectTaskId (or legacy taskId), or project_task_search.tasks[].projectTaskId. projectTaskId is canonical; taskId remains only as a compatibility alias.
7. When a task source has objectType=emission_source, use projectCalculationId and objectId from that same project_task_read.source object with project_emission_source_read before deciding whether activity data, factor data, or transport data is missing. Never combine IDs from different task sources. This remains read-only and cannot authorize an existing modeling write tool.
8. In an enterprise-carbon project, use project_enterprise_source_search to find sources in the project's server-locked accounting year, then use project_enterprise_source_read when exact source details must be verified. Its keyword searches only the emission source name; use computationId, categoryId, or scopeCode to narrow other dimensions. Include a source in activity-data task creation only when taskAvailabilities.activity_data_collection.available=true.
9. Before enterprise collection-task creation, call project_member_list. Use only members[].memberId with assignableForEnterpriseTask=true as items[].assigneeMemberId; this is not a userId or companyId. If names are identical or ambiguous, ask the user to choose and never select the first result automatically.
10. Use project_enterprise_task_create only for a project manager after the user confirms the exact source, assignee, deadline, and optional task text. Map emissionSources[].emissionSourceId to items[].sourceId; do not submit project, company, year, source type, or source session fields.
11. Task creation is an all-or-nothing batch of at most 50 items. Use a fresh idempotency key for each confirmed batch and reuse it only for a manual retry of that identical batch; MCP automatic retries are disabled.

Public MCP argument examples:

{
  "sessionId": "agent_project_xxx",
  "keyword": "purchased electricity",
  "scopeCode": "1",
  "pageNum": 1,
  "limit": 10
}

Use the selected result's emissionSourceId to read the source or create a confirmed collection task:

{
  "sessionId": "agent_project_xxx",
  "messageId": "msg_xxx",
  "traceId": "run_xxx",
  "idempotencyKey": "enterprise-collection-20260805-001",
  "confirmed": true,
  "items": [
    {
      "sourceId": "4853195245764096",
      "assigneeMemberId": "4853200000000000",
      "dueTime": "2026-08-31 18:00:00",
      "taskTitle": "Collect August electricity data",
      "taskDescription": "Provide the meter reading and invoice."
    }
  ]
}

Modeling Tool Selection

Use the product carbon modeling tools as follows:

• modeling_re_modeling: re-run the whole model for an existing accountId.
• modeling_account_detail: get the latest structured model detail before an Agent edits existing data.
• modeling_account_update_structured: update only carbon account/model master information, not emission source activity data.
• modeling_emission_detail: inspect one emission source before a precise structured update.
• modeling_emission_add_structured: add exactly one new emission source to an existing account.
• modeling_emission_batch_add_structured: add several new emission sources together; the backend rolls back the whole batch if any item fails.
• modeling_emission_update_structured: update one emission source under a carbon account, including factor or transport list.
• modeling_emission_batch_update_structured: update several existing emission sources together; every item must include emissionId, and the backend rolls back the whole batch if any item fails.
• modeling_emission_delete_structured: delete one emission source only after the Agent has identified the exact target emission source and the user has explicitly asked to remove it.
• modeling_execute_structured: create a new model only after the Agent has extracted structured product data, emission sources, transport legs, and factor selections. Attach routine material or packaging transport to the parent emission source's transport[]; do not create a separate transport source unless the user explicitly asks for a standalone logistics activity.
• unit_list: query available units before modeling_execute_structured, then use returned dictLabel values as unitName.

CBAM Tool Selection

The Java service exposes 35 atomic routes used by MCP, while MCP exposes 17 task-oriented CBAM tools. Dynamic action, view, and dataType values select exactly one Java endpoint per call; MCP removes those routing-only fields before dispatch. Excel generation polling, Word template download, workspace artifact upload, and Word publication status remain hidden implementation capabilities.

1. Start with session_carbon_objects(module="cbam") or cbam_report_search. One session may contain multiple reports. If more than one candidate fits, ask the user which report to use and pass its exact reportId on every later call.
2. Use cbam_reference_search for organizations, factories, countries, currencies, CBAM enum codes, product categories, defaults, and carbon-tax candidates. Never invent an id/code. MCP removes the Java R + AgentCbamSkillResp envelopes, so CARBON_TAX_CANDIDATE is read directly from carbonTaxCandidates. It requires the selected reportId and returns taxTypeOptions, offsetMethodOptions, currencyOptions, report-year inputDefaults, requiredUserInputs, and conditionalRules; apply its defaults and continue without questioning the user when requiredUserInputs is empty. currencyOptions.value is the request dictionary code and currencyOptions.unit is the ISO display unit. Pass saleProductId and emissionValueType after selecting a product to receive valid emission/precursor options. Benchmark record ids and type codes are independent: productBenchmarkType=1 selects bmgStar/BMg*, while 2 selects bmg/BMg.
3. Create a missing factory through cbam_factory_save(action="create"); update only after cbam_factory_read. Factory create/update changes shared data, so the Agent wrapper must complete the existing approval interrupt before making the single MCP call with confirmed=true.
4. Create report general information with cbam_report_save(action="create"). Each call creates and session-binds a new CBAM report. It never overwrites the prior report in that session. General information is sufficient to request report generation; the remaining sections progressively improve completeness.
5. Before changing an existing report or section, use cbam_report_read. Use view=section for complete form data and view=item for one child record. Do not reuse an item id with another report id.
6. Maintain process definitions, precursors, and source flows with their *_manage tools. save accepts create/update batches; delete uses exact ids and requires prior Agent approval plus confirmed=true; process reorder must contain every current process id once.
7. Update heat-power and process/precursor product activity through cbam_heat_power_update and cbam_product_data_update. For a purchased precursor, first read PRECURSOR_PRODUCT_DATA, then copy exact ids from routeOptions, consumerProcessOptions, and defaultCnOptions. Submit complete route-input and report-process-consumption arrays separately and satisfy sum(routeInputs.amount) - sum(processConsumptions.amount) - nonProduct = 0; pass [] when a direction has no rows. Use emissionMode=DEFAULT with defaultCnId + year + defaultReason; the backend calculates and persists the legacy direct/indirect attribution rows. For emissionMode=ACTUAL, electricityFactorSource must use the exact value returned by electricityFactorSourceOptions; never guess or translate the dictionary code. Do not construct isDefault, processList, or productAttributionList in the Agent.
8. Maintain sale products and tax inputs with cbam_sale_product_manage and cbam_carbon_tax_manage. Carbon-tax save uses candidate products, emission sources, and benchmarks; default emissions require the paired emissionSourceDefaultCnId and year. productName may be omitted because the Agent backend derives it from the report-owned saleProductId. New Agent rows share the migrated CBAM form defaults: 2026 adjustment factor 97.5, CSCFy 1, certificate price 0, EUR currency/rate 1, and paid carbon price 0. The backend applies them when optional default fields are omitted. Before updating an existing tax row, read its CARBON_TAX item; omitted default fields preserve stored values. precursorList is tri-state: omit it to preserve stored rows, pass [] only to explicitly clear them, or pass a complete non-empty list to replace them. Omit paidCarbonPrice or pass 0 when no eligible carbon price was paid; in that case omit taxType and offsetMethod. When it is greater than 0, both classifications are required and must use exact candidate option codes. Calculated emissions, benchmark snapshots, versions, fill status, ratios, taxValue, offsetPrice, and payTax are backend-owned and absent from the MCP schemas.
9. cbam_carbon_tax_manage(action="calculate") is the backend's full result-recalculation entry: it recalculates process direct/indirect totals and upstream allocation, writes sale-product emissions, refreshes calculation status, and then recalculates taxes. Use it when sale-product emissions are null or status is NOT_CALCULATED/STALE; do not claim that no recalculation API exists. It is asynchronous and requires prior Agent approval with wrapper-injected confirmed=true. Poll cbam_report_read(view="carbon_tax_status") after the start call. calVersion is a status enum (0 not calculated, 1 running, 2 completed, 3 stale), not a numeric version to compare with updateVersion.
10. Use cbam_report_read(view="readiness") to explain blockers/warnings. canGenerate=true is authoritative permission to generate; complete=false and warnings do not block generation. Basic information alone can still start generation under the migrated CBAM rule. Sale-product unit/unitName are read-only values derived from the linked process/category rather than persisted sale-product inputs; a null legacy projection must not block generation or trigger a request to save those fields.
11. Call cbam_report_generate once after the existing Agent approval. MCP starts backend generation once, polls the internal status route, and normally returns COMPLETED with the final download file. If the 100-second wait expires, the tool returns RUNNING with timedOut=true; call the same tool again with the same idempotencyKey to continue waiting for the same generationId. The backend-generated file is also registered in Carbon Cloud download management.
12. For the operator-emissions or monitoring-plan Word document, call cbam_document_read(view="manifest") first and retain its snapshotId, template.version, coverage states, and final blockers. Then call view="package" exactly once. For Workspace handoff, copy package.manifest unchanged and set the handoff snapshot_id to the exact package.snapshotId; never combine values from different document reads. Call view="chunk" only for tokens in a non-empty chunkPlan, merging each response at the declared JSON path. IDs in the document package are strings.
13. Generate the DOCX from the exact machine template returned by the manifest. In DRAFT, render missing fields as 待补充; never invent facts, turn absence into zero/not-applicable, or substitute factoryCode for the EU installation registry id. In FINAL, resolve every blocker first. Only fields marked supplementable=true may be carried as explicit supplements; authoritative CBAM fields must be changed through their normal tools, and STALE emissions must be recalculated.
14. Upload the generated DOCX with the hidden workspace artifact capability. After the existing approval interrupt is accepted, the trusted wrapper injects artifactId, confirmed=true, and one stable idempotencyKey into cbam_document_publish. Publication is synchronous. Do not poll and do not automatically retry an unknown network outcome; reconcile the download list/business state first.

Every CBAM write requires idempotencyKey. The model-facing wrapper should hide technical approval/idempotency/artifact fields. Factory changes, all deletes, carbon-tax calculation, Excel report generation, and Word document publication must reuse the existing Agent approval interrupt; after approval the wrapper injects confirmed=true and the stable idempotencyKey into one MCP call. Rejection makes no MCP call.

Enterprise Carbon Tool Selection

Use the enterprise carbon tools in this order:

1. company_org_subject_query: list existing organization subjects and match the user's subject name.
2. enterprise_computation_exists: check whether the target year already has enterprise carbon accounting.
3. If the year has no accounting, call enterprise_computation_create_or_update with selected or newly created subjects. For a newly created subject, pass its known ownership percentage as superiorsShares; omit it to default to 100.
4. If the year already exists but the user wants to add a new subject, call company_org_subject_batch_add when needed, then enterprise_computation_batch_add. The same optional superiorsShares rule applies when creating a subject. To rename an existing subject or change its ownership percentage, call company_org_subject_batch_update with its exact orgId and orgName. Pass superiorsShares only when changing it; omission preserves the existing percentage.
5. If the user wants to change GWP or period type, call enterprise_computation_update_base_info.
6. Call enterprise_computation_detail before source maintenance. Use its returned computationId and sourceId; do not guess ids by names.
7. Read timeType from detail before adding sources. For annual accounting (timeType=0), skip the period-list tool and omit computationPeriod or use 1. For quarterly/monthly accounting (timeType=1/2), call enterprise_computation_period_list for the same year, match the user's displayed period to a returned name, and use that item's exact value; never infer it from calendar order.
8. Always call enterprise_emission_category_list before source creation or before changing ghgClassify during an update, then reuse the returned dictionary during that workflow. An activity-data-only update that preserves the existing classification does not need this lookup. Pass only the selected GHG child id as ghgClassify; the backend derives ghgCategory, isoCategory, and isoClassify.
9. Add new sources with enterprise_emission_batch_save. Every orgList[] item requires the exact computationId returned by enterprise_computation_detail. This is pure insert; do not pass orgId, orgName, sourceId, or emissionQuantity. Generate a non-empty clientSourceKey for every source and keep it unique across the entire request. For quarterly/monthly accounting, do not call this tool when the period list is empty, no returned name matches, or the user has not selected a period.
10. Update existing sources with enterprise_emission_batch_update. Every source item must include sourceId; name, facility, ghgClassify, activityData, and activityUnit are partial-update fields whose omitted or blank values preserve stored values. Do not send emissionQuantity, ghgCategory, isoCategory, or isoClassify; the backend recalculates and derives them. Do not pass orgId inside computationList[]. Omit grouping to preserve the existing group, or pass grouping: "" to clear it.
11. Delete sources with enterprise_emission_batch_delete. Use exact sourceIdList from detail and require user confirmation when the action is destructive.
12. For new reports, call enterprise_report_org_tree first, then call enterprise_report_generate with a valid orgId. The backend generates the report正文, inventory, calculations, ratios, charts, and conclusions. The Agent must not draft a parallel report before the call. Keep confirmation content to a short summary of organization, period, standard, language, and requested versions. After success, present the returned fileList as the report result; do not generate another text report unless the user explicitly asks for a separate summary or interpretation.
13. When the user explicitly asks to regenerate the complete report after data, scope, organization, period, language, or version changes, call enterprise_report_regenerate. It uses the same input fields and /agent/report/generate backend as initial generation, but represents a new whole-report action and therefore needs a new idempotency key. The same backend-report and brief-confirmation rules apply.
14. After enterprise_report_generate or enterprise_report_regenerate, inspect its fileList[] when returned. Generation may fail before returning a complete list; in that case obtain the exact failed file records from the report card/runtime result. For each record with status=2, call enterprise_report_file_record_retry separately with its exact reportFileRecordId and a distinct idempotency key. Never invent the id. Do not retry status=1 successful or status=0 generating records, do not pass reportId, and do not use this tool to change report content or regenerate the whole report.

enterprise_computation_detail returns full detail in a compact table format to reduce Agent context size:

• computationColumns defines the field order of every row in computationRows.
• sourceColumns defines the field order of every row in sourceRows.
• gasColumns defines the field order of every row in gasRows.
• Map every row with its returned columns array. Never assume fixed array positions, even when the current order is known.
• Use sourceRows.computationId to join a source to its computation, and gasRows.sourceId to join gas details to a source.
• Read exact computationId and sourceId values from the detail rows before update or deletion. orgSummary is aggregate display data and must not be used in place of detail ids.
• resultFormat=compact_enterprise_computation_table identifies this response. It is full data, not pagination or truncation.

Enterprise unit rules:

• Call unit_list before creating or updating enterprise emission sources.
• Prefer unit_list.factorUnitM[].dictLabel or dictValue as activityUnit and custom factor denominator factorUnitM.
• The backend also recognizes common aliases such as KWh, 度电, 公斤, 公吨, 立方米, t-km, and 人公里, then normalizes them to the unit dictionary. Standard dictionary values remain preferred.
• Use a standard numerator label such as kgCO2e, kgCO2, kgCH4, kgN2O, or kgSF6 as custom-factor factorUnit. A gas-specific numeric unit code is also accepted according to the table below.
• activityData and activityUnit are independently optional. Pass either, both, or neither according to the data actually available; do not invent missing values.
• activityData, custom-factor factorValue, unitConver, and superiorsShares accept either JSON numbers or numeric strings; MCP normalizes numbers to strings before calling Java.
• The backend calculates emissionQuantity only when calculation inputs are sufficient. A missing calculation result is returned as null, not 0; the Agent must not interpret it as zero emissions.
• Pass unitConver only when the user supplied or explicitly confirmed the ratio. Otherwise omit it: the backend first infers deterministic same-dimension conversions and then uses its dictionary conversion fallback.

Custom-factor numerator unit codes are scoped by the gas row's type:

| Gas type | factorUnit code mapping | | --- | --- | | g1 CO2 | 1=kgCO2, 2=tCO2, 3=gCO2 | | g2 CH4 | 1=tCH4, 2=kgCH4, 3=gCH4 | | g3 N2O | 1=tN2O, 2=kgN2O, 3=gN2O | | g4 HFCs | 1=tHFCs, 2=kgHFCs | | g5 PFCs | 1=tPFCs, 2=kgPFCs | | g6 SF6 | 1=tSF6, 2=kgSF6 | | g7 NF3 | 1=tNF3, 2=kgNF3 | | g9 CO2e | 1=kgCO2e, 2=tCO2e, 3=gCO2e |

Enterprise activity data categories accept numbers, numeric strings, or the official Chinese labels:

| Code | Meaning | | --- | --- | | 1 | 自行推估 | | 3 | 定期记录/凭证数据 | | 6 | 自动连续测量 |

Enterprise factor action rules:

• Select a library factor: pass factorId; fdType=1 is optional. Omit gas details and factor snapshot fields. If redundant values are received, MCP removes them before calling Java, so encrypted library-factor values are not treated as custom factor values.
• Create a custom factor: pass a non-empty factorGasList for batch save or gasList for batch update; fdType=2 is optional.
• Automatically match a factor during batch save: omit factorId, fdType, the gas list, and factorName/factorType/factorSource/factorPublic.
• Preserve the existing factor during batch update: omit all factor action and snapshot fields.
• Re-match during batch update: pass only autoMatchFactor=true; do not combine it with any other factor action or snapshot field.

Enterprise batch result rules:

• MCP/HTTP success does not mean every source row succeeded. The backend response is returned unchanged.
• For enterprise_emission_batch_save, always inspect data.successCount, data.failCount, and data.orgList[].sourceList[].
• For enterprise_emission_batch_update, always inspect data.successCount, data.failCount, and data.computationList[].sourceList[].
• Inspect each source result's clientSourceKey, index, sourceId, success, operation, and errorMsg.
• Only report complete success when failCount=0. When correcting failed rows, submit only the corrected failed rows as a new business action with a new idempotencyKey; reuse the original key only when retrying the unchanged original request.

Enterprise report dictionaries:

The code fields below accept numbers or numeric strings. MCP normalizes numeric strings to numbers before calling the Java service.

One user message and one report-generation or whole-report-regeneration action must produce exactly one tool call. Before calling, aggregate every requested standard and output type into one versionTypeList; never split GHG/ISO or Word/Excel into separate calls. Use [2,5] for GHG and ISO full reports, and [2,3,5,6] for both standards with full reports and inventories. Multiple fileList[] items in one response are the expected result, not a reason to call the tool again. MCP normalizes numeric strings and removes duplicate version codes before forwarding the request while preserving first-seen order.

| Field | Code | Meaning | | --- | --- | --- | | versionTypeList[] | 2 | GHG full report, Word | | versionTypeList[] | 3 | GHG inventory, Excel | | versionTypeList[] | 5 | ISO full report, Word | | versionTypeList[] | 6 | ISO inventory, Excel | | languageType | 1 | Chinese, default | | languageType | 2 | English | | timeType | 0 | Annual, default | | timeType | 1 | Quarterly | | timeType | 2 | Monthly |

The report response fileList is passed through unchanged. Each fileList[].path is the backend-provided persistent link and is not converted to a workspace fileId. Summary report versions 1 and 4 are not supported by the current enterprise report backend and are rejected by the MCP schema.

Tool Request Shape

The MCP schema only exposes fields the Agent should fill. Do not pass platform, confirmation, or unrelated id fields unless they are listed for the selected tool.

Write tools accept optional trace fields:

• messageId: current Agent message id, used to associate business records with the current conversation message.
• traceId: Agent run trace id.
• taskId: Agent task or graph node id.
• eventId: Agent event id, mainly used by enterprise carbon trace records.

Enterprise Carbon Examples

Query subjects:

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx"
}

Create yearly accounting:

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx",
  "traceId": "run_xxx",
  "taskId": "enterprise_create_node",
  "year": 2025,
  "timeType": 0,
  "gwp": "2",
  "idempotencyKey": "agent_xxx_enterprise_create_2025_v1",
  "orgList": [
    {
      "orgName": "Beijing Office"
    }
  ]
}

Get detail before source changes:

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx",
  "year": 2025
}

For quarterly or monthly accounting only, resolve the period value before adding sources:

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx",
  "year": 2025,
  "lang": "zh"
}

enterprise_computation_period_list returns items shaped as { "name": "...", "value": 1, "status": 0 }. Match the requested displayed quarter/month against name, then copy that item's exact value to sourceList[].computationPeriod. status is period state metadata, not the period value: 0 filling, 1 completed, 2 not started, 3 waiting for data, 4 waiting for submission, 5 not open.

Get GHG/ISO emission source classifications before source creation or update:

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx",
  "traceId": "run_xxx",
  "taskId": "enterprise_emission_category_node"
}

Use the selected ghgList[].children[].id as ghgClassify. Do not send ghgCategory, isoCategory, or isoClassify; the backend derives them from the selected GHG classification.

Add enterprise emission sources:

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx",
  "year": 2025,
  "idempotencyKey": "agent_xxx_enterprise_source_add_v1",
  "orgList": [
    {
      "computationId": 3001,
      "sourceList": [
        {
          "clientSourceKey": "src_001",
          "name": "Purchased electricity",
          "facility": "Beijing Office",
          "ghgClassify": "Purchased electricity",
          "computationPeriod": 1,
          "activityData": 1000,
          "activityUnit": "kWh",
          "activityCategory": 3,
          "factorId": 9001
        }
      ]
    }
  ]
}

computationPeriod belongs to each sourceList[] item, not to orgList[], and must follow the computation timeType returned by enterprise_computation_detail. For annual accounting (timeType=0), omit it or use 1. For quarterly/monthly accounting (timeType=1/2), first call enterprise_computation_period_list, match the requested display period to an item name, and use its exact value. Never assume that value equals the calendar quarter/month: with a fiscal year starting in April, April can be { "name": "4", "value": 1 } and January can be { "name": "1", "value": 10 }. If the list is empty, no item matches, or the user has not selected a period, do not guess and do not call enterprise_emission_batch_save.

Update enterprise emission sources:

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx",
  "year": 2025,
  "idempotencyKey": "agent_xxx_enterprise_source_update_v1",
  "computationList": [
    {
      "computationId": 3001,
      "sourceList": [
        {
          "sourceId": 5001,
          "name": "Purchased electricity",
          "facility": "Beijing Office",
          "ghgClassify": "Purchased electricity",
          "activityData": "1200",
          "activityUnit": "kWh",
          "activityCategory": "3"
        }
      ]
    }
  ]
}

Delete enterprise emission sources:

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx",
  "year": 2025,
  "idempotencyKey": "agent_xxx_enterprise_source_delete_v1",
  "sourceIdList": [5001]
}

Generate enterprise report:

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx",
  "idempotencyKey": "agent_xxx_enterprise_report_2025_v1",
  "versionTypeList": [2, 5],
  "languageType": 1,
  "timeType": 0,
  "calculatePeriod": "2025",
  "orgId": 1001,
  "reportName": "2025 Enterprise Carbon Report"
}

The example above generates the GHG and ISO full reports in one backend request. Do not send [2] and [5] as two separate MCP calls.

calculatePeriod is always the accounting year, such as "2025". For quarterly or monthly accounting, keep the year-only value and set timeType to 1 or 2. Do not send "1", "Q1", or "2025-Q1"; the current report endpoint does not generate a report scoped to only one quarter or month.

Do not place a generated report正文, emission inventory, calculations, charts, conclusions, or Markdown in reportName or confirmation content. A confirmation should only summarize the organization, accounting period, standard, language, and requested version types. After a successful call, use the backend fileList as the final report output and do not create a duplicate Agent-authored report unless the user separately requests an interpretation or summary.

For an explicit whole-report regeneration, call enterprise_report_regenerate with the same request shape and a new idempotencyKey. It intentionally uses the same /enterprise/agent/report/generate backend as initial generation. Do not use it for a single failed file.

If the report generation response or report card/runtime result contains failed file records (status=2), retry each failed file separately:

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx",
  "traceId": "run_xxx",
  "taskId": "enterprise_report_file_record_retry_node",
  "idempotencyKey": "agent_xxx_enterprise_report_file_2884_retry_v1",
  "confirmed": true,
  "reportFileRecordId": 2884
}

Use only the exact reportFileRecordId returned for the failed file; never infer it from reportId. Do not call enterprise_report_file_record_retry for successful (status=1) or still-generating (status=0) records. Retrying several failed records requires one call and one distinct idempotency key per reportFileRecordId.

modeling_re_modeling

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx",
  "traceId": "langgraph_run_xxx",
  "taskId": "modeling_re_modeling_node",
  "accountId": 2001,
  "idempotencyKey": "agent_xxx_modeling_re_modeling_v1",
  "input": {
    "content": "Updated product description",
    "message": "Recalculate with updated packaging",
    "scope": 1,
    "scopeValue": "0,1,2,3,4",
    "factorScope": 3
  }
}

modeling_detail

{
  "sessionId": "agent_xxx",
  "accountId": 2001
}

modeling_account_detail

Structured alias for modeling_detail. Use this before structured account or emission updates.

The response uses compact column-driven tables. Map each emissionRows[] row with emissionColumns and each transportRows[] row with transportColumns; never assume fixed array positions. Both column lists include factorId. Use the mapped factorId when the Agent needs to preserve or reuse an existing library factor. It can be null for a custom factor or an emission source/transport segment without a matched factor.

{
  "sessionId": "agent_xxx",
  "accountId": 2001
}

modeling_account_update_structured

Use this for carbon account/model master information only. Do not use it for emission source activity data, source factor, source unit, or source transport changes.

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx",
  "traceId": "langgraph_run_xxx",
  "taskId": "account_update_node",
  "accountId": 2001,
  "idempotencyKey": "agent_xxx_account_update_v1",
  "accountName": "1件XS T恤半生命周期",
  "productName": "XS T恤",
  "specification": "XS",
  "amount": "1",
  "unitName": "件",
  "scope": 0,
  "scopeValue": "0,1",
  "startDate": "2026-01-01",
  "endDate": "2026-12-31",
  "remark": "Updated by Agent after user confirmation"
}

Account update field rules:

• accountName: carbon account/model name, for example 1件XS T恤半生命周期.
• productName: product name, for example XS T恤.
• specification: product specification or model, for example XS, 500ml, 80g.
• amount: functional unit amount, not emission source activity amount.
• unitName: functional unit name from unit_list.factorUnitM[].dictLabel, not emission source unit.
• scope: lifecycle boundary code, 0 half lifecycle, 1 full lifecycle, 2 custom lifecycle.
• scopeValue: custom lifecycle stages, comma-separated: 0 raw material acquisition, 1 production, 2 distribution/storage, 3 use, 4 end-of-life.
• startDate / endDate: accounting period, format yyyy-MM-dd.
• remark: account-level update reason or data quality note.

modeling_emission_detail

Use this before changing one emission source.

{
  "sessionId": "agent_xxx",
  "accountId": 2001,
  "emissionId": 4783583185526528
}

modeling_emission_add_structured

Use this when the user wants to add one new emission source to an existing carbon account. The emissionSource object uses the same structure as modeling_execute_structured.emissionSources[].

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx",
  "traceId": "langgraph_run_xxx",
  "taskId": "emission_add_node",
  "accountId": 2001,
  "idempotencyKey": "agent_xxx_emission_add_v1",
  "emissionSource": {
    "name": "Additional recycled polyester",
    "stage": "MATERIAL",
    "type": "4",
    "amount": "12",
    "unitName": "kg",
    "factor": {
      "sourceType": "library",
      "factorId": 1381768211166976,
      "reason": "Best match for recycled polyester"
    },
    "transport": [
      {
        "name": "Supplier to factory road transport",
        "transportType": "1",
        "way": "1",
        "amount": "12",
        "unitName": "kg",
        "distance": "300",
        "distUnitName": "km",
        "factor": {
          "sourceType": "library",
          "factorId": 1584418899325440,
          "reason": "Truck freight factor"
        }
      }
    ],
    "remark": "Added after user provided supplemental material data"
  }
}

modeling_emission_batch_add_structured

Use this when the user wants to add multiple new emission sources to the same existing carbon account. All emission sources are committed in one transaction; if any source fails validation, the backend rolls back the whole batch.

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx",
  "traceId": "langgraph_run_xxx",
  "taskId": "emission_batch_add_node",
  "accountId": 2001,
  "idempotencyKey": "agent_xxx_emission_batch_add_v1",
  "emissionSources": [
    {
      "name": "Additional municipal electricity",
      "stage": "PRODUCT",
      "type": "5",
      "amount": "120",
      "unitName": "kWh",
      "factor": {
        "sourceType": "library",
        "factorId": 123456789,
        "reason": "Grid electricity factor"
      }
    },
    {
      "name": "Additional PE bag",
      "stage": "MATERIAL",
      "type": "3",
      "amount": "3.5",
      "unitName": "kg",
      "factor": {
        "sourceType": "library",
        "factorId": 987654321,
        "reason": "PE packaging factor"
      }
    }
  ]
}

modeling_emission_update_structured

Use this for precise changes to one emission source under a carbon account. Include only fields that should change. Do not use it for account name, product name, functional unit, accounting period, or lifecycle boundary changes.

{
  "sessionId": "agent_xxx",
  "messageId": "msg_xxx",
  "traceId": "langgraph_run_xxx",
  "taskId": "emission_update_node",
  "accountId": 2001,
  "emissionId": 4783583185526528,
  "idempotencyKey": "agent_xxx_emission_update_v1",
  "amount": "0.108",
  "unitName": "kg",
  "rate": "1",
  "factor": {
    "sourceType": "library",
    "factorId": 1381768211166976,
    "name": "Polyester fiber",
    "factor": "2.1",
    "unit": "kgCO2e/kg",
    "institution": "CCDB",
    "year": "2025",
    "reason": "Best match for polyester fiber"
  },
  "transportAction": "replace",
  "transport": [
    {
      "name": "Material supplier to factory road transport",
      "transportType": "1",
      "way": "1",
      "amount": "0.108",
      "unitName": "kg",
      "rate": "0.001",
      "distance": "3000",
      "distUnitName": "km",
      "factor": {
        "sourceType": "library",
        "factorId": 1584418899325440,
        "name": "Truck freight",
        "factor": "0.28948",
        "unit": "kgCO2e/tkm",
        "institution": "CCDB",
        "year": "2025",
        "reason": "Truck freight factor"
      }
    }
  ],
  "remark": "Updated material weight and replaced transport details"
}

transportAction rules:

• keep: keep existing transport. Use this when only non-transport fields change.
• replace: replace all existing transport segments with this request's transport[].
• clear: remove all existing transport segments.

Emission update field rules:

• name: emission source name, for example 再生涤纶面料, 市政电, 环保PE胶袋.
• stage: lifecycle stage, accepts 0/MATERIAL, 1/PRODUCT, 2/DISTRIBUTION, 3/USE, 4/WASTE_DISPOSAL.
• type: emission source type code: 1 main material, 2 auxiliary material, 3 packaging, 4 recycled material, 5 energy, 6 water, 7 standalone transport, 21 waste gas, 22 wastewater, 23 solid waste, 24 renewable waste, 41 other.
• amount: activity data amount for this emission source only.
• unitName: activity data unit from unit_list.factorUnitM[].dictLabel, for example kg, g, t, kWh, m3, 件.
• rate: conversion ratio from activity unit to factor denominator unit, for example g to kg uses 0.001.
• factor: selected factor for normal non-transport sources. In update tools, normal library factors currently must include a full factor snapshot: sourceType, factorId, name, factor, unit, institution, and year. Ecoinvent library factors, or encrypted/masked factor values, must use sourceType: "library" plus factorId only, optionally factorPattern: "2"; do not copy encrypted values, guess values, or send placeholders. Custom factors must include sourceType, name, factor, unit, `