Cernion Energy Tools MCP

Cernion Energy Tools

Stadtwerke、DSO、エネルギーサービスチーム向けの、API ファーストなエージェント型エネルギー運用レイヤーです。 Cernion は、決定論的なエネルギー領域サービス、厳選された機能ルーティング、 エビデンス資料、VDMI のロールロジック、HITL の境界、REST、Sidecar、Microsoft Copilot、n8n、OpenWebUI、OpenClaw 向けの 読み取り専用統合インターフェースを組み合わせています。

このリポジトリについて

Cernion Energy Tools は、cernion.de のバックエンドランタイムです。 エネルギー領域の自動化、意思決定支援、エージェント型プロセスオーケストレーションのための Node.js/Moleculer サービスプラットフォームです。

エネルギー API 用のチャットフロントエンドにとどまりません。現在のプラットフォームには次のものが含まれます。

• services/ 内の 138 個の Moleculer サービス
• openapi-export.json 内の 1007 個の OpenAPI パス
• tests/ 以下の 304 個の JavaScript テストファイル
• バックエンドのうち、ガバナンスされたサブセットのみを公開する 厳選された Copilot、Sidecar、OpenWebUI、n8n、OpenClaw の統合インターフェース
• ルーティング、レシート、資料、HITL、エビデンス、再検証、可観測性のための エージェント型ランタイムコンポーネント
• テナント単位の取り込み、構造化テーブル、エビデンスに基づく関係グラフ、ソース選択を可視化するバージョン管理されたルーティングマニフェストを備えた 永続的なプロジェクトファイル。API、来歴、制限、クリーンアップについては Projektakte をご覧ください。

現在のパッケージ／OpenAPI バージョン：0.99.0

公開上の位置付け

Cernion は、チャットに判断を委ねません。目標、利用可能なデータ、サービスチェーン、エビデンス、不足情報、リスク、次に進める安全なゲートを構造化します。その結果はブラックボックスの回答ではなく、Stadtwerke、配電事業者、エネルギーサービスチーム向けの、資料作成にすぐ使えるステータスまたは意思決定準備状況のビューです。

Cernion Energy Tools は、自動的な契約判断、系統接続の確約、デバイス制御システム、MaKo 実行システム、請求／精算システム、料金変更システムではありません。適切な統合範囲は ask、plan、evidence、capability lookup、read-only status です。書き込みを伴う手順や重大な結果につながる手順は draft、prepare、pending confirmation の状態にとどまり、HITL が必要です。

公開ウェブサイトでは、MaStR 分析、系統計画、§14a、Redispatch、Energy Sharing、顧客サービスの自動化、Microsoft Copilot との補完性を扱う、Stadtwerke 向けのエネルギーインテリジェンスおよび意思決定プラットフォームとして Cernion を紹介しています。このリポジトリは、そうした製品の説明を支える、より深い技術システムです。

公開向けの関連リンク

• 製品とトピックのハブ：Cernion Themencluster
• 機能の概要：Cernion Capability Hub
• API とエージェントの統合：MCP Tools & API および REST API
• 運用に関する検索意図別ページ：
  • 配電事業者向けソフトウェア
  • Stadtwerke のプロセス自動化
  • §14a EnWG のエビデンス資料
  • Redispatch 2.0 の移動データ
  • Stadtwerke および系統運用者向け AI

Cernion がエージェント型である理由

Cernion は API ファーストですが、API は統合レイヤーにすぎません。エージェント型であることを示すのは、次のようなランタイムの振る舞いです。

