ABS Data (observed)

ABS Data API — カートグラフィーとフロントドア

このプロジェクトでは、オーストラリア統計局の Data API が実際に提供するデータを、取得ごとにすべてのデータフローについて計測し、その結果を型付きのフロントドアとして公開しています。存在するものだけを提供する MCP サーバーと HTTP API です。

フロントドア	https://abs-data-front-door.aicolab.workers.dev
claude.ai／任意の MCP クライアントにコネクターとして追加	https://abs-data-front-door.aicolab.workers.dev/mcp（レジストリ名 io.github.AI-CoLab/abs-data）
MCP（2026-07-28、ステートレス）— 4つの固定動詞＋Code Mode search／execute、リソース、プロンプト	https://abs-data-front-door.aicolab.workers.dev/mcp
RPC ドア（Cap'n Web、@abs/sdk が使用するもの — HTTP バッチまたは WebSocket）	https://abs-data-front-door.aicolab.workers.dev/rpc
HTTP API	https://abs-data-front-door.aicolab.workers.dev/api/tables
Scalar リファレンス	https://abs-data-front-door.aicolab.workers.dev/api/docs
修正版 OpenAPI	https://abs-data-front-door.aicolab.workers.dev/api/openapi.json
メニューを1つのドキュメントにまとめたもの	https://abs-data-front-door.aicolab.workers.dev/api/catalogue.json
ライブで閲覧できるカタログ	https://abs-data-front-door.aicolab.workers.dev/catalogue
静的スナップショット（claude.ai の成果物）	https://claude.ai/code/artifact/d0635dee-5cce-40dd-bfa2-7ab7dd03e5bd

調査結果

• 1,227のデータフローにわたり、621,536,714件の系列が存在します。ABS のメタデータが示す数は14,761,557,818件で、密度は4.21%、23.8倍の過大評価です。
• ディメンションごとのメタデータは正確です。示されている選択肢はすべて存在し、実在する選択肢が漏れていることもありません。過大評価の原因はすべて組み合わせにあります。
• 系列の**81.0%**は、疎性が原則に基づいており、キーで検証できるフローにあります。ほぼすべてが、別々のディメンションとして表現された階層的な地理情報です（664のフローでSTATEはREGIONの関数です）。残りの19%は、単一ディメンションの依存関係には還元できません。
• detail=serieskeysonly — 「何が存在するか」に答えるべきエンドポイント — は壊れています（HTTP 200、JSON の形式不正）。ドキュメントに記載された15の動作のうち8つが仕様に適合していません。reports/を参照してください。

DESIGN.mdには、検証済みの API 調査結果、すべての判断とその理由、そして過程で行った修正がすべて記録されています。

構成

packages/schema      Drizzle schema (declared vs observed, never joined), shared CSV/period parsing
packages/crawler     structural crawl, observed probe, conformance suite, sizing
packages/catalogue   delta report, sparsity analysis, contract generator, OpenAPI emitter, artifact
packages/contract    the corrected contract: stable Zod verbs + generated tables/options (per crawl)
packages/worker      the front door: MCP door (SDK v2) + HTTP door (oRPC + Scalar) + RPC door (Cap'n Web) on one Worker
packages/sdk         @abs/sdk — typed TypeScript client over the RPC door (connect(), invalidSelectionFromError())
reports/             delta.md/json, sparsity.md/json, openapi.json, abs-report-draft.md
data/                local SQLite catalogue (~400GB), raw archive, D1 import SQL — not committed

実行方法

pnpm install
pnpm db:migrate                       # local SQLite at data/abs-catalogue.sqlite

pnpm crawl:structural                 # 7 bulk requests, ~1 minute
pnpm crawl:probe -- '--key-values=*'  # every dataflow by retrieval; ~24h, 20GB heap for the giants
pnpm report:delta && pnpm report:sparsity
pnpm generate:contract                # -> packages/contract/src/generated, data/d1/*.sql
pnpm --filter @abs/catalogue emit:openapi

cd packages/worker
npx wrangler d1 execute abs-catalogue --local --file=../../data/d1/00-schema.sql   # then each data file
npx wrangler dev
ABS_MCP_URL=http://localhost:8787/mcp npx tsx test/protocol.ts                     # ~50 checks, all doors
pnpm --filter @abs/sdk example                                                     # the SDK against production
ABS_URL=http://localhost:8787 npx tsx test/limits.ts                               # rate limits (spends a minute's budget)

クライアントアドレスごとのレート制限：全体で毎分600リクエスト、データ取得は毎分120リクエスト（各リクエストで ABS にライブコールします）、Code Mode のexecuteは毎分20リクエストです。制限を超えると、HTTP ドアはRetry-Afterとともに429を返し、MCP ツール呼び出しはツールエラーになります。

TypeScript から SDK を使用する場合：

import { connect, invalidSelectionFromError } from "@abs/sdk";

const abs = connect(); // https://abs-data-front-door.aicolab.workers.dev/rpc
const [hits, cpi] = await Promise.all([          // one HTTP batch
  abs.searchTables({ query: "cpi rent", limit: 3 }),
  abs.describeTable("CPI"),
]);
try {
  const data = await abs.getData({ table: "CPI", select: { REGION: "Sydney", INDEX: "10001" }, lastN: 4 });
} catch (err) {
  const invalid = invalidSelectionFromError(err); // typed: reason, dimension, validOptions from observation
}

プローブは再開可能です。再実行すると、完了済みとして記録されたフローはスキップされます。最大規模の国勢調査フローを実行する場合は、NODE_OPTIONS=--max-old-space-size=20480を指定してください。

注意点：wrangler は、ローカルの D1 状態をdatabase_idで識別します。wrangler.toml内の ID を変更すると（たとえばd1 createの実行後）、wrangler devは新しく空のローカルデータベースを使用します。その場合は、ローカルへのインポートを再実行してください。

原則

• 観測済みのデータのみ。 宣言されたメタデータはクローラーを制御し、欠陥レポートに反映されますが、呼び出し元に見えるデータには含まれません。利用可能性は実測に基づきます。カタログの観測済み選択肢を使用し、組み合わせは ABS のavailableconstraintに対してライブで正確に検証します（すべてのフローのすべてのディメンションで、プローブの結果と一致します）。
• 単一の契約からドアを生成。 クロールのたびに1つの契約を再生成します。MCP の動詞、HTTP ルート、OpenAPI ドキュメント、ドキュメント類はすべて、それを参照またはレンダリングします。インターフェースをハードコードしないため、ずれも発生しません。
• データを返す呼び出しのみ。 選択内容は転送前に検証されます。無効な選択に対しては、観測済みの有効な選択肢が返されます。MCP では MRTR のinput_requiredとして、HTTP では型付きの422として返されます。