xe-mcp: Instructions file for Claude Code

xe-mcp — Claude Code Instructions

What this project is

An MCP server for the Xe Currency Data API. Eleven tools spanning rate lookup, conversion, historical analysis, volatility, moving averages, correlation, alert checking, and charting. Falls back to Frankfurter (ECB) when Xe credentials aren't set.

Build and test

npm install            # install deps
npm run build          # compile TypeScript → dist/ (MCP server)
npm run build:lambda   # compile → dist-lambda/ (Lambda handlers)
npm run build:all      # compile both
npm test               # run Jest unit tests (49 tests, 5 suites)
bash scripts/smoke-test.sh  # 12/12 live tool smoke test (requires npm run build first)

Build must pass before any commit. Tests must pass before any PR.

Architecture

src/
├── index.ts              # MCP server entry — 12 tools, stdio transport
├── xe-client.ts          # Xe XECD API wrapper (auth: HTTP Basic)
├── frankfurter-client.ts # ECB fallback (free, no auth)
├── s3-cache.ts           # S3-backed rate history cache (Lambda use)
└── tools/
    ├── rates.ts          # get_rate, convert, list_currencies
    ├── analysis.ts       # get_historical_rates, volatility_analysis, optimal_send_window, moving_average
    ├── nzd.ts            # nzd_corridors
    ├── correlation.ts    # correlation_analysis
    ├── alerts.ts         # rate_alert_check
    └── chart.ts          # rate_chart

lambda/
├── handler.ts            # REST API — all 12 tools via POST /tool/{name}
├── alert-scheduler.ts    # CloudWatch hourly → DynamoDB → SQS
└── alert-processor.ts    # SQS consumer → SES email

Adding a new tool

1. Create src/tools/your-tool.ts with a tool definition object and handler function
2. Import and register both in src/index.ts (tools list + switch case)
3. Also register in lambda/handler.ts switch statement
4. Write tests in src/__tests__/your-tool.test.ts covering the math or logic
5. Add the tool to scripts/smoke-test.sh
6. Rebuild and run tests before committing