openfda AGENTS.md

AGENTS.md

This file provides guidance for agentic coding assistants (e.g., Claude Code, Copilot) working in this repository.

Project Overview

This is a Model Context Protocol (MCP) server that provides tools for querying drug information from the OpenFDA API. The server communicates over stdio and requires an OPENFDA_API_KEY environment variable.

Build / Lint / Test Commands

# Build
npm run build        # Compile TypeScript to dist/ (Vite build)
npm run build:cli    # Build + add shebang for CLI executable

# Development
npm run dev          # Start development server with Vite

# Testing
npm run test         # Run Vitest tests (watch mode)
npm run test:ci      # Run tests in CI mode (no watch)

# Single test file
npx vitest run tests/ApiHandler.test.ts

# Quality checks
npm run lint         # ESLint with Prettier
npm run lint -- --fix  # Auto-fix linting issues
npm run typecheck    # TypeScript type checking (tsc --noEmit)

Code Style Guidelines

File Headers

Every .ts file must include the MIT license header:

/*
 * Copyright (c) 2025 Ythalo Saldanha
 * Licensed under the MIT License
 */

Imports

• Use ES modules with .js extension in imports (required for bundled output)
• Use import { thing } from './module.js' not import * as thing
• Group imports: external packages first, then internal modules

Formatting

• Run npm run lint -- --fix before committing (Prettier + ESLint)
• Windows users: Ensure line endings are LF, not CRLF, before committing
• The ESLint config ignores tests/, dist/, bin/, and node_modules/

TypeScript

• Strict mode is enabled ("strict": true in tsconfig.json)
• Avoid any unless absolutely necessary (ESLint rule is off but discouraged)
• Use explicit return types on public functions
• Use interfaces for API response shapes (see src/types.ts)

Naming Conventions

• Files: kebab-case (openfda-builder.ts)
• Classes: PascalCase (OpenFDABuilder)
• Functions/variables: camelCase (makeOpenFDARequest)
• Constants: UPPER_SNAKE_CASE for true constants
• Types/interfaces: PascalCase (OpenFDAResponse)