genomics-mcp: Instructions file for Codex

AGENTS.md — AI Agent Instructions

Project Overview

This is an MCP (Model Context Protocol) server written in TypeScript that exposes genomics SNP data to LLM clients. It is a read-only data service — no mutations, no user accounts, no authentication.

Tech Stack

• Runtime: Bun
• Language: TypeScript (strict mode)
• MCP SDK: @modelcontextprotocol/sdk v1.x — use server.registerTool(name, { inputSchema: Schema.shape }, handler) API
• Validation: Zod 4.x
• Linter/Formatter: Biome (biome.json at project root)
• Build: Bun runs TypeScript directly — tsc is available for type-checking only (tsconfig.json at project root)

Key Architecture Rules

1. stdout is sacred. All log output MUST go to stderr. Use createLogger() from src/utils/logger.ts — never use console.log() or console.error() directly.
2. Repository Pattern. All data access goes through ISnpRepository. Never read JSON files directly in services or tools.
3. Use-case classes. Business logic lives in src/services/*.use-case.ts. The SnpService facade delegates to them. Exception: listTraits() and getMetadata() on SnpService call the repository directly (no use-case class) because they contain no business logic — getMetadata() enriches the repository's getStats() result with the application VERSION.
4. One tool per file. Each MCP tool is defined in src/tools/*.tool.ts. The barrel register-all.ts wires them together.
5. Zod schemas are the source of truth for both runtime validation and TypeScript types (via z.infer).

File Layout

genomics-mcp/
├── package.json                          # Scripts, dependencies (Bun runtime)
├── tsconfig.json                         # Strict mode, noEmit, excludes tests/
├── biome.json                            # Linter + formatter config
├── bun.lock                              # Lockfile
├── AGENTS.md                             # AI agent instructions (this file)
├── README.md                             # Project overview and quick-start
├── LICENSE                               # MIT
│
├── docs/
│   ├── ARCHITECTURE.md                   # Design decisions, data flow, known limitations
│   ├── PROJECT_STATUS.md                 # Health metrics, resolved items, pending features
│   ├── TESTING.md                        # Automated + manual testing guide
│   └── TOOLS.md                          # MCP tool reference (inputs, outputs, examples)
│
├── src/
│   ├── index.ts                          # Entry point — wires server, repository, service, tools
│   ├── constants.ts                      # Shared limits, patterns, defaults
│   │
│   ├── types/                            # TypeScript types (derived from Zod schemas via z.infer)
│   │   ├── common.ts                     # PaginationMetadata, MatchMode, ResponseFormat, RiskLevel, StudyType
│   │   ├── snp.ts                        # SnpRecord, SnpSummary, TraitSummary, DatasetStats, DatasetMetadata, GenotypeInterpretation
│   │   └── trait-categories.ts           # TraitCategory const/type, TRAIT_CATEGORIES slug→category map
│   │
│   ├── schemas/                          # Zod schemas — source of truth for validation and types
│   │   ├── snp.schemas.ts                # Domain schemas — validates seed data on startup
│   │   └── tool-inputs.schemas.ts        # MCP tool input schemas
│   │
│   ├── repositories/                     # Data access layer
│   │   ├── snp.repository.ts             # ISnpRepository interface
│   │   ├── snp.json-repository.ts        # JSON/in-memory implementation
│   │   └── data/
│   │       └── snps.json                 # Seed data (validated by Zod on startup)
│   │
│   ├── services/                         # Business logic
│   │   ├── snp.service.ts                # Facade — delegates to use-case classes
│   │   ├── get-snp-details.use-case.ts
│   │   ├── interpret-genotype.use-case.ts
│   │   └── search-by-trait.use-case.ts
│   │
│   ├── tools/                            # MCP tool registrations (one tool per file)
│   │   ├── register-all.ts               # Barrel — imports and registers all tools
│   │   ├── get-metadata.tool.ts
│   │   ├── get-snp-details.tool.ts
│   │   ├── interpret-genotype.tool.ts
│   │   ├── list-traits.tool.ts
│   │   └── search-by-trait.tool.ts
│   │
│   └── utils/                            # Shared utilities
│       ├── logger.ts                     # Stderr-only logger (stdout is reserved for MCP)
│       ├── genotype.ts                   # Allele normalization (canonical sort)
│       ├── errors.ts                     # Error message helpers
│       └── formatting.ts                 # Markdown/JSON response formatters
│
└── tests/                                # Mirrors src/ — Bun native test runner (bun:test)
    ├── utils/
    │   ├── genotype.test.ts              # normalizeGenotype() — all allele combos, case handling
    │   ├── errors.test.ts                # createSnpNotFoundMessage(), createGenotypeNotFoundMessage()
    │   └── formatting.test.ts            # All 5 formatters, pagination, empty results, truncation
    ├── schemas/
    │   └── snp.schemas.test.ts           # Valid/invalid domain data, canonicalisation transform
    ├── repositories/
    │   └── snp.json-repository.test.ts   # Full repository lifecycle, all query methods, error paths
    ├── services/
    │   ├── mock-repo.ts                  # Shared in-memory ISnpRepository mock + fixture SNPs
    │   ├── snp.service.test.ts
    │   ├── get-snp-details.use-case.test.ts
    │   ├── interpret-genotype.use-case.test.ts
    │   └── search-by-trait.use-case.test.ts
    └── tools/
        ├── fixtures.ts                   # Shared InMemoryTransport + real repo/service/server/client harness
        ├── get-metadata.tool.test.ts
        ├── get-snp-details.tool.test.ts
        ├── interpret-genotype.tool.test.ts
        ├── list-traits.tool.test.ts
        └── search-by-trait.tool.test.ts