tako-mcp 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# tako-mcp
+
+[Octopus Energy API](https://developer.octopus.energy/docs/api/) の MCP サーバー。
+
+電気・ガスの使用量、料金プラン、単価などを MCP ツール経由で取得できます。Claude をはじめとする LLM でのエネルギー使用状況の分析に活用できます。
+
+## 特徴
+
+- 電気・ガスの使用量データ取得
+- 料金プロダクト一覧・単価検索（Agile の30分単位価格にも対応）
+- 基本料金（スタンディングチャージ）の取得
+- 郵便番号からのグリッド供給ポイント検索
+- MPAN/MPRN/シリアル番号の自動解決（LLM コンテキストには露出しない）
+- プライバシー重視: 住所等の個人情報はツールレスポンスから除外
+
+## 必要条件
+
+- Node.js 22+
+- Octopus Energy の API キーとアカウント番号
+
+## セットアップ
+
+### API キーとアカウント番号の取得
+
+メールアドレスとパスワードから、Kraken GraphQL API 経由で取得できます。
+
+```bash
+npx tako-mcp-get-credentials
+```
+
+対話的に Email / Password を入力すると、`OCTOPUS_API_KEY` と `OCTOPUS_ACCOUNT_NUMBER` が標準出力に出力されます。
+
+```bash
+# .env ファイルに直接書き出す場合
+npx tako-mcp-get-credentials > .env
+```
+
+デフォルトでは Octopus Energy Japan の API (`https://api.oejp-kraken.energy/v1/graphql/`) を使用します。他リージョンの場合は `KRAKEN_GRAPHQL_URL` 環境変数で上書きしてください。
+
+## 使い方
+
+```bash
+OCTOPUS_API_KEY=<token> OCTOPUS_ACCOUNT_NUMBER=A-AAAA1111 npx tako-mcp
+```
+
+デフォルトで `http://localhost:3000` で起動します。MCP エンドポイントは `/mcp` です。
+
+### 環境変数
+
+| 変数名 | 必須 | 説明 |
+|---|---|---|
+| `OCTOPUS_API_KEY` | Yes | Octopus Energy API キー（Basic Auth のユーザー名として使用） |
+| `OCTOPUS_ACCOUNT_NUMBER` | Yes | アカウント番号（例: `A-AAAA1111`） |
+| `PORT` | No | HTTP サーバーのポート番号（デフォルト: `3000`） |
+
+## MCP ツール一覧
+
+| ツール | 説明 | 認証 |
+|---|---|---|
+| `get_account_info` | メーター情報と料金プラン履歴（住所は除外） | 必要 |
+| `get_electricity_consumption` | 電気の使用量データ（期間グルーピング対応） | 必要 |
+| `get_gas_consumption` | ガスの使用量データ（期間グルーピング対応） | 必要 |
+| `list_products` | 利用可能な料金プロダクト一覧 | 不要 |
+| `get_product` | プロダクト詳細（地域別料金含む） | 不要 |
+| `get_electricity_rates` | 電気料金の単位料金（standard/day/night） | 不要 |
+| `get_gas_rates` | ガス料金の単位料金 | 不要 |
+| `get_standing_charges` | 電気・ガスの基本料金 | 不要 |
+| `get_grid_supply_point` | 郵便番号からグリッド供給ポイントを検索 | 不要 |
+
+## クライアント設定
+
+### Claude Code
+
+MCP 設定に以下を追加:
+
+```json
+{
+  "mcpServers": {
+    "tako-mcp": {
+      "type": "http",
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+## 開発
+
+```bash
+npm install
+npm run dev        # tsx で起動
+npm run build      # tsup でバンドル
+npm run typecheck  # 型チェック
+npm run check      # Lint & フォーマット (Biome)
+```
+
+## ライセンス
+
+MIT

package/dist/get-credentials.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+// src/get-credentials.ts
+import * as readline from "readline/promises";
+var DEFAULT_GRAPHQL_URL = "https://api.oejp-kraken.energy/v1/graphql/";
+var OBTAIN_TOKEN_MUTATION = `
+mutation obtainKrakenToken($input: ObtainJSONWebTokenInput!) {
+  obtainKrakenToken(input: $input) {
+    token
+  }
+}
+`;
+var GET_ACCOUNT_QUERY = `
+query accountViewer {
+  viewer {
+    accounts {
+      number
+    }
+  }
+}
+`;
+async function graphqlRequest(url, query, variables, token) {
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (token) {
+    headers.authorization = `JWT ${token}`;
+  }
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ query, variables })
+  });
+  const data = await response.json();
+  if (data.errors?.length) {
+    throw new Error(data.errors.map((e) => e.message).join(", "));
+  }
+  if (!data.data) {
+    throw new Error("No data in GraphQL response");
+  }
+  return data.data;
+}
+async function getToken(url, email, password) {
+  const data = await graphqlRequest(url, OBTAIN_TOKEN_MUTATION, {
+    input: { email, password }
+  });
+  return data.obtainKrakenToken.token;
+}
+async function getAccountNumber(url, token) {
+  const data = await graphqlRequest(url, GET_ACCOUNT_QUERY, void 0, token);
+  const accounts = data.viewer.accounts;
+  if (accounts.length === 0) {
+    throw new Error("No accounts found");
+  }
+  return accounts[0].number;
+}
+async function prompt(rl, message) {
+  const answer = await rl.question(message);
+  return answer.trim();
+}
+async function main() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr
+  });
+  try {
+    const graphqlUrl = process.env.KRAKEN_GRAPHQL_URL ?? DEFAULT_GRAPHQL_URL;
+    console.error(`Kraken GraphQL API: ${graphqlUrl}`);
+    console.error("");
+    const email = await prompt(rl, "Email: ");
+    const password = await prompt(rl, "Password: ");
+    console.error("");
+    console.error("Authenticating...");
+    const token = await getToken(graphqlUrl, email, password);
+    console.error("Fetching account number...");
+    const accountNumber = await getAccountNumber(graphqlUrl, token);
+    console.error("");
+    console.error("Done! Set the following environment variables:");
+    console.error("");
+    console.log(`OCTOPUS_API_KEY=${token}`);
+    console.log(`OCTOPUS_ACCOUNT_NUMBER=${accountNumber}`);
+  } finally {
+    rl.close();
+  }
+}
+main().catch((err) => {
+  console.error(`Error: ${err instanceof Error ? err.message : err}`);
+  process.exit(1);
+});

package/dist/index.js

@@ -0,0 +1,500 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StreamableHTTPTransport } from "@hono/mcp";
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+
+// src/client.ts
+var BASE_URL = "https://api.octopus.energy/v1";
+var OctopusClient = class {
+  apiKey;
+  accountNumber;
+  authHeader;
+  meterInfoCache = null;
+  constructor(apiKey2, accountNumber2) {
+    this.apiKey = apiKey2;
+    this.accountNumber = accountNumber2;
+    this.authHeader = `Basic ${btoa(`${this.apiKey}:`)}`;
+  }
+  async fetch(path, options) {
+    const url = new URL(`${BASE_URL}${path}`);
+    if (options?.params) {
+      for (const [key, value] of Object.entries(options.params)) {
+        if (value !== void 0 && value !== "") {
+          url.searchParams.set(key, value);
+        }
+      }
+    }
+    const headers = {};
+    if (options?.auth !== false) {
+      headers.Authorization = this.authHeader;
+    }
+    const response = await fetch(url.toString(), { headers });
+    if (!response.ok) {
+      throw new Error(
+        `Octopus Energy API error: ${response.status} ${response.statusText}`
+      );
+    }
+    return response.json();
+  }
+  /** ページネーションを自動追従して全件取得 */
+  async fetchAllPages(path, options) {
+    const results = [];
+    let url = `${BASE_URL}${path}`;
+    if (options?.params) {
+      const u = new URL(url);
+      for (const [key, value] of Object.entries(options.params)) {
+        if (value !== void 0 && value !== "") {
+          u.searchParams.set(key, value);
+        }
+      }
+      url = u.toString();
+    }
+    while (url) {
+      const headers = {};
+      if (options?.auth !== false) {
+        headers.Authorization = this.authHeader;
+      }
+      const response = await fetch(url, { headers });
+      if (!response.ok) {
+        throw new Error(
+          `Octopus Energy API error: ${response.status} ${response.statusText}`
+        );
+      }
+      const data = await response.json();
+      results.push(...data.results);
+      url = data.next;
+    }
+    return results;
+  }
+  /** アカウント情報からメーター情報を解決してキャッシュ */
+  async resolveMeterInfo() {
+    if (this.meterInfoCache) {
+      return this.meterInfoCache;
+    }
+    const account = await this.getAccount();
+    const activeProperty = account.properties.find((p) => !p.moved_out_at) ?? account.properties[0];
+    if (!activeProperty) {
+      throw new Error("No properties found on account");
+    }
+    const elecPoint = activeProperty.electricity_meter_points[0];
+    const gasPoint = activeProperty.gas_meter_points[0];
+    this.meterInfoCache = {
+      electricity: elecPoint ? {
+        mpan: elecPoint.mpan,
+        serialNumber: elecPoint.meters[0]?.serial_number ?? ""
+      } : null,
+      gas: gasPoint ? {
+        mprn: gasPoint.mprn,
+        serialNumber: gasPoint.meters[0]?.serial_number ?? ""
+      } : null
+    };
+    return this.meterInfoCache;
+  }
+  async getAccount() {
+    return this.fetch(`/accounts/${this.accountNumber}/`);
+  }
+  async getElectricityConsumption(params) {
+    const meterInfo = await this.resolveMeterInfo();
+    if (!meterInfo.electricity) {
+      throw new Error("No electricity meter found on account");
+    }
+    const { mpan, serialNumber } = meterInfo.electricity;
+    const queryParams = {
+      period_from: params.period_from,
+      period_to: params.period_to
+    };
+    if (params.group_by) {
+      queryParams.group_by = params.group_by;
+    }
+    if (params.order_by) {
+      queryParams.order_by = params.order_by;
+    }
+    if (params.page_size) {
+      queryParams.page_size = String(params.page_size);
+    }
+    return this.fetchAllPages(
+      `/electricity-meter-points/${mpan}/meters/${serialNumber}/consumption/`,
+      { params: queryParams }
+    );
+  }
+  async getGasConsumption(params) {
+    const meterInfo = await this.resolveMeterInfo();
+    if (!meterInfo.gas) {
+      throw new Error("No gas meter found on account");
+    }
+    const { mprn, serialNumber } = meterInfo.gas;
+    const queryParams = {
+      period_from: params.period_from,
+      period_to: params.period_to
+    };
+    if (params.group_by) {
+      queryParams.group_by = params.group_by;
+    }
+    if (params.order_by) {
+      queryParams.order_by = params.order_by;
+    }
+    if (params.page_size) {
+      queryParams.page_size = String(params.page_size);
+    }
+    return this.fetchAllPages(
+      `/gas-meter-points/${mprn}/meters/${serialNumber}/consumption/`,
+      { params: queryParams }
+    );
+  }
+  async listProducts(filter) {
+    const params = {};
+    if (filter?.is_variable !== void 0) {
+      params.is_variable = String(filter.is_variable);
+    }
+    if (filter?.is_green !== void 0) {
+      params.is_green = String(filter.is_green);
+    }
+    if (filter?.is_business !== void 0) {
+      params.is_business = String(filter.is_business);
+    }
+    if (filter?.available_at) {
+      params.available_at = filter.available_at;
+    }
+    if (filter?.is_prepay !== void 0) {
+      params.is_prepay = String(filter.is_prepay);
+    }
+    return this.fetchAllPages("/products/", {
+      auth: false,
+      params
+    });
+  }
+  async getProduct(productCode, tariffsActiveAt) {
+    const params = {};
+    if (tariffsActiveAt) {
+      params.tariffs_active_at = tariffsActiveAt;
+    }
+    return this.fetch(`/products/${productCode}/`, {
+      auth: false,
+      params
+    });
+  }
+  async getElectricityRates(productCode, tariffCode, rateType = "standard", params) {
+    const rateSegment = rateType === "standard" ? "standard-unit-rates" : `${rateType}-unit-rates`;
+    const queryParams = {};
+    if (params?.period_from) {
+      queryParams.period_from = params.period_from;
+    }
+    if (params?.period_to) {
+      queryParams.period_to = params.period_to;
+    }
+    if (params?.page_size) {
+      queryParams.page_size = String(params.page_size);
+    }
+    return this.fetchAllPages(
+      `/products/${productCode}/electricity-tariffs/${tariffCode}/${rateSegment}/`,
+      { auth: false, params: queryParams }
+    );
+  }
+  async getGasRates(productCode, tariffCode, params) {
+    const queryParams = {};
+    if (params?.period_from) {
+      queryParams.period_from = params.period_from;
+    }
+    if (params?.period_to) {
+      queryParams.period_to = params.period_to;
+    }
+    if (params?.page_size) {
+      queryParams.page_size = String(params.page_size);
+    }
+    return this.fetchAllPages(
+      `/products/${productCode}/gas-tariffs/${tariffCode}/standard-unit-rates/`,
+      { auth: false, params: queryParams }
+    );
+  }
+  async getStandingCharges(productCode, tariffCode, fuel, params) {
+    const fuelSegment = fuel === "electricity" ? "electricity-tariffs" : "gas-tariffs";
+    const queryParams = {};
+    if (params?.period_from) {
+      queryParams.period_from = params.period_from;
+    }
+    if (params?.period_to) {
+      queryParams.period_to = params.period_to;
+    }
+    if (params?.page_size) {
+      queryParams.page_size = String(params.page_size);
+    }
+    return this.fetchAllPages(
+      `/products/${productCode}/${fuelSegment}/${tariffCode}/standing-charges/`,
+      { auth: false, params: queryParams }
+    );
+  }
+  async getGridSupplyPoint(postcode) {
+    const data = await this.fetch(
+      "/industry/grid-supply-points/",
+      {
+        auth: false,
+        params: { postcode }
+      }
+    );
+    return data.results;
+  }
+};
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools/account.ts
+function registerAccountTools(server, client2) {
+  server.tool(
+    "get_account_info",
+    "Get meter information and tariff history for the account. Does not include address or personal details.",
+    async () => {
+      const account = await client2.getAccount();
+      const sanitized = {
+        number: account.number,
+        properties: account.properties.map((p) => ({
+          id: p.id,
+          moved_in_at: p.moved_in_at,
+          moved_out_at: p.moved_out_at,
+          electricity_meter_points: p.electricity_meter_points,
+          gas_meter_points: p.gas_meter_points
+        }))
+      };
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(sanitized, null, 2) }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/consumption.ts
+import { z } from "zod";
+var consumptionParams = {
+  period_from: z.string().describe(
+    "Start datetime in ISO 8601 format (UTC), e.g. 2024-01-01T00:00Z"
+  ),
+  period_to: z.string().describe("End datetime in ISO 8601 format (UTC), e.g. 2024-02-01T00:00Z"),
+  group_by: z.enum(["day", "week", "month", "quarter"]).optional().describe("Group consumption data by time period")
+};
+function registerConsumptionTools(server, client2) {
+  server.tool(
+    "get_electricity_consumption",
+    "Get electricity consumption data for the account. MPAN and serial number are resolved automatically.",
+    consumptionParams,
+    async (args) => {
+      const data = await client2.getElectricityConsumption({
+        period_from: args.period_from,
+        period_to: args.period_to,
+        group_by: args.group_by
+      });
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(data, null, 2) }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "get_gas_consumption",
+    "Get gas consumption data for the account. MPRN and serial number are resolved automatically.",
+    consumptionParams,
+    async (args) => {
+      const data = await client2.getGasConsumption({
+        period_from: args.period_from,
+        period_to: args.period_to,
+        group_by: args.group_by
+      });
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(data, null, 2) }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/grid.ts
+import { z as z2 } from "zod";
+function registerGridTools(server, client2) {
+  server.tool(
+    "get_grid_supply_point",
+    "Look up Grid Supply Point (GSP) information by postcode. Useful for determining the regional electricity distribution zone. No authentication required.",
+    {
+      postcode: z2.string().describe("UK postcode, e.g. SW1A 1AA")
+    },
+    async (args) => {
+      const data = await client2.getGridSupplyPoint(args.postcode);
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(data, null, 2) }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/products.ts
+import { z as z3 } from "zod";
+function registerProductTools(server, client2) {
+  server.tool(
+    "list_products",
+    "List available energy products/tariffs. No authentication required.",
+    {
+      is_variable: z3.boolean().optional().describe("Filter by variable tariffs"),
+      is_green: z3.boolean().optional().describe("Filter by green tariffs"),
+      is_business: z3.boolean().optional().describe("Filter by business tariffs"),
+      available_at: z3.string().optional().describe("Filter products available at this datetime (ISO 8601)")
+    },
+    async (args) => {
+      const data = await client2.listProducts({
+        is_variable: args.is_variable,
+        is_green: args.is_green,
+        is_business: args.is_business,
+        available_at: args.available_at
+      });
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(data, null, 2) }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "get_product",
+    "Get detailed information about a specific product, including regional tariff details. No authentication required.",
+    {
+      product_code: z3.string().describe("The product code, e.g. AGILE-FLEX-22-11-25"),
+      tariffs_active_at: z3.string().optional().describe("Only show tariffs active at this datetime (ISO 8601)")
+    },
+    async (args) => {
+      const data = await client2.getProduct(
+        args.product_code,
+        args.tariffs_active_at
+      );
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(data, null, 2) }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/rates.ts
+import { z as z4 } from "zod";
+function registerRateTools(server, client2) {
+  server.tool(
+    "get_electricity_rates",
+    "Get electricity unit rates for a product/tariff. Supports Agile's half-hourly pricing. No authentication required.",
+    {
+      product_code: z4.string().describe("The product code"),
+      tariff_code: z4.string().describe("The tariff code, e.g. E-1R-AGILE-FLEX-22-11-25-C"),
+      rate_type: z4.enum(["standard", "day", "night"]).optional().describe("Rate type (default: standard)"),
+      period_from: z4.string().optional().describe("Start datetime (ISO 8601)"),
+      period_to: z4.string().optional().describe("End datetime (ISO 8601)")
+    },
+    async (args) => {
+      const data = await client2.getElectricityRates(
+        args.product_code,
+        args.tariff_code,
+        args.rate_type ?? "standard",
+        {
+          period_from: args.period_from,
+          period_to: args.period_to
+        }
+      );
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(data, null, 2) }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "get_gas_rates",
+    "Get gas unit rates for a product/tariff. No authentication required.",
+    {
+      product_code: z4.string().describe("The product code"),
+      tariff_code: z4.string().describe("The tariff code, e.g. G-1R-VAR-17-01-11-D"),
+      period_from: z4.string().optional().describe("Start datetime (ISO 8601)"),
+      period_to: z4.string().optional().describe("End datetime (ISO 8601)")
+    },
+    async (args) => {
+      const data = await client2.getGasRates(
+        args.product_code,
+        args.tariff_code,
+        {
+          period_from: args.period_from,
+          period_to: args.period_to
+        }
+      );
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(data, null, 2) }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "get_standing_charges",
+    "Get standing charges (daily fixed charges) for a product/tariff. No authentication required.",
+    {
+      product_code: z4.string().describe("The product code"),
+      tariff_code: z4.string().describe("The tariff code"),
+      fuel: z4.enum(["electricity", "gas"]).describe("Fuel type"),
+      period_from: z4.string().optional().describe("Start datetime (ISO 8601)"),
+      period_to: z4.string().optional().describe("End datetime (ISO 8601)")
+    },
+    async (args) => {
+      const data = await client2.getStandingCharges(
+        args.product_code,
+        args.tariff_code,
+        args.fuel,
+        {
+          period_from: args.period_from,
+          period_to: args.period_to
+        }
+      );
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(data, null, 2) }
+        ]
+      };
+    }
+  );
+}
+
+// src/server.ts
+function createMcpServer(client2) {
+  const server = new McpServer({
+    name: "tako-mcp",
+    version: "0.1.0"
+  });
+  registerAccountTools(server, client2);
+  registerConsumptionTools(server, client2);
+  registerProductTools(server, client2);
+  registerRateTools(server, client2);
+  registerGridTools(server, client2);
+  return server;
+}
+
+// src/index.ts
+var apiKey = process.env.OCTOPUS_API_KEY;
+var accountNumber = process.env.OCTOPUS_ACCOUNT_NUMBER;
+if (!apiKey || !accountNumber) {
+  console.error(
+    "Missing required environment variables: OCTOPUS_API_KEY, OCTOPUS_ACCOUNT_NUMBER"
+  );
+  process.exit(1);
+}
+var port = Number(process.env.PORT) || 3e3;
+var client = new OctopusClient(apiKey, accountNumber);
+var mcpServer = createMcpServer(client);
+var transport = new StreamableHTTPTransport();
+await mcpServer.connect(transport);
+var app = new Hono();
+app.all("/mcp", (c) => transport.handleRequest(c));
+app.get("/health", (c) => c.json({ status: "ok" }));
+serve({ fetch: app.fetch, port }, () => {
+  console.log(`tako-mcp server running on http://localhost:${port}`);
+  console.log(`MCP endpoint: http://localhost:${port}/mcp`);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "tako-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Octopus Energy API",
+  "type": "module",
+  "bin": {
+    "tako-mcp": "dist/index.js",
+    "tako-mcp-get-credentials": "dist/get-credentials.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arrow2nd/tako-mcp.git"
+  },
+  "homepage": "https://github.com/arrow2nd/tako-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/arrow2nd/tako-mcp/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup && chmod +x dist/*.js",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/index.ts",
+    "check": "biome check",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "octopus-energy"
+  ],
+  "license": "MIT",
+  "author": "arrow2nd",
+  "dependencies": {
+    "@hono/mcp": "^0.2.3",
+    "@hono/node-server": "^1.19.9",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "hono": "^4.11.9",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@types/node": "^25.2.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}