fdic-mcp-server: Instructions file for Codex

AGENTS.md

Canonical repository instructions for LLM agents working in this repo. Keep repo-specific guidance here and use thin pointer files for agent-specific entrypoints.

Purpose

This repository implements an MCP server for the FDIC BankFind Suite API. The codebase wraps FDIC datasets as MCP tools and includes server-side analysis helpers for multi-bank comparisons.

Primary references:

• README.md
• docs/clients.md

Core Commands

Install dependencies:

npm install

Validate changes:

npm run typecheck
npm test
npm run build

Run locally over stdio:

node dist/index.js

Run locally over HTTP:

TRANSPORT=http PORT=3000 node dist/index.js

Working Norms

• Prefer using the MCP server tool implementations in src/tools rather than bypassing them with ad hoc FDIC API logic when validating server behavior.
• Preserve tool contracts. Changes to tool names, argument shapes, content, or structuredContent should be treated as breaking unless intentionally coordinated.
• Keep changes small and explicit. Add or update tests whenever tool behavior, output structure, filtering, ranking, or error handling changes.
• Do not add secrets or API keys. The FDIC BankFind API is public and this server should work without credentials.
• Prefer the simplest change that solves the real problem. Avoid speculative refactors and temporary fixes.
• Find root causes. Do not stop at symptom treatment if the underlying defect is identifiable.

Workflow Orchestration

• Enter plan mode for non-trivial tasks, especially work with multiple implementation steps, verification steps, or architectural choices.
• If execution goes sideways, stop and re-plan instead of pushing through a weak plan.
• For non-trivial work, write a detailed spec up front to reduce ambiguity before editing.
• Use parallel exploration where tooling allows it to keep the main execution path focused.
• For larger problems, break work into focused tracks rather than mixing research, implementation, and verification in one pass.
• Prompt macros for label-driven orchestration:
  • If the user says /issue-batch <label> or issue-batch <label>, treat that as an instruction to run npm run issues:batch -- --label <label>, review the generated batches, and use the brief as the planning input for the next implementation steps.
  • If the user says /issue-batch-run <label> or issue-batch-run <label>, first run npm run issues:batch -- --label <label>, then execute the recommended batches one at a time using the document agent working norms in this file. That means restating acceptance criteria, refreshing from main, creating a dedicated branch per coherent batch, updating tasks/todo.md for non-trivial work, implementing root-cause fixes with tests, validating, opening a PR, watching checks, merging when green, and only then moving to the next batch unless the user explicitly asks to pause.