1. エネルギー分野の目標を理解する 例：系統接続のシナリオを検証する、VDMI の責任分担マトリクスを作成する、BESS の財務リスクを評価する、Energy Sharing のデータ競合を特定する。
2. ガバナンスが適用された機能パスを選択する capability-broker は、LLM にツールカタログ全体を公開するのではなく、意図を精選されたサービスチェーンに対応付けます。
3. 決定論的なマイクロサービスを実行する エネルギー分野の計算と規制チェックは、コードに基づいて実行され、再現可能な状態が保たれます。
4. プロセスの状態を維持する パーソナルエージェントのセッション、レシート、ドシエ、HITL 項目、オブジェクトストアのエビデンスにより、1 回のチャットで完結しない作業も継続できます。
5. 監査可能な成果物を生成する 出力は自然言語による回答だけではありません。ドシエ、エビデンスパッケージ、意思決定フレーム、検証レポート、レシート、トレースも含まれます。
6. 再検証をガバナンスする 新しい事実はエージェントの制御シグナルとして機能します。MaStR 資産、データポイント、オブジェクトストアのエビデンス項目が変更された場合、依存する判断を特定して再確認できます。

これが、質問応答ボットとエージェント型のエネルギー運用プラットフォームとの実質的な違いです。

コアアーキテクチャ

External systems / humans / agents
        |
        v
REST API, Copilot API, OpenClaw Sidecar, MCP-like tool surfaces
        |
        v
Personal Agent / Capability Broker / Agent Receipts / Blueprints
        |
        v
Governed Moleculer services
        |
        v
Datapoints, Object Store, Knowledge RAG, Dossiers, Jobs, Observability

ランタイムレイヤー

レイヤー	コンポーネント	目的
サービスバス	Moleculer、REST ゲートウェイ、非同期ジョブ	決定論的なサービス実行と API の公開
データレイヤー	Object Store、Datapoints、DataSources、Knowledge RAG	内部データ、外部エビデンス、テナントのメモリ、ソース資料
エージェント型ルーティング	Personal Agent、Capability Broker、Blueprints、Agent Receipts	意図の解決、ツールチェーンの選択、永続的な実行
ガバナンス	VDMI、HITL、Clarification Policy、Interface Placeholder、Evidence Revalidation	責任、エビデンスの不足、人間による判断、ギャップへの対処
統合	Full OpenAPI、Copilot subset、OpenClaw Sidecar、Webhooks、MCP-style tools	人間、副操縦士、エージェント、自動化システムによる安全な利用
オブザーバビリティ	メトリクス、トレース、監査記録、ジョブのステータス	運用、監査可能性、サポート

主な領域

このプラットフォームは、エネルギー業界の複数の業務領域をカバーしています。以下は代表例であり、正確な情報は OpenAPI エクスポートを参照してください。

領域	例
系統接続と fNAV	系統接続の検証、柔軟なネットワークアクセス、接続拒否のエビデンス
VDMI ガバナンス	プロセスステップごとの Verantwortlich、Durchführend、Mitwirkend、Information、所見、ドシエ、エビデンス
Zielnetzplanung（ZNP）	プロジェクト、前提条件、Layer 0/1/2 の資産、ポートフォリオ分析、NOVA の判断
資産とデータ品質	MaStR の品質、資産の上書き、ゴースト資産のアラート、データソースの分類
Energy Sharing と精算	§42c 形式の割り当て、精算チェック、Redispatch の事後照合
EDM と市場通信	MSCONS のインポート、EDM の検証、仮想メーター、メスコンセプトのチェック
予測と柔軟性	予測エンジン、残余負荷、§14a の柔軟性イベント、SLP プロファイル
財務と投資	Finance Agent、fNAV の経済性、BESS のスクリーニング、設備投資の優先順位付け
レポートと BI	レポートのガバナンス、ダッシュボード API、VNB のモニタリング、EWK のモニタリング
ナレッジとエビデンス	Knowledge RAG、エビデンスのルーティング、ドシエ、オブジェクトストアのコンテキスト

エージェント型コンポーネント

エージェント型サイトマップ／AI カタログ

GET /.well-known/ai-catalog.json および GET /.well-known/ard.json は、読み込まれたサービスレジストリとリアルタイムの OpenAPI メタデータから、リクエストごとに生成される公開カタログを提供します。公開される各 REST サービスには、アクション／機能トークン、代表的なクエリ、インラインの OpenAPI コントラクトを含むエントリーがあります。カタログからは、完全な OpenAPI ドキュメントと llm.txt にもリンクしています。ルートのレスポンスでは、HTTP Link ヘッダーを通じて両方の検出パスを案内し、条件付きリクエストでは ETag をサポートします。

