spreedly-mcp: Instructions file for Codex

Spreedly MCP -- Developer Agent Reference

This document is for AI coding agents that work on the Spreedly MCP codebase itself. If you are an agent using the MCP tools to process payments, your guidance comes from the server's instructions field delivered during the MCP initialize handshake (source: src/instructions.ts).

Project Overview

This is an MCP (Model Context Protocol) server that exposes the Spreedly payments API as tools for AI agents. It runs over stdio and is distributed as an npm package.

Architecture

Source Layout

src/
├── bin.ts                 # CLI entry point (reads env vars, starts stdio server)
├── server.ts              # MCP server creation, tool registration, passes instructions
├── instructions.ts        # SERVER_INSTRUCTIONS constant -- agent-facing guidance delivered via MCP
├── domains/               # One folder per Spreedly API domain
│   ├── index.ts           # Aggregates allTools from every domain
│   ├── gateways/          # tools.ts, schemas.ts
│   ├── transactions/
│   ├── paymentMethods/
│   ├── certificates/
│   ├── environments/
│   ├── merchantProfiles/
│   ├── subMerchants/
│   ├── events/
│   ├── protection/
│   ├── sca/
│   ├── cardRefresher/
│   └── networkTokenization/
├── security/
│   ├── descriptions.ts    # Per-tool description strings (behavioral guidance lives here)
│   ├── toolPolicy.ts      # Tool categories, access control, CATEGORY_GUIDANCE tags
│   ├── middleware.ts       # wrapHandler -- validation, error formatting, audit logging
│   ├── sanitizer.ts       # Input sanitization
│   └── audit-logger.ts    # Audit logging
├── transport/             # HTTP transport abstraction for the Spreedly API
│   ├── SpreedlyHttpTransport.ts
│   ├── types.ts
│   └── errors.ts
└── types/
    └── shared.ts          # ToolDefinition interface (name, description, schema, annotations, handler, parseError)

Key Patterns

ToolDefinition (src/types/shared.ts): Every tool is a plain object with name, description, schema (Zod), annotations (MCP ToolAnnotations), a handler function, and an optional parseError hook. Tools are collected in src/domains/index.ts as allTools. The parseError hook lets a tool override how SpreedlyError responses are extracted into structured agent-facing output; when omitted, the default parser extracts fieldErrors, transactionToken, and retryAfterMs from typed error subclass properties.