godaddy-dns-mcp: Instructions file for Codex

AGENTS.md

Node.js/TypeScript MCP server for managing GoDaddy DNS records. Published to npm as @appouse/godaddy-dns-mcp; the binary is godaddy-dns-mcp.

Setup

Requires Node.js >= 18.17.

npm install

Executable Commands

npm run typecheck   # tsc --noEmit over src/ and test/
npm test            # vitest run (all HTTP is stubbed)
npm run build       # tsc -p tsconfig.build.json -> dist/
npm run dev         # tsx src/cli.ts (stdio server, from source)

Folder Structure

godaddy-dns-mcp/
├── src/
│   ├── cli.ts        # bin entry — stdio transport, --help/--version
│   ├── index.ts      # library exports
│   ├── server.ts     # MCP tool registration (McpServer)
│   ├── dns.ts        # DNS operations, one per tool
│   ├── godaddy.ts    # GoDaddy API client (fetch, auth, errors)
│   ├── validate.ts   # input validation for values used in URL paths
│   └── version.ts    # VERSION + SERVER_NAME
├── test/             # vitest: unit, MCP in-memory, built-CLI e2e
├── tsconfig.json     # typecheck (src + test)
└── tsconfig.build.json

Available Tools

• list_dns_records — list records, optional type/name filter (returns structured content)
• add_dns_record — PATCH, adds without overwriting
• replace_dns_records — PUT, overwrites all records of a type+name; supports dry_run
• delete_dns_record — DELETE all records of a type+name; supports dry_run
• check_domain_availability — availability + price (returns structured content)

Tool and argument names are snake_case — this is the published contract, so renaming one is a breaking change.

Conventions

• ESM only ("type": "module"), moduleResolution: NodeNext — all relative imports need a .js extension, including in .ts files.
• VERSION in src/version.ts must match package.json; a test enforces this. Bump both together.
• Anything interpolated into a request path goes through src/validate.ts first.
• Tool handlers catch their own errors and return { isError: true } rather than throwing.