手動での JSON 管理も、LLM 呼び出しも必要ありません。保護されたアクションや非公開アクション、サービス設定、ランタイムデータは除外されます。カタログの公開によって、アクションを呼び出す権限が付与されるわけではありません。デプロイの詳細をご覧ください。

これらの形式はドラフトです：AI Catalog と Agentic Resource Discovery。ARD は現在 ard.json を使用しています。以前のパスを使用するクライアント向けに、リクエストされた ai-catalog.json も引き続き利用できます。オフラインテストでは、両方の形式を固定された上流スキーマに照らして検証します。npm run sync:ai-catalog-schemas を実行すると、同期スクリプトで固定されたリビジョンからフィクスチャーを更新できます（Apache-2.0）。

パーソナルエージェント

services/personal-agent.service.js は、ユーザー向けのオーケストレーション層です。会話状態を保持し、インテントをルーティングし、決定論的なサービスを呼び出して結果を統合します。バックエンド全体を単一のプロンプトにすることはありません。

主な概念：

• 階層化されたコンテキスト管理（「Zwiebelmodus」）
• 永続的な実行状態と再開可能なセッション
• ファイルとデータポイントの取り込み
• エビデンスの不足への対応
• 思考過程を示すイベント
• プレゼンテーションを考慮した最終成果物

ケイパビリティブローカー

services/capability-broker.service.js と src/capability-catalog.js は、厳選されたケイパビリティのルーティングを提供します。エージェントがバックエンド全体を直接参照したり選択したりできないようにする制御点です。

厳選されたケイパビリティの例：

• vdmi_role_boundary_governance
• vdmi_asset_validation_governance
• vdmi_grid_connection_decision_governance
• netzfahrplan_fnav_assessment
• znp_portfolio_assessment
• settlement_a96_reconciliation
• financier_due_diligence_assessment
• reporting_governance

エージェントレシート

services/agent-receipts.service.js は、反復可能なエージェントワークフローを、バージョン管理されたテスト可能なレシピに変換します。レシートには、一致条件、必須の入力、ツール計画、ナレッジ計画が記述されています。「エージェントが回答した」状態から「プラットフォームが、ガバナンスに基づき検査可能なワークフローを選択した」状態へとつなぐものです。

ドシエと意思決定フレーム

Cernion は、監査可能な出力のためにドシエと意思決定フレームを使用します。結果には次の内容を含めることができます。

• 使用した事実
• 仮説
• エビデンスの不足
• リスク
• 禁止される前提
• VDMI の責任
• 次のアクション
• 人によるレビューの要件

エージェント型ガバナンスと再検証

GitHub のイシューには、進行中のアーキテクチャトラックが 2 つ記録されています。

• #275 エージェントガバナンスランタイム：実装計画の前に現状分析
• #276 エージェント型ガバナンスレイヤー：エージェントの制御シグナルとしての事実の変更

目指す方向性は、変更された事実をエージェントの制御シグナルにできるようにすることです。

MaStR / datapoint / object-store change
        |
        v
Dependency and impact analysis
        |
        v
Revalidation queue
        |
        v
Agent receipt / capability flow rerun
        |
        v
Audit note, updated dossier, HITL item or exception case

これにより、Cernion は一度限りの API 分析から、商品エネルギーのプロセス向け RPA+ へと移行します。標準的なケースは自動化され、例外は明確に示されます。

統合インターフェース

完全な REST API

完全な REST API は、Moleculer サービスのメタデータから生成されます。

• Swagger UI：GET /api/docs
• OpenAPI JSON：GET /api/openapi.json
• 静的エクスポート：openapi-export.json
• 開発者および LLM による検出向けの公開 API レシピ：docs/public-api-recipes.md

レシピでは、合成データの例、環境変数を使用したトークン、テナントセーフなデモ用識別子のみを使用します。相談／読み取り専用／確認待ちの境界を説明するものであり、承認、課金、料金表、デバイス制御、契約、本番環境の変更を扱うデモではありません。

