mcp-ezpay-einvoice: Instructions file for Claude Code

mcp-ezpay-einvoice

Overview

MCP server for Taiwan's ezPay e-invoice API. Exposes 7 AI-callable tools covering the full invoice lifecycle (issue, trigger, void) and allowance lifecycle (issue, trigger, void), plus querying. Uses AES-256-CBC encryption for the ezPay form POST protocol.

Setup

uv venv && source .venv/bin/activate
uv pip install -e .
cp .env.example .env
# Set EZPAY_MERCHANT_ID, EZPAY_HASH_KEY, EZPAY_HASH_IV in .env

Run

python mcp_server.py

Test

# Validate credentials and connectivity
python scripts/auth/test_connection.py

# Run all 7 tool E2E tests
python tests/test_all_tools.py

Architecture

stdio (JSON-RPC 2.0)
  -> mcp_server.py (entry point, imports tools/invoice_tools.py to trigger registration)
    -> app.py (FastMCP("mcp-ezpay-einvoice") singleton)
      -> tools/invoice_tools.py (7 @mcp.tool() decorated functions)
        -> connectors/ezpay_client.py (encrypted form POST: inject fields, AES encrypt, HTTP POST)
          -> auth/ezpay_crypto.py (AES-256-CBC encrypt, PKCS7 pad, CheckCode SHA-256)
            -> config/settings.py (endpoints, URL builder, env var credentials)

Key Patterns

• Singleton: app.py creates the FastMCP instance, imported by tools and server
• Decorator registration: @mcp.tool() with Pydantic Field() for typed parameters
• Side-effect import: mcp_server.py imports tools.invoice_tools to trigger registration
• Encrypted protocol: All API params are URL-encoded, PKCS7-padded, AES-256-CBC encrypted, hex-encoded
• Dual environment: EZPAY_IS_PRODUCTION switches between test and production base URLs

Adding a New Tool

1. Add the function in tools/invoice_tools.py (or create a new tools/*_tools.py module)
2. Use the connector: from connectors.ezpay_client import ezpay_post
3. Decorate with @mcp.tool() and use Field() for parameter descriptions
4. If new module, add import tools.{module} # noqa: F401 in mcp_server.py
5. Add a test case in tests/test_all_tools.py