mcp: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents working on this project.

Project Overview

A Model Context Protocol (MCP) server in TypeScript that wraps the PEX Card External API as 72 read-only tools. Runs as a stdio-based process using @modelcontextprotocol/sdk. Read-only by design — only GET endpoints are exposed.

Build & Run

npm ci                # install dependencies
npm run build         # compile TypeScript (tsc → dist/)
npm run dev           # run in development mode (tsx, no build needed)
npm start             # run compiled output (dist/index.js)
npm audit --audit-level=high  # check for vulnerabilities

There are no tests yet. Do not add a npm test step to scripts without being asked.

Project Structure

src/
├── index.ts              # Entry point: creates server, registers tools, connects transport
├── pex-client.ts         # HTTP client (GET-only, retry, error handling)
├── logger.ts             # JSON structured logger (writes to stderr only)
├── types.ts              # Shared type: ToolRegistrar
└── tools/
    ├── index.ts           # Aggregator — calls all register() functions
    ├── utils.ts           # toolResponse, toolError, paginateArray, paginateNestedArray, readOnlyAnnotations
    ├── business.ts        # 12 tools
    ├── card.ts            # 7 tools
    ├── transactions.ts    # 10 tools
    ├── details.ts         # 10 tools
    ├── spending-ruleset.ts # 7 tools
    ├── bill.ts            # 4 tools
    ├── vendor.ts          # 2 tools
    ├── vendor-card.ts     # 1 tool
    ├── payment.ts         # 3 tools
    ├── credit.ts          # 4 tools
    ├── group.ts           # 2 tools
    ├── token.ts           # 3 tools
    ├── token-provisioning.ts # 3 tools
    ├── callback.ts        # 3 tools
    └── partner.ts         # 1 tool

Architecture

Entry point (src/index.ts): Creates McpServer, instantiates PexClient, calls registerAllTools(), and connects via StdioServerTransport. All logging goes to stderr to keep stdout clean for MCP protocol.