aiseg2-mcp 0.1.0__tar.gz

aiseg2_mcp-0.1.0/.env.example

@@ -0,0 +1,15 @@
+# Local development env for aiseg2-mcp. Copy to .env and fill in. Never commit a real password.
+
+# AiSEG2 controller base URL (http only — the device has no HTTPS).
+AISEG_URL=http://192.168.0.216
+# HTTP Digest password for the AiSEG2 web UI.
+AISEG_PASSWORD=
+# Optional overrides (defaults shown):
+# AISEG_USER=aiseg
+# AISEG_TRANSPORT=stdio            # or streamable-http
+# AISEG_HOST=0.0.0.0               # streamable-http bind host
+# AISEG_PORT=8000                  # streamable-http bind port
+# AISEG_DISABLE_DNS_REBINDING_PROTECTION=false  # true ONLY behind a trusted auth proxy
+# AISEG_CACHE_DIR=                 # SD-card history cache dir (default: <tempdir>/aiseg2-mcp-cache)
+# AISEG_CACHE_TTL=3600             # seconds to reuse a cached history export before re-downloading
+# LOG_LEVEL=info

aiseg2_mcp-0.1.0/.github/workflows/build.yml

@@ -0,0 +1,53 @@
+name: Build and Push
+
+# Builds the MCP server image and pushes it to the Zot registry (fumo homelab delivery). ArgoCD
+# Image Updater then detects the new 7-hex SHA tag and writes it back to the k8s overlay. This is
+# independent of test.yml / release.yml (PyPI + GHCR public distribution). Excludes k8s/** on
+# purpose: Image Updater writes the new tag into k8s/overlays/production/.argocd-source-*.yaml, so
+# triggering on it would loop forever (writeback -> build -> new tag -> writeback -> ...).
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'aiseg2_mcp/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'Dockerfile'
+      - '.github/workflows/build.yml'
+  workflow_dispatch: {}
+
+jobs:
+  build:
+    # GitHub-hosted arm64 native runner (no QEMU); the k3s cluster is all arm64.
+    runs-on: ubuntu-24.04-arm
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Get image tag
+        id: tag
+        run: echo "tag=$(echo $GITHUB_SHA | cut -c1-7)" >> "$GITHUB_OUTPUT"
+
+      - name: Login to Zot registry
+        uses: docker/login-action@v3
+        with:
+          registry: registry.fumo.jp
+          username: ${{ secrets.ZOT_USERNAME }}
+          password: ${{ secrets.ZOT_PASSWORD }}
+
+      - name: Build and Push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: Dockerfile
+          platforms: linux/arm64
+          push: true
+          tags: registry.fumo.jp/aiseg2-mcp:${{ steps.tag.outputs.tag }}
+          # type=gha lives in the same datacenter as the hosted runner; caches the slow uv sync
+          # dependency layer (the ephemeral runner throws away the Dockerfile --mount cache).
+          cache-from: type=gha,scope=aiseg2-mcp-deps
+          cache-to: type=gha,scope=aiseg2-mcp-deps,mode=max

