pinelabs-online-mcp: Instructions file for Codex

Agent Instructions

This file provides instructions for AI coding agents working on this repository.

Project Overview

This is a Python MCP (Model Context Protocol) server that wraps Pine Labs payment APIs. It uses FastMCP for the MCP protocol, httpx for async HTTP, and Pydantic for request/response validation. Transport is stdio-only (no HTTP server).

Directory Layout

cli/pinelabs_mcp_server/     # CLI entry point (argparse + stdio runner)
pkg/
  log/                       # Logging setup (LogConfig, setup_logging)
  observability/              # Observability stubs
  toolsets/                   # Toolset/ToolsetGroup for read/write grouping
  pinelabs/
    client.py                 # PineLabsClient — async httpx + in-memory token cache
    config.py                 # Settings from env vars / CLI overrides
    server.py                 # MCP server factory (new_pinelabs_mcp_server)
    tools.py                  # Central tool registration (register_all_tools)
    models/                   # Pydantic request/response models
    utils/                    # Shared validators, errors, API docs config
    *.py                      # One file per resource (payment_links, orders, …)
tests/                        # pytest tests — one test file per source module

Key Commands

make test       # Run all tests (pytest)
make fmt        # Format code (ruff format)
make lint       # Lint code (ruff check)
make build      # Build Docker image
make local-run  # Run locally via stdio
make clean      # Remove __pycache__ and caches

Quick Start

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python -m cli.pinelabs_mcp_server.main stdio \
  --client-id <ID> --client-secret <SECRET> \
  --env uat

Code Conventions

• Python 3.10+ (uses from __future__ import annotations where needed)
• Async-first: all tool handlers and client methods are async
• No Redis, no metrics, no tracing — kept deliberately simple
• In-memory token cache with TTL in PineLabsClient
• Pydantic v2 for all request models
• Error handling: use pkg.pinelabs.utils.errors helpers (error_response, api_error_response, validation_error_response, unexpected_error_response) — they return JSON strings
• Input validation: use validate_resource_id() and validate_path_param() from pkg.pinelabs.utils.validators
• Imports: stdlib → third-party → pkg.* (local), separated by blank lines