capture-mcp-server: Instructions file for Claude Code

CLAUDE.md

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

Development Commands

Building and Running

• npm run build - Compiles TypeScript to dist/ directory
• npm start - Runs the compiled server (requires build first)
• npm run dev - Development mode with ts-node (auto-reload with nodemon)

Project Configuration

• Uses ES modules ("type": "module" in package.json)
• TypeScript compilation target: ES2020
• Output directory: dist/
• Source directory: src/

Architecture Overview

This is a Model Context Protocol (MCP) server that captures federal procurement and spending data through 34 specialized tools. The architecture follows a modular tool-based design:

Core Components

Server (src/server.ts)

• MCP server using @modelcontextprotocol/sdk
• Uses stdio transport for Claude Desktop integration
• Handles tool registration and execution through centralized registry

Tool Architecture (src/tools/)

• Modular tool system with six categories:
  • reference-tools.ts - 1 static FPDS reference tool (lookup_reference_code; no key, no network)
  • sam-tools.ts - 4 SAM.gov API tools (entities, opportunities, details, exclusions)
  • usaspending-tools.ts - 6 USASpending.gov API tools (awards, spending, budgets, recipient search, get_award_detail verification, aggregate_contracts grouping)
  • tango-tools.ts - 12 Tango API tools (contracts, grants, vendor profiles, opportunities, spending summaries, GAO protests + detail, IDVs + child/task-order drill-down, vehicle catalog, OTAs, entity time-series metrics). Set-aside filtering is exact on FPDS codes; cursor pagination via the Tango next URL.
  • highergov-tools.ts - 9 HigherGov tools (forecast/opportunity/contract/people search, saved-search listing, opportunity documents, single-record lookups). Responses are normalized to lowercase agency/vehicle/set-aside slugs via utils/highergov-slugs.ts. get_* tools cache for 15 min in an in-process LRU.
  • join-tools.ts - 2 cross-API tools (entity+awards, opportunity+context)
• Response conventions (see utils/envelope.ts and docs/fix-plan.md): every list tool echoes filters.upstream vs filters.client_side, nulls untrustworthy totals (total_upstream_unfiltered / total_upstream_unverified + warnings), labels count_unit and date_field, and returns one next_cursor shape. tools/index.ts rejects unknown/mistyped parameters with a structured bad_request. utils/fpds-codes.ts is the FPDS code table; docs/upstream-api-notes.md records which upstream params are verified to bind (run npm run capture-fixtures with live keys to re-probe).
• Each tool module exports getTools() and callTool() methods
• Central registry in tools/index.ts manages all tool registration