aiseg2_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,150 @@
+name: Release
+
+# Tag-driven release: publishes the PyPI package, the multi-arch GHCR image, and the MCP registry
+# entry. Triggered by pushing a semver tag (e.g. v0.1.0).
+#
+# Prerequisite (one-time, human): configure PyPI Trusted Publishing for this workflow/environment
+# so publish-pypi needs no API token. Until that is set up, do not push a release tag.
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+env:
+  IMAGE: ghcr.io/chanyou0311/aiseg2-mcp
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --locked
+      - run: uv run pytest -q
+
+  publish-pypi:
+    needs: test
+    runs-on: ubuntu-24.04
+    environment: pypi
+    permissions:
+      id-token: write  # Trusted Publishing (OIDC); no API token needed
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true  # hatch-vcs derives the version from the tag
+      - uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-ghcr:
+    needs: test
+    runs-on: ${{ matrix.runner }}
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: ubuntu-24.04
+            platform: linux/amd64
+            arch: amd64
+          - runner: ubuntu-24.04-arm
+            platform: linux/arm64
+            arch: arm64
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: ${{ matrix.platform }}
+          outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=true
+      - name: Export digest
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.build.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: digests-${{ matrix.arch }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  merge-ghcr:
+    needs: publish-ghcr
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/digests
+          pattern: digests-*
+          merge-multiple: true
+      - uses: docker/setup-buildx-action@v3
+      - name: Docker metadata (tags)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.IMAGE }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Create manifest list and push
+        working-directory: /tmp/digests
+        run: |
+          docker buildx imagetools create \
+            $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            $(printf '${{ env.IMAGE }}@sha256:%s ' *)
+      - name: Inspect
+        run: docker buildx imagetools inspect ${{ env.IMAGE }}:${{ steps.meta.outputs.version }}
+
+  publish-mcp-registry:
+    needs: [publish-pypi, merge-ghcr]
+    runs-on: ubuntu-24.04
+    permissions:
+      id-token: write  # GitHub OIDC login to the MCP registry
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Stamp version into server.json
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          jq --arg v "$VERSION" '.version = $v | .packages |= map(.version = $v)' server.json > server.json.tmp
+          mv server.json.tmp server.json
+      - name: Install mcp-publisher
+        run: |
+          TAG=$(curl -sSL https://api.github.com/repos/modelcontextprotocol/registry/releases/latest | jq -r .tag_name)
+          VER="${TAG#v}"
+          curl -sSL "https://github.com/modelcontextprotocol/registry/releases/download/${TAG}/mcp-publisher_${VER}_linux_amd64.tar.gz" \
+            | tar xz mcp-publisher
+      - name: Login (GitHub OIDC)
+        run: ./mcp-publisher login github-oidc
+      - name: Publish to MCP registry
+        run: ./mcp-publisher publish

aiseg2_mcp-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,19 @@
+name: Test
+
+# Runs the test suite (parser regressions + read-only tool-surface guards) on every push and PR.
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Sync deps (locked)
+        run: uv sync --locked
+      - name: Run tests
+        run: uv run pytest -q

aiseg2_mcp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+.pytest_cache/
+*.egg-info/
+dist/
+build/

aiseg2_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

aiseg2_mcp-0.1.0/Dockerfile

@@ -0,0 +1,41 @@
+# Container image for the AiSEG2 MCP server. Two-stage uv build; the dependency layer caches until
+# pyproject.toml / uv.lock change. Built from the repo root (context: .).
+#
+# The image defaults to the streamable-http transport because a container is normally run as a
+# long-lived network service (behind an authenticating proxy). stdio users should instead run the
+# published PyPI package with `uvx aiseg2-mcp`.
+#
+# Note: .git is not in the build context, so hatch-vcs falls back to version 0.0.0 inside the image
+# (the real version is carried by the image tag). Pass SETUPTOOLS_SCM_PRETEND_VERSION at build time
+# to override if an accurate __version__ is needed in the container.
+
+# --- build stage -----------------------------------------------------------------------------
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS build
+WORKDIR /app
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy
+
+# Dependency layer: manifests only, so it caches until deps change.
+COPY pyproject.toml uv.lock ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --locked --no-dev --no-install-project
+
+# Source layer: copy the package and install it into the venv.
+COPY aiseg2_mcp/ aiseg2_mcp/
+COPY README.md ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --locked --no-dev --no-editable
+
+# --- runtime stage ---------------------------------------------------------------------------
+FROM python:3.12-slim-bookworm
+LABEL io.modelcontextprotocol.server.name="io.github.chanyou0311/aiseg2-mcp"
+WORKDIR /app
+COPY --from=build /app/.venv /app/.venv
+ENV PATH="/app/.venv/bin:$PATH" \
+    AISEG_TRANSPORT=streamable-http
+# Run unprivileged. USER must be NUMERIC: Kubernetes runAsNonRoot cannot verify a non-root user
+# from a name and refuses to start the container, so reference the UID.
+RUN useradd -u 10001 -m app
+USER 10001
+EXPOSE 8000
+CMD ["python", "-m", "aiseg2_mcp"]

aiseg2_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chanyou0311
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiseg2_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: aiseg2-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for the Panasonic AiSEG2 HEMS controller.
+Project-URL: Homepage, https://github.com/chanyou0311/aiseg2-mcp
+Project-URL: Repository, https://github.com/chanyou0311/aiseg2-mcp
+Author: chanyou0311
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aiseg2,hems,home-energy,mcp,panasonic
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: lxml>=5
+Requires-Dist: mcp<2,>=1.28
+Requires-Dist: pydantic-settings>=2
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.chanyou0311/aiseg2-mcp -->
+
+# aiseg2-mcp
+
+日本語版は [README.ja.md](./README.ja.md) をご覧ください。
+
+An **unofficial, read-only** [Model Context Protocol](https://modelcontextprotocol.io) server for
+the **Panasonic AiSEG2** home energy management (HEMS) controller. It lets an MCP client (e.g.
+Claude) read your home's live power flow, per-circuit consumption, circuit names, and daily energy
+totals from the AiSEG2's local web interface.
+
+This project is not affiliated with or endorsed by Panasonic. "AiSEG" is a Panasonic trademark.
+
+## Verified environment
+
+Developed and tested against:
+
+- AiSEG2 model **MKN713** series
+- Firmware **Ver.2.97I-01**
+
+The AiSEG2 web interface is undocumented and changes between firmware revisions. **On a different
+model or firmware the pages this server scrapes may differ and some tools may not work.** If you hit
+a parse error, please open an issue with your model / firmware version.
+
+## Tools
+
+All tools are **read-only** (annotated `readOnlyHint`, non-destructive). The server only issues
+GETs and the display-only refresh POSTs the web UI itself uses; it never touches settings or any
+`/action/` endpoint.
+
+| Tool | Returns |
+|---|---|
+| `get_power_flow` | Instantaneous generation/consumption (kW), buy/sell state, battery status, generation sources, top consuming circuits |
+| `get_circuit_breakdown` | Every measured circuit's instantaneous draw (W), ranked highest first, with the total |
+| `list_circuits` | Registered circuit ids and names (the authoritative naming source) |
+| `get_daily_totals` | Today's cumulative generation / consumption / grid-buy / grid-sell (kWh) |
+| `get_history` | Long-term energy history from the SD-card export (Wh), long-form points. Args: `granularity` (`30min`/`hour`/`day`/`month`/`year`), `start`/`end` (per granularity: `YYYY-MM-DD`, `YYYY-MM`, or `YYYY`), optional `metrics`/`circuits` filters, `limit`/`offset` paging |
+| `get_cost_history` | Long-term energy-cost history from the SD-card export (JPY). Args: `granularity` (`day`/`month`/`year`), `start`/`end`, `limit`/`offset` |
+
+> **The two history tools require an SD card inserted in the AiSEG2** — they read the device's SD-card CSV export. The export is downloaded once and cached (see `AISEG_CACHE_DIR` / `AISEG_CACHE_TTL`), so the first call is slow and later calls are fast.
+
+## Install & run
+
+Three ways to run it, depending on your setup.
+
+### 1. uvx (PyPI — once published)
+
+The simplest option for a local (stdio) MCP client. Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+AISEG_URL=http://192.168.0.216 AISEG_PASSWORD=... uvx aiseg2-mcp
+```
+
+Add it to Claude Code:
+
+```bash
+claude mcp add aiseg2 \
+  --env AISEG_URL=http://192.168.0.216 \
+  --env AISEG_PASSWORD=your-digest-password \
+  -- uvx aiseg2-mcp
+```
+
+### 2. docker run (GHCR)
+
+The container defaults to the `streamable-http` transport (long-lived network service). Only expose
+it behind an authenticating proxy — see [Security](#security).
+
+```bash
+docker run --rm -p 8000:8000 \
+  -e AISEG_URL=http://192.168.0.216 \
+  -e AISEG_PASSWORD=your-digest-password \
+  ghcr.io/chanyou0311/aiseg2-mcp:latest
+```
+
+### 3. From source
+
+Requires Python 3.12+ and uv.
+
+```bash
+uv sync
+AISEG_URL=http://192.168.0.216 AISEG_PASSWORD=... uv run aiseg2-mcp
+```
+
+### Remote (authenticated claude.ai Custom Connector)
+
+To reach the server from claude.ai while your AiSEG2 stays on your LAN, see
+[`examples/remote/`](./examples/remote/) — a Docker Compose stack (MCP + GitHub-OAuth proxy +
+Cloudflare Tunnel).
+
+## Configuration (environment variables)
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `AISEG_URL` | yes | — | AiSEG2 base URL, e.g. `http://192.168.0.216` (http only) |
+| `AISEG_PASSWORD` | yes | — | HTTP Digest password for the AiSEG2 web UI |
+| `AISEG_USER` | no | `aiseg` | HTTP Digest user |
+| `AISEG_TRANSPORT` | no | `stdio` | `stdio` or `streamable-http` |
+| `AISEG_HOST` | no | `0.0.0.0` | Bind host (streamable-http only) |
+| `AISEG_PORT` | no | `8000` | Bind port (streamable-http only) |
+| `AISEG_DISABLE_DNS_REBINDING_PROTECTION` | no | `false` | Disable the SDK Host allowlist — **only** behind a trusted auth proxy |
+| `AISEG_CACHE_DIR` | no | `<tempdir>/aiseg2-mcp-cache` | Where the SD-card history export is cached |
+| `AISEG_CACHE_TTL` | no | `3600` | Seconds to reuse a cached history export before re-downloading |
+| `LOG_LEVEL` | no | `info` | Log level |
+
+## Security
+
+- **LAN-only by design.** The AiSEG2 speaks plain HTTP with Digest auth; keep it and this server on
+  a trusted local network. The password is read from the environment and is never logged.
+- **Read-only.** There is no tool that changes a device setting. The tool surface is enforced by
+  tests (registered-tool allowlist, tool-name guard, a source scan for `/action/`, and read-only
+  annotation checks).
+- **Do not expose the `streamable-http` transport to untrusted networks without authentication.**
+  This server carries no auth of its own; if you run it as a network service, put an authenticating
+  reverse proxy in front of it. `AISEG_DISABLE_DNS_REBINDING_PROTECTION=true` is only appropriate in
+  that proxied setup.
+
+## Acknowledgements
+
+The AiSEG2 web interface is undocumented; this project builds on the reverse-engineering knowledge
+shared by prior work:
+
+- [shimosyan/aiseg2-influxdb-forwarder](https://github.com/shimosyan/aiseg2-influxdb-forwarder) — the circuit-paging "repeat the last page" terminator and the electric-flow fields.
+- [hiroaki0923/aiseg2-bridge](https://github.com/hiroaki0923/aiseg2-bridge) — endpoint and page structure.
+- [Bugfire/aiseg_download](https://github.com/Bugfire/aiseg_download) — Digest auth and data-endpoint conventions.
+
+## License
+
+[MIT](./LICENSE)

aiseg2_mcp-0.1.0/README.ja.md

@@ -0,0 +1,126 @@
+# aiseg2-mcp
+
+English version: [README.md](./README.md)
+
+Panasonic **AiSEG2**（HEMS コントローラー）を対象とした、**非公式・読み取り専用**の
+[Model Context Protocol](https://modelcontextprotocol.io) サーバーです。MCP クライアント
+（Claude など）から、AiSEG2 のローカル Web インターフェース経由で、自宅のリアルタイムな電力フロー・
+回路別消費電力・回路名・日次エネルギー総量を読み取れます。
+
+本プロジェクトは Panasonic とは無関係であり、Panasonic による承認・提携はありません。
+「AiSEG」は Panasonic の商標です。
+
+## 検証済み環境
+
+以下の環境で開発・動作確認しています。
+
+- AiSEG2 機種: **MKN713** 系
+- ファームウェア: **Ver.2.97I-01**
+
+AiSEG2 の Web インターフェースは非公開で、ファームウェアの版により変化します。
+**機種やファームウェアが異なると、本サーバーがスクレイプするページの構造が変わり、一部のツールが
+動作しない可能性があります。** パースエラーが出た場合は、機種・ファームウェア版を添えて issue を
+立ててください。
+
+## ツール一覧
+
+すべて**読み取り専用**（`readOnlyHint`・非破壊のアノテーション付き）です。本サーバーは GET と、
+Web UI 自身が画面更新に使う表示用 POST のみを発行し、設定変更や `/action/` 系エンドポイントには
+一切触れません。
+
+| ツール | 返す内容 |
+|---|---|
+| `get_power_flow` | 瞬時の発電/消費（kW）、売買電の状態、蓄電池状態、発電内訳、消費上位回路 |
+| `get_circuit_breakdown` | 計測回路ごとの瞬時消費電力（W）を降順で全件・合計付き |
+| `list_circuits` | 登録された回路の id と名称（名称の正本） |
+| `get_daily_totals` | 当日の発電/消費/買電/売電の積算（kWh） |
+| `get_history` | SD カードエクスポートからの長期履歴（Wh）をロング形式で。引数: `granularity`（`30min`/`hour`/`day`/`month`/`year`）、`start`/`end`（粒度に応じ `YYYY-MM-DD` / `YYYY-MM` / `YYYY`）、任意の `metrics`/`circuits` フィルタ、`limit`/`offset` ページング |
+| `get_cost_history` | SD カードエクスポートからの長期コスト履歴（円）。引数: `granularity`（`day`/`month`/`year`）、`start`/`end`、`limit`/`offset` |
+
+> **履歴系 2 ツールは AiSEG2 に SD カードが挿入されている場合のみ動作する** — デバイスの SD カード CSV エクスポートを読む。エクスポートは 1 回だけダウンロードしてキャッシュする（`AISEG_CACHE_DIR` / `AISEG_CACHE_TTL` 参照）。初回呼び出しは遅く、以降は高速。
+
+## インストール・起動
+
+環境に応じて 3 通りの起動方法があります。
+
+### 1. uvx（PyPI 公開後）
+
+ローカル（stdio）MCP クライアント向けの最も簡単な方法。[uv](https://docs.astral.sh/uv/) が必要です。
+
+```bash
+AISEG_URL=http://192.168.0.216 AISEG_PASSWORD=... uvx aiseg2-mcp
+```
+
+Claude Code に追加:
+
+```bash
+claude mcp add aiseg2 \
+  --env AISEG_URL=http://192.168.0.216 \
+  --env AISEG_PASSWORD=your-digest-password \
+  -- uvx aiseg2-mcp
+```
+
+### 2. docker run（GHCR）
+
+コンテナは既定で `streamable-http` トランスポート（常駐ネットワークサービス）になります。
+必ず認証付きプロキシの背後で公開してください（[セキュリティ](#セキュリティ)参照）。
+
+```bash
+docker run --rm -p 8000:8000 \
+  -e AISEG_URL=http://192.168.0.216 \
+  -e AISEG_PASSWORD=your-digest-password \
+  ghcr.io/chanyou0311/aiseg2-mcp:latest
+```
+
+### 3. ソースから
+
+Python 3.12 以上と uv が必要です。
+
+```bash
+uv sync
+AISEG_URL=http://192.168.0.216 AISEG_PASSWORD=... uv run aiseg2-mcp
+```
+
+### リモート（認証付き claude.ai Custom Connector）
+
+AiSEG2 を LAN 内に置いたまま claude.ai から接続するには、[`examples/remote/`](./examples/remote/)
+を参照してください（MCP + GitHub OAuth プロキシ + Cloudflare Tunnel の Docker Compose 構成）。
+
+## 設定（環境変数）
+
+| 変数 | 必須 | 既定値 | 説明 |
+|---|---|---|---|
+| `AISEG_URL` | はい | — | AiSEG2 のベース URL 例: `http://192.168.0.216`（http のみ） |
+| `AISEG_PASSWORD` | はい | — | AiSEG2 Web UI の HTTP Digest パスワード |
+| `AISEG_USER` | いいえ | `aiseg` | HTTP Digest ユーザー |
+| `AISEG_TRANSPORT` | いいえ | `stdio` | `stdio` または `streamable-http` |
+| `AISEG_HOST` | いいえ | `0.0.0.0` | バインドホスト（streamable-http のみ） |
+| `AISEG_PORT` | いいえ | `8000` | バインドポート（streamable-http のみ） |
+| `AISEG_DISABLE_DNS_REBINDING_PROTECTION` | いいえ | `false` | SDK の Host 許可リストを無効化。**信頼できる認証プロキシ配下でのみ** |
+| `AISEG_CACHE_DIR` | いいえ | `<tempdir>/aiseg2-mcp-cache` | SD カード履歴エクスポートのキャッシュ先 |
+| `AISEG_CACHE_TTL` | いいえ | `3600` | キャッシュした履歴エクスポートを再ダウンロードするまでの秒数 |
+| `LOG_LEVEL` | いいえ | `info` | ログレベル |
+
+## セキュリティ
+
+- **LAN 内利用が前提。** AiSEG2 は平文 HTTP + Digest 認証です。AiSEG2 と本サーバーは信頼できる
+  ローカルネットワーク内に置いてください。パスワードは環境変数から読み込み、ログには出力しません。
+- **読み取り専用。** 設定を変更するツールは存在しません。ツール表面はテストで強制しています
+  （登録ツールの許可リスト、ツール名ガード、`/action/` のソース走査、読み取り専用アノテーション検査）。
+- **`streamable-http` トランスポートを認証なしで信頼できないネットワークに公開しないでください。**
+  本サーバー自身は認証を持ちません。ネットワークサービスとして動かす場合は、前段に認証付きリバース
+  プロキシを置いてください。`AISEG_DISABLE_DNS_REBINDING_PROTECTION=true` はそのプロキシ構成でのみ
+  適切です。
+
+## 謝辞
+
+AiSEG2 の Web インターフェースは非公開であり、本プロジェクトは先行するリバースエンジニアリングの
+知見に基づいています。
+
+- [shimosyan/aiseg2-influxdb-forwarder](https://github.com/shimosyan/aiseg2-influxdb-forwarder) — 回路ページングの「前頁と同一で終端」判定、電力フローのフィールド。
+- [hiroaki0923/aiseg2-bridge](https://github.com/hiroaki0923/aiseg2-bridge) — エンドポイントとページ構造。
+- [Bugfire/aiseg_download](https://github.com/Bugfire/aiseg_download) — Digest 認証と data エンドポイントの流儀。
+
+## ライセンス
+
+[MIT](./LICENSE)