再生成と監査：

npm run export:openapi
npm run audit:openapi

Microsoft Copilot ブリッジ

Cernion は、600 以上あるすべての API パスを Microsoft Copilot に公開するわけではありません。Copilot ブリッジでは、config/copilot-operations.json で管理される厳選された許可リストを使用します。

関連ファイル：

• docs/copilot-process-bridge.md
• docs/copilot-agent.json
• docs/copilot-plugin.json
• openapi-copilot.json

Copilot 用のサブセットを生成します：

npm run export:openapi:copilot

Copilot 向けのインターフェースでは、次のように区別します。

• 副作用のない read 操作
• 提案を準備する draft 操作
• 確認が必要な prepare 操作
• 明示的なガバナンスが適用されるまでブロックされる、重大な結果を伴う操作

OpenClaw サイドカー

Cernion Energy Tools は、公開されているClawHub パッケージ @cernion/openclaw-energy-tools-sidecarを通じて OpenClaw から使用できます。次の手順で OpenClaw にインストールします。

openclaw plugins install clawhub:@cernion/openclaw-energy-tools-sidecar

付属のリポジトリ SmartEnergySolutions/cernion-openclaw-sidecar では、汎用 Energy Sidecar プロバイダー向けの OpenClaw プラグインを提供しており、最初のプロバイダーとして Cernion を採用しています。

製品の境界は意図的に分けられています。OpenClaw は、会話、ツールのオーケストレーション、メモリ、回答の合成を担うエージェントランタイムです。Cernion Energy Tools は、MaStR 資産、電力網の状況、Redispatch、Zielnetzplanung、14a/14d EnWG の義務、プロセスの受付、Domain Router のケース状態、Case Event Outbox/MWI、運用状況に関する回答を支える、エネルギー分野のエビデンス、ポリシー、Knowledge RAG、CET が管理するプロセスレイヤーです。

サイドカーは、Cernion Sidecar コントラクトを使用します。

• GET /api/agent-sidecar/descriptor
• GET /api/agent-sidecar/mcp/tools
• POST /api/agent-sidecar/mcp/tools/:name/call
• POST /api/knowledge-rag/query
• POST /api/evidence-router/route
• POST /api/copilot-process/intents
• GET /api/_agent/capabilities[?domain=]
• GET /api/_agent/operations[?domain=]

境界は意図的に厳格に定められています。

• サイドカートークンはテナント、アクター、クライアントのコンテキストを識別します。権限の境界は CET の認可／ガバナンスです。
• Domain Router および MWI ツールは、ケース状態、イベント配信状態、関連セッションリンクなどの内部 CET PouchDB 状態を更新する場合があります。
• エビデンス／ハイドレーションの検索と Blueprint の計画は、実際の操作が読み取り専用である場合、そのまま読み取り専用です。
• プロセスの受付には別のプロセストークンを使用し、作成されるレシートは pending_confirmation のみです。
• 管理者、トークン、HITL の解決、本番環境の変更に関するパスはブロックされます。
• ドメインルーティングはサイドカー内ではなく、Cernion 内にとどまります。

MCP スタイルのツール

Cernion は、llm.txt、機能解決エンドポイント、MCP/OpenClaw スタイルのツールリストを通じて、AI エージェント向けのツール説明も公開しています。公開ドキュメントのページでは、これを Stadtwerke 向けのすぐに使えるエネルギーツールのセットとして紹介しています。

クイックスタート

前提条件：Node.js 22+

git clone https://github.com/energychain/cernion-energy-tools.git
cd cernion-energy-tools
npm install
cp .env.example .env
npm start

ローカルエンドポイントの初期設定：

• API：http://localhost:3000/api
• Swagger UI：http://localhost:3000/api/docs
• Web アプリ：http://localhost:3000/app

セットアップガイド全文：QUICKSTART.md

設定

まず、.env.example を参照してください。一般的な変数は次のとおりです。

