Cernion Energy Tools

エネルギー市場向けマイクロサービスエージェントシステム

Moleculerで構築されたモジュール式でスケーラブルなマイクロサービスプラットフォーム。AI統合（Google Gemini）およびMCP（Model Context Protocol）サポートを備えたエネルギー市場アプリケーションを開発するための基盤です。

特徴

• 🚀 Moleculerマイクロサービスフレームワーク — 高速でモダン、かつ強力なマイクロサービスフレームワーク

• 🌐 APIゲートウェイ — 自動ルート生成機能を備えたHTTP REST API

• 🤖 AIエージェント — Google Geminiを活用した自然言語クエリプランナー：エネルギーデータのニーズを平易なテキストで記述すると、エージェントが自動的にマルチステップのマイクロサービス計画を生成、実行、解釈します

• 🏢 社内データソース — 公共のエネルギーツールと並行して、内部の公益事業データセット（CSV、REST、GeoJSON、XLSX、DOCX、スクレイパー）を登録、推論、キャッシュ、検出します

• 🧩 リサーチWebアプリ — /app に組み込まれたシングルページアプリケーション。AIエージェントのブラウザベースでの対話型テストが可能で、別途ツールを用意する必要はありません

• 📥 ライブCSVエクスポート — すべてのエージェント結果は、パラメータ化されたGETエンドポイント（/api/agent/session/:id/csv?param=value）を公開しており、Microsoft Power Automate、Excel Power Query、cronジョブなどの自動化ツールと設定不要で統合できます

• 💾 データポイント — 組み込みのPouchDBをバックエンドとする、名前付き・バージョン管理・ヘルス監視されたデータソース。エージェントセッションを管理対象のデータポイントに昇格させ、更新履歴やスキーマの安定性を追跡し、/api/datapoints 経由でJSONまたはCSVとしてライブデータを取得できます。登録済みデータポイントのダッシュボードについては、ヘルス概要を参照してください。

• 📸 スナップショット — SHA-256の出自ハッシュを使用して、データポイントのグループを一貫した単位として封印します。/api/datapoints/snapshot*（v0.13）経由でスナップショットの作成、検証（ドリフト検出）、一覧表示、削除が可能です

• 🌍 OSM地理レイヤー — OpenStreetMap/Overpassによるグリッドインフラ分析：VNB割り当て検証、近隣インフラ、変電所インベントリ、グリッドトポロジー（v0.10）

