opendata-mcp: Instructions file for Codex

AGENTS.md — working rules for this repo

Read this together with docs/ARCHITECTURE.md before starting any session. This file is the enforceable checklist; the architecture doc is the reasoning behind it. Where they disagree, the architecture doc's principles win but this file's interfaces are what the code actually implements (see the deviations noted below — they're intentional and this file documents the canonical, as-built interface).

1. Directory structure

src/
  index.ts        # Worker entry point, MCP server assembly, routing — no fetch/parsing logic
  tools/          # One file per curated tool. Thin: cache -> envelope -> MCP result.
  registry/       # One DatasetEntry per dataset, grouped by source (cwa.ts, moenv.ts, ...)
  adapters/       # One file per upstream source: auth, URL assembly, envelope unwrapping
  infra/          # http.ts, cache.ts, envelope.ts, errors.ts — no CWA/MOENV-specific code
test/             # Mirrors src/'s layout (test/adapters/, test/registry/, test/tools/, test/infra/)
  fixtures/       # Real captured response samples (see §5)
docs/
  ARCHITECTURE.md
  adr/            # ADR-NNN-slug.md, numbered sequentially
AGENTS.md         # this file

Layer responsibilities (see ADR-001 for why):

• infra/ never imports from adapters/, registry/, or tools/.
• adapters/ never does dataset-specific filtering/shaping — only auth injection, URL building, timeout+retry (via infra/http.ts), and unwrapping that source's response envelope into "raw JSON". Missing-value normalization that's a source quirk (like MOENV's "" / "-" / "ND") belongs here, generically, not per-dataset.
• registry/ entries do the dataset-specific shaping (transform) and own the Zod param schema. No fetch calls here.
• tools/ compose cache + envelope on top of a registry entry's adapter+transform. No parsing logic here.

2. Core interfaces (as-built, not the doc's literal draft)

// registry/index.ts
export interface DatasetEntry<TParams, TRaw, TResult> {
  id: string;                    // "cwa:F-C0032-001"
  source: "cwa" | "moenv";       // add sources here as adapters are added
  path: string;                  // upstream dataset id/path, used to build the URL
  title: string;
  keywords: string[];            // for the future tw_search_datasets
  paramsSchema: Record<string, ZodTypeAny>;  // Zod raw shape — reused directly as the MCP tool's inputSchema
  buildQueryParams: (params: TParams) => Record<string, string | undefined>;
  transform: (raw: TRaw, params: TParams) => TResult;
  cacheTtlSeconds: number;
  updateFrequency: string;       // human-readable, surfaced in the response envelope
  docUrl: string;
  notes?: string;
}

// adapters/types.ts
export interface SourceAdapter {
  id: "cwa" | "moenv";
  displayName: string;           // "中央氣象署" etc, used as the envelope's `source`
  fetchDataset<TParams, TRaw>(
    entry: DatasetEntry<TParams, TRaw, unknown>,
    params: TParams,
    env: Env,
    fetchImpl?: typeof fetch     // DI seam for tests, defaults to global fetch
  ): Promise<TRaw>;
}