変数	用途
CERNION_TOKEN	認証アクセス用の API トークン
LLM_PROVIDER	LLM プロバイダー（gemini、openai-compat、ollama）
LLM_MODEL	選択したプロバイダーのモデル名
LLM_API_KEY / GEMINI_API_KEY	必要に応じて使用するプロバイダー認証情報
API_URL	生成される OpenAPI サーバーおよび CLI 共有リンクで使用するベース URL
PORT	API ゲートウェイのポート。デフォルトは 3000 です
TRACING_ENABLED	OpenTelemetry トレーシングを有効にします
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP HTTP トレースの送信先
METRICS_PUBLIC	フルアクセス用トークンなしで /metrics を公開します

LLM のヘルスチェック：

GET /api/system/llm/health

オブザーバビリティ：

• GET /metrics は Prometheus 互換のメトリクスを返します
• Grafana の例：docs/observability/grafana/README.md

認証ガイド：BEARER_TOKEN_AUTHENTICATION.md

開発

npm test
npm run test:unit:ci
npm run test:tdd-matrix
npm run test:rest-usecases
npm run lint
npm run audit:openapi
npm run check:llm
npm run release:check
npm run release:gate

「リリースゲートの実行」Runbook では、合成マルチターンシナリオ、評価基準、ローカルまたは HTTP テストインスタンスを対象とした反復実行を用いる実践評価について説明しています。release:gate は、この受け入れテストをリポジトリのチェックに追加します。

便利な生成コマンド：

npm run export:openapi
npm run export:openapi:copilot
npm run generate:llm
npm run blueprint:export

新しい Moleculer サービスを作成します：

npm run create

Cernion のデモ

優れたデモでは、単なるチャットの回答ではなく、エージェントによる実行を見せる必要があります。

効果的なデモのパターン：

• VDMI：プロセスの各ステップについて責任分担表を生成し、役割境界の違反を検出する
• BESS：系統接続、リスク、収益の前提、融資者向け証拠にわたってサイトを評価する
• Energy Sharing：プロセスを妨げる MaLo/MeLo、EDM、精算の競合を特定する
• MaStR/Revalidation：外部アセットの更新によって、依存する意思決定の再確認がどのように発生するかを示す
• Copilot/Sidecar：汎用エージェントの背後で、Cernion がガバナンスされたエネルギー領域のバックエンドとして機能する様子を示す

有用なエージェント実行トレースでは、次の点が確認できる必要があります：

User objective
  -> intent and capability
  -> selected receipt / blueprint
  -> service chain
  -> evidence used
  -> gaps and risks
  -> HITL / policy decision
  -> dossier or decision artifact
  -> audit trace

ドキュメント一覧

ドキュメント	トピック
docs/copilot-process-bridge.md	厳選された Microsoft Copilot API サブセット
docs/v0.52-implementation-plans/personal-agent-v052-architecture-tdd.md	Personal Agent のアーキテクチャと TDD 契約
docs/v0.52-implementation-plans/v0.52.1-capability-broker.md	Capability Broker の実装計画
docs/observability/grafana/README.md	Grafana ダッシュボード
docs/DSFA_TEMPLATE.md	データ保護影響評価テンプレート
docs/BACKEND_CONTEXT.md	UI／フロントエンド作業向けのバックエンドコンテキスト
CHANGELOG.md	リリース履歴
MCP_TOOLS.md	MCP／ツールのリファレンス
docs/SHARED_SERVICE_JOURNAL.md	RC3 の追記専用 Shared Service Journal、決定論的ダイジェスト、保持
docs/domain-router.md	CET Domain Router、型付きケース関連付け、own/team/tenant の可視性、Case Event Outbox／MWI
docs/tenant-memory.md	テナントメモリ：主張、共有アンカー、ソース、訂正、単発の通知
docs/open-webui-tenant-gateway.md	RC3 Open WebUI／Cernion Workbench のテナントゲートウェイアクセス（AgentOS 不使用）
llm.txt	機械可読なサービスと機能のコンテキスト
SECURITY.md	セキュリティポリシー

ライセンスと運営者の情報

ライセンス：GPL-3.0。LICENSEを参照してください。

