Skip to content

CLAUDE.md

Latest commit

 

History

History
156 lines (120 loc) · 4.1 KB

CLAUDE.md

File metadata and controls

156 lines (120 loc) · 4.1 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Turborepo monorepo containing TypeScript SDKs and MCP (Model Context Protocol) servers for major U.S. federal legal and regulatory APIs. The project uses Bun as the primary runtime and package manager.

Key Commands

Development

# Install dependencies
bun install

# Generate all SDKs from OpenAPI specs
turbo generate

# Build all packages
turbo build

# Run tests
turbo test

# Run integration tests
turbo test:integration

# Run e2e tests
turbo test:e2e

# Format and lint code
turbo format
turbo lint
turbo check

Package-Specific Commands

# Work on a specific package
cd packages/[package-name]

# Run MCP server
bun run mcp:server

# Run development server
bun run dev

# Run tests for specific package
bun test
bun test:watch

Single Test Execution

# Run a specific test file
bun test src/api/client.test.ts

# Run tests matching a pattern
bun test --filter="search"

# Run with specific environment
SKIP_INTEGRATION_TESTS=false bun test src

Architecture

Monorepo Structure

  • Root: Turborepo configuration with shared dependencies
  • packages/: Individual SDK packages
    • ecfr-sdk: Electronic Code of Federal Regulations
    • federal-register-sdk: Federal Register documents
    • courtlistener-sdk: Court cases and legal data
    • govinfo-sdk: Government Publishing Office data
    • dol-sdk: Department of Labor statistics
    • scalar-ui: API documentation UI

Package Architecture

Each SDK package follows a consistent structure:

  1. API Client (src/api/): Generated TypeScript client from OpenAPI spec
  2. MCP Server (src/mcp/): Model Context Protocol implementation for AI integration
  3. Build System: Uses Orval for code generation from OpenAPI specs
  4. Testing: Unit, integration, and e2e test suites

Code Generation Flow

  1. OpenAPI specs are downloaded/maintained in each package
  2. Orval generates TypeScript clients and types
  3. MCP handlers are manually maintained to wrap the generated API clients
  4. Build process creates both CommonJS and ESM outputs

Important Patterns

API Client Usage

import { getApiSearchV1Results } from '@beshkenadze/us-legal-tools';

// Direct function calls with typed parameters
const results = await getApiSearchV1Results({
  q: 'search term',
  per_page: 10
});

MCP Server Implementation

  • Each SDK includes an MCP server for AI assistant integration
  • Servers expose API functionality as structured tools
  • Authentication handled via environment variables when required

Testing Strategy

  • Unit tests: Test individual functions and components
  • Integration tests: Test API client with real endpoints (controlled by SKIP_INTEGRATION_TESTS)
  • E2E tests: Full workflow testing including MCP servers (controlled by SKIP_E2E_TESTS)

CI/CD Pipeline

GitHub Actions Workflows

  • CI: Runs on all PRs and main branch pushes

    • Generates SDKs
    • Runs format and lint checks
    • Builds all packages
    • Runs all test suites
    • Verifies MCP servers work

  • Release: Triggered by version tags (v*)

    • Downloads latest OpenAPI specs
    • Generates fresh SDK code
    • Publishes to npm and GitHub Packages

Release Process

# Update version
bun version patch/minor/major

# This automatically:
# - Updates package.json version
# - Creates git commit and tag
# - Pushes to trigger release workflow

Development Guidelines

Code Style

  • Biome for formatting and linting
  • TypeScript with strict mode
  • Import/export type annotations required
  • Generated code is excluded from linting

Environment Variables

  • GOV_INFO_API_KEY: Required for GovInfo SDK
  • DOL_API_KEY: Required for DOL SDK
  • COURTLISTENER_API_TOKEN: Required for CourtListener SDK
  • No auth required for eCFR and Federal Register APIs

Working with Generated Code

  • Never manually edit files in generated/ directories
  • Never edit MCP handler files marked with "Generated by" headers
  • To modify SDK behavior, update Orval configs or create wrapper functions