港华燃气 MCP Server

用于查询港华燃气登录后账户数据的 MCP server。CLI 主要用于本地调试和验证，TypeScript SDK 作为附带能力提供。

安装与构建

要求 Node.js 20 或更高版本。

pnpm install
pnpm run build
pnpm test

src/ 是 TypeScript 源码；MCP server 和调试 CLI 的可执行入口由 src/cli/ 编译到 dist/src/cli/。因此本地使用前需要先执行 pnpm run build。

构建流程使用 esbuild 生成 JavaScript，并用 TypeScript 生成 .d.ts 类型声明。

Docker 镜像使用 pnpm run build:docker 生成单文件 MCP bundle。运行层不包含 node_modules。

仓库内可以直接通过 pnpm 脚本启动 MCP server 或调试 CLI：

pnpm towngas:mcp
pnpm towngas user
pnpm towngas accounts

也可以把本仓库的命令链接到本机：

pnpm link --global

之后即可直接使用全局命令：

towngas user
towngas-mcp

配置

MCP server、调试 CLI 和附带 SDK 都支持从环境变量读取默认配置，也会通过 dotenv 自动读取当前工作目录的 .env 文件。用户需要自行提供 access_token 或 refresh_token，项目不会自动完成网页登录。

字段说明：

MCP Server

启动 Streamable HTTP MCP server：

towngas-mcp

默认监听本机 127.0.0.1:3000。需要对容器或局域网开放时，显式设置监听地址：

towngas-mcp --listen-host 0.0.0.0 --port 3000

HTTP MCP endpoint 默认为：

http://localhost:3000/mcp

Docker 镜像默认启动 Streamable HTTP server，监听容器内 0.0.0.0:3000：

docker run --rm \
  -p 3000:3000 \
  -e TOWNGAS_HOST=https://your-company.towngasvcc.com \
  -e TOWNGAS_ORG_CODE=YOUR_ORG_CODE \
  -e TOWNGAS_SUBS_CODE=YOUR_SUBS_CODE \
  -e TOWNGAS_REFRESH_TOKEN=YOUR_REFRESH_TOKEN \
  -e TOWNGAS_ACCESS_TOKEN=YOUR_ACCESS_TOKEN \
  ghcr.io/sdrpsps/towngas-mcp:latest

MCP server 默认从环境变量或 .env 读取配置。MCP 工具不接受 token 参数，也不会在工具返回值中暴露 access_token 或 refresh_token。

当前 MCP 工具：

所有 MCP 工具都注册了 outputSchema。

登录后业务工具统一返回：

{
  "result": {},
  "meta": {
    "host": "https://your-company.towngasvcc.com",
    "orgCode": "YOUR_ORG_CODE",
    "subsCode": "YOUR_SUBS_CODE",
    "fetchedAt": "2026-06-24T00:00:00.000Z",
    "tokenExpiresAt": "2026-06-24T00:15:00.000Z"
  }
}

字段口径来自实测响应和网页版命名推测。不同地区可能返回额外字段，schema 会保留这些字段。

调试 CLI

登录后查询：

towngas user
towngas accounts
towngas bills --page-index 1 --page-size 10
towngas readings
towngas router --scene 2003

也可以显式覆盖默认户号、机构编码或 host：

towngas bills \
  --host https://your-company.towngasvcc.com \
  --org-code YOUR_ORG_CODE \
  --subs-code YOUR_SUBS_CODE \
  --page-index 1 \
  --page-size 10

CLI 用于本地调试和验证 MCP 背后的接口能力，当前命令包括：

常用参数：

附带 SDK

包的主要入口面向 MCP 使用；SDK 是附带能力，目前只承诺顶层入口和 MCP server 入口：

import { TowngasClient } from "towngas-client";
import { createTowngasMcpServer } from "towngas-client/mcp-server";

基础客户端示例：

import { TowngasClient } from "towngas-client";

const client = new TowngasClient({
  host: process.env.TOWNGAS_HOST,
  orgCode: process.env.TOWNGAS_ORG_CODE,
  subsCode: process.env.TOWNGAS_SUBS_CODE,
  refreshToken: process.env.TOWNGAS_REFRESH_TOKEN
});

const accounts = await client.getBoundAccounts();
const bills = await client.getBills({ pageIndex: 1, pageSize: 10 });
const readings = await client.getLastReadings();
const router = await client.checkRouters({ scene: "2003" });

已封装方法：

协议行为

• 登录后接口按网页版规则构造请求。
• 请求 URL 会附带 seq，格式为 接口编码 + YYYYMMDDHHmmss + 13 位递增序号。
• 登录后接口使用 token=<access_token>。
• resultCode 为 0 表示成功。
• resultCode 为 40058 或 20001 会触发一次 refresh token 刷新并重试。
• resultCode 为 40162 或 40163 会标记为验证码类错误。
• OAuth invalid_grant 会抛出 TowngasAuthError，通常表示 refresh token 已过期或被撤销。