Cernion は、エネルギーインテリジェンスプラットフォーム Cernion の開発の一環として、STROMDAO GmbH が開発しています。

サポートと製品に関するフィードバック：

• GitHub Issues
• [email protected]

ワークベンチ：理解し、回答し、ケースをバックグラウンドで管理

内容に関するメッセージや貼り付けられた外部テキストは、中央の LLM ファサードを通じて状況把握情報に変換されます。CET は関連する情報源を添えて回答し、新たな専門的な確認質問は最大 3 つまで行います。具体的な作業依頼にはバックグラウンドケースが作成され、「ケースなし」を選ぶと取り消されます。知識や状況に関する質問ではケースは作成されません。送信の希望があった場合は案内を表示し、明示的に依頼された場合は内部用の下書きを作成します。情報源の割り当てと関連性のしきい値は src/workbench-knowledge-sources.json で設定します。詳細と制限事項は、テナントゲートウェイガイドおよび#739 の受け入れレポートを参照してください。

組織に関係する発言は CET がテナント全体で記録し、「記録しました：…」と一度だけ確認します。まれに使われる共通の手掛かりによって複数の人の発言が結び付けられ、検出された相互作用は会話中と、もう一方の人が次に連絡した際に一度だけ表示されます。テナントの分離と機密レベルは、アクセスのたびに適用されます。詳細はテナントメモリガイドを参照してください。

テナントデータカタログ

Open WebUI から送信された完全な CSV／XLSX テキストテーブルは、テナント全体でユーザー提供情報として保存され、dataset.query によって決定論的に評価されます。同じ内容であれば、添付ファイルを再送信しても新しいバージョンや確認は生成されません。セットアップ、制限事項、例についてはテナントデータカタログを参照してください。構造化メッセージと EDIFACT については形式、検証、クエリを参照してください。

チャット内の元ファイル（#790）

バージョン管理された Open-WebUI フィルターのインストール、署名付きダウンロード、ファイル制限、保持期間についてはランブックを参照してください。フィルターがインストールされていない場合は、従来のドキュメントテキスト経路が引き続き使用されます。

メールとドキュメント取り込み向け RC3 ホットフィックス（#846）

テーブル検出には、2 列以上のヘッダーと、同じ幅のデータ行が 2 行以上必要です。WORKBENCH_DATASET_MIN_TABLE_RATIO は、テーブルブロック内で必要となる割合を指定します（デフォルトは 0.75、有効範囲は 0.5 より大きく 1 以下）。一般的なパーサーエラーの場合はテキストにフォールバックしますが、実際に検出されたテーブルに対する妥当性チェックは引き続き有効です。ファイル、行、列の予算も引き続き適用されます。明確に特定でき、かつ損失なく復元できない Open-WebUI の分割パターンに限り、WORKBENCH_DATASET_DAMAGED を使用します。

合成フィクスチャを再生成し、ローカルでリグレッションを確認します。

node scripts/generate-conversation-fixtures.js
node scripts/generate-review-fixture.js
node scripts/generate-dataset-fixtures.js
npm test -- --runInBand tests/workbench-846.test.js tests/workbench-838.test.js

既存のライブスクリプトでは、メールの取り込み（1）、プロトコルの要約（3）、別の INVOIC データセットと並行したメール履歴（5）、明示的に指定されたメッセージ（6）も確認します。分離された一時データベースと合成検証テナントを使用して、ローカルブローカーを起動します。すべての言語モデル呼び出しは中央のファサードと既存の呼び出し／トークン予算を通じて行われます。非本番環境の構成でのみ起動してください。

WORKBENCH_ENV_FILE=/path/to/nonproduction.env \
  WORKBENCH_VALIDATION_REPORT=/tmp/rc3-hotfix-846-live.json \
  LIVE_MAX_MODEL_CALLS=80 LIVE_MAX_TOKENS=1000000 \
  node scripts/validate-rc3-closeout-live.js

この拡張機能はライブ実行されていません。ライブレポートは、個別に非本番環境で実行した後に限り、受け入れ証拠として使用できます。