porkbun-mcp: Instructions file for Codex

porkbun-mcp - Agent Guidelines

MCP server for Porkbun DNS API. Python 3.14+, FastMCP 2.14+, async-first via oinker.

Quick Reference

# Install dependencies
uv sync --dev

# Run all checks (lint, format, typecheck, test)
make check

# Individual commands
make lint          # ruff check .
make format        # ruff format .
make typecheck     # ty check
make test          # pytest with coverage

# Run single test file
uv run pytest tests/test_dns_tools.py

# Run single test by name
uv run pytest -k "test_dns_list"

# Fix lint issues automatically
make fix

# Run the MCP server
uv run porkbun-mcp
uv run porkbun-mcp --transport sse    # SSE transport

Project Structure

src/porkbun_mcp/
├── __init__.py           # Public API + main() entry point
├── server.py             # FastMCP server setup + lifespan
├── config.py             # PorkbunMCPSettings (pydantic-settings)
├── models.py             # Pydantic response models (output schemas)
├── errors.py             # Oinker -> MCP error mapping
└── tools/
    ├── __init__.py       # register_tools()
    ├── ping.py           # ping tool
    ├── dns.py            # DNS record tools (list, get, create, edit, delete)
    ├── domains.py        # Domain management tools
    ├── dnssec.py         # DNSSEC tools
    ├── ssl.py            # SSL certificate tools
    └── pricing.py        # TLD pricing tool

Code Style

General Principles

• Async-first: All tools and resources are async functions
• Pydantic models: Response models for strict output schemas
• Type hints everywhere: Full type annotations with Annotated[type, Field(...)]
• Single-purpose functions: Small, focused, testable

Imports

from __future__ import annotations  # Always first

from typing import TYPE_CHECKING, Annotated

from fastmcp import Context, FastMCP
from fastmcp.exceptions import ToolError
from pydantic import BaseModel, Field

from porkbun_mcp.config import PorkbunMCPSettings
from porkbun_mcp.errors import handle_oinker_error
from porkbun_mcp.models import DNSRecord

if TYPE_CHECKING:
    from oinker import AsyncPiglet