• 🌐 OEPコネクタ — /api/oep/*（v0.12）経由でOpen Energy Platform（シナリオデータ、NEP参照、研究データセット）への読み取り専用アクセスを提供

• 🔌 グリッド接続検証 — 決定論的な6ステップのNetzanschlussパイプライン（POST /api/grid-connection/validate）：インベントリ → デルタ → 容量 → EWKベンチマーク → Go/No-Go判定 → 監査証跡。LLMを使用せず、入力が同じであれば結果も同一です。EU AI法第12条への準拠のため、レポートはPouchDBスナップショットで封印されます（v0.14）

• 🤝 エネルギーシェアリング検証 — 決定論的な6ステップの§ 42c EnWGパイプライン（POST /api/energy-sharing/validate）：発電機/消費者の適格性、MaLo検証、シェア合計チェック、DV検証。規制期限：2026年6月1日（v0.15）

• 📊 MaStRデータ品質監査 — 8ステップのポートフォリオ品質監査（POST /api/mastr-quality/audit）：登録の完全性、容量の妥当性、NAP/MeLo接続性、重複検出、地理スポットチェック。5つの次元にわたる0〜100の加重スコア（v0.17）

• ⚡ Redispatch事後監査 — 7ステップのRedispatch 2.0決済準備状況監査（POST /api/redispatch/audit）：ポートフォリオ構成（Weg A/B）、NAP/MeLo/DVチェック、削減データ、財務リスクスコアリング（v0.18）

• 🗂️ ダッシュボードAPI — 4つの複合エンドポイント（GET /api/dashboard/*）を備えた読み取り専用UIアグリゲーター：VNB概要、市場スナップショット、品質サマリー、発見コード参照。すべてのアップストリーム呼び出しは Promise.allSettled を介して並列実行され、正常な劣化（graceful degradation）と5〜15分のキャッシュを備えています（v0.19）

• 🧠 OEO / OEMetadata — 45以上のすべてのRESTエンドポイントに対するOpen Energy Ontologyアノテーション、オプションのJSONスキーマ検証付きのOEMetadata v2.0エクスポート（v0.11.4–v0.12）

• 🔐 データの出自 — EU AI法第12条への準拠のため、データポイントの更新ごとにSHA-256の出自ハッシュを生成し、エージェントの修正に関する説明可能性ログも記録（v0.11.5）

• 🧹 プロンプトスクラバー — 外部LLMにデータを送信する前に、エネルギー領域の許可リストを使用してフィールドレベルのPII（個人識別情報）をマスキング（v0.11.5）

• 🔌 MCPサポート — Model Context Protocol SDK統合

• 📝 OpenAPIドキュメント — /api/docs で自動APIドキュメントを提供

• 🧭 DSO/VNB検索 — VNBdigital検索/ルックアップおよびBDEW → MaStR解決

• 🛠️ CLIツール — マイクロサービスを呼び出すためのコマンドラインインターフェース

• 📦 サービステンプレート — すぐに使用可能なスケルトンサービステンプレート

• 🔄 ホットリロード — 開発中の自動サービスリロード

• 🎯 ベストプラクティス — ESLint、Prettier、および構造化されたプロジェクトレイアウト

Related MCP server: EnergyAtIt MCP Server

ドキュメント

• CHANGELOG.md - リリースノートおよび重要な変更点

• MCP_TOOLS.md - MCPツールリファレンス

• MCP_SERVICES.md - マイクロサービスとツールのマッピング

• BEARER_TOKEN_AUTHENTICATION.md - 認証ガイド

• docs/BACKEND_CONTEXT.md - バックエンドアーキテクチャリファレンス（サービス、PouchDB、発見コード、認証）

• llm.txt - 生成されたLLMコンテキストアーティファクト（アーキテクチャ + ドメイン知識 + クックブック + OpenAPI）

• docs/ui-contracts/ - フロントエンド ↔ バックエンドAPI契約（v0.20、14ドキュメント）

• docs/MAINTENANCE_MILESTONE_CHECKLIST.md - マイルストーン前の品質/セキュリティゲートチェックリスト

• SECURITY.md - セキュリティポリシーおよび開示

• CODE_OF_CONDUCT.md - コミュニティガイドライン

CI/CDと透明性

• main へのプルリクエストおよびプッシュは、自動化された品質チェック（lint、ビルド、ユニットカバレッジゲート、統合検出の健全性、OpenAPI監査、セキュリティ監査）を実行します。

• セキュリティ分析はCodeQLによって継続的に強制されます。

• バージョンタグ（v*）はリリースパイプライン（release:check + ビルド + GitHubリリース）をトリガーします。

• llm.txt はリリースチェックで検証され、npm run generate:llm を介して信頼できるソースファイルから再生成されます。

• メンテナンスCIでは、CHANGELOG.md が変更された際に llm.txt の同期が厳密にチェックされます。

• カバレッジレポートはアップロードされ、Codecov経由で公開されます。

• 推奨されるリポジトリ設定：main ブランチの保護を有効にし、マージ前に Maintenance CI + CodeQL チェックを必須にしてください。

クイックスタート

前提条件

• Node.js 18+

• npm または yarn

インストール

# Clone the repository
git clone https://github.com/energychain/cernion-energy-tools.git
cd cernion-energy-tools

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Edit .env and add your API keys (see Configuration section)
nano .env

サービスの実行

# Start all services
npm start

# Or use development mode with hot reload
npm run dev

APIゲートウェイはデフォルトで http://localhost:3000 で起動します。

CLIの使用

# Call a microservice action
npm run cli -- skeleton.hello --name=John

# Health check
npm run cli -- skeleton.health

# Get help
npm run cli -- --help

リサーチWebアプリ

/app にある組み込みのWebアプリケーションを使用すると、curlやSwaggerフォーム、コーディングを必要とせず、平易な自然言語ですべてのマイクロサービスを探索できます。

ワークフロー

1. 質問を記述する — 平易な英語またはドイツ語で入力します。例： "Alle PV-Anlagen im Netz der Enercity in Hannover"

2. 計画を確認する — AIが質問を番号付きのマイクロサービス呼び出しシーケンスに分解し、どのサービスがどのパラメータで呼び出されるかを正確に表示します。

3. パラメータを調整する — クエリから抽出された具体的な値（日付、郵便番号、MeLo ID、事業者名など）が、事前入力された編集可能なフォームフィールドとして表示されます。計画を再生成することなく、値を変更できます。

4. 実行して探索する — 結果は並べ替えやフィルタリングが可能なテーブルに表示されます。デバッグ用に各ステップの生のJSONも利用可能です。

5. 共有または自動化する — 共有可能なURLと ライブCSVリンク が自動的に生成されます（下記参照）。

自動化のためのライブCSV

完了したすべての分析は、パラメータ化されたCSVエンドポイントを公開します：

GET /api/agent/session/<id>/csv?param1=value1&param2=value2

• クエリは呼び出されるたびに実際のデータソースに対して ライブで再実行 されるため、データが古くなることはありません。

• GETパラメータは保存された値を 上書き するため、同じセッションURLを異なる日付、地域、識別子で再利用できます。

• フォームフィールドを変更すると、UI内のCSV URLがリアルタイムで更新されます。

Power Automate / Excel Power Queryの例：

http://10.0.0.8:3900/api/agent/session/2a70e478-90ce-4fa5-b996-6f98efdba7cf/csv?startDate=2026-03-01

HTTP → Get file アクションまたはPower Queryの Web データソースをこのURLに向けます。startDate パラメータを変更して別の報告期間を取得すれば、再分析は不要です。

その他の自動化パターン：

• cronジョブ / GitHub Actionをスケジュールして、毎日最新のCSVを取得する

• Jupyterノートブックで pandas read_csv(url) に直接フィードする

• Grafana、Power BI、またはCSV URLを受け入れる任意のツールでデータソースとして使用する

新しいサービスの作成

サービス作成ツールの使用

# Create a new service interactively
npm run create

# Or specify a name directly
npm run create -- my-service

これにより、スケルトンテンプレートから custom-services/ に新しいサービスが作成され、custom-tests/ に対応するテストが生成されます。

カスタムサービスはローカル専用であり、gitでは無視されます。プロジェクトに同梱されているコアサービスは services/ に配置されます。

手動でのサービス作成

1. スケルトンテンプレートをコピーします：

   cp templates/skeleton.service.js custom-services/my-service.service.js

2. サービスを編集します — name プロパティを変更し、アクション、イベント、メソッドを追加します。

3. サービスを再起動します：

   npm start

カスタムサービスとテスト

• カスタムサービスは custom-services/ に配置され、起動時に読み込まれます。

• カスタムテストは custom-tests/ に配置され、リリース対象のカバレッジからは除外されます。

• グローバルカバレッジしきい値なしでカスタムテストを実行します：

  npm run test:custom -- my-service.service.test.js

プロジェクト構造

cernion-energy-tools/
├── services/              # Core microservices (shipped with release)
│   ├── api.service.js     # API Gateway + Swagger UI
│   ├── agent.service.js   # AI agent — plan/execute/export
│   ├── assets.service.js  # MaStR installation assets
│   ├── datapoint.service.js # Named datapoints + snapshots (v0.11–v0.13)
│   ├── osm-geo.service.js # OSM geo layer (v0.10)
│   ├── oep.service.js     # Open Energy Platform (v0.12)
│   ├── datasource-registry.service.js
│   ├── datasource-connector.service.js
│   ├── datasource-cache.service.js
│   ├── datasource-discovery.service.js
│   ├── forecast.service.js
│   ├── gas-storage.service.js
│   ├── german-grid.service.js
│   ├── grid-operations.service.js
│   └── ...                # See services/ for full list
├── src/
│   ├── app.html           # Research Web App (single-page)
│   ├── connectors/        # Built-in datasource connector plugins
│   ├── mcp-client.js      # Centralised MCP tool caller
│   ├── async-job-poller.js # Async job polling
│   ├── prompt-scrubber.js  # PII masking for LLM prompts
│   ├── oeo-mappings.js    # OEO class mappings (~150 entries)
│   ├── validation-findings.js # Grid connection finding constants (v0.14)
│   └── oemetadata-builder.js # OEMetadata v2.0 builder
├── custom-services/       # Local/custom services (git-ignored)
├── custom-connectors/     # Local/custom datasource plugins (git-ignored)
├── custom-tests/          # Local/custom tests (git-ignored)
├── templates/
│   └── skeleton.service.js
├── tests/                 # Core test suite
├── scripts/               # Build / audit scripts
├── index.js               # Main entry point
├── cli.js                 # CLI tool
├── create-service.js      # Interactive service creator
├── moleculer.config.js    # Moleculer configuration
├── .env.example           # Environment variables template
└── package.json

設定

環境変数

.env.example を .env にコピーして編集します：