nankai-trough-mcp: Instructions file for Codex

AGENTS.md: nankai-trough-mcp

Guide for AI coding agents (Claude Code, Cursor, Codex, Copilot…) working in this repo.

What this project is

nankai-trough-mcp is an MCP server that surfaces official Japanese government data on the Nankai Trough (南海トラフ地震) earthquake hazard and Japanese building seismic standards, so an AI assistant can answer "how bad is it, how far does it reach, and what does my build year mean?" with cited figures instead of guesses. It never returns a safety verdict.

• npm: nankai-trough-mcp · registry name: io.github.mrslbt/nankai-trough
• Local stdio server, read-only, bundled data + one official geocoder call, no API keys.
• Six tools, two prompts, four resources. Entry tool: nankai_overview (scale and reach); official_hazard_maps bridges to the official per-address maps.

Quick commands

npm install        # deps
npm run build      # tsc → dist/   (must pass before commit)
npm test           # build + node --test test/*.test.mjs   (must pass before commit)
npm run smoke      # build + a live MCP round-trip (lists tools + resources, classifies a 1975 wooden house)
npm run dev        # tsc --watch

Pre-commit: npm run build && npm test. Both must pass. 11 tests today.

Architecture (the whole mental model)

src/
├── index.ts            # McpServer, registers the 6 tools + 2 prompts + 4 resources + server instructions (the no-verdict rules)
├── meta.ts             # READONLY / READONLY_EXTERNAL annotations
├── resources.ts        # RESOURCES, reference docs rendered FROM the data below (no second copy, no drift)
├── data/
│   ├── nankai.ts       # NANKAI_FACTS, the headline figures, each with source + as-of + a VERIFICATION LOG header
│   ├── building.ts     # classifyEra(year, structure); ERA_INFO; KUMAMOTO_WOOD field data
│   ├── shindo.ts       # JMA 震度 5弱–7 meanings
│   ├── subsidy.ts      # 耐震診断/補強 routing (never quotes an amount; varies by municipality)
│   └── sources.ts      # SOURCES, DISCLAIMER, ATTRIBUTION: single source of truth, every figure traces here
└── lib/
    ├── geocode.ts      # GSI geocoder + parsePrefMuni() (pure, tested)
    ├── maps.ts         # hazardMapLinks(), pure builder for the official per-address map URLs (tested)
    ├── fetch.ts        # safeFetch (hard timeout, UA, throws on non-OK)
    └── cache.ts        # getOrFetch + TTL