refactor: clean v1 tool operations and harden api params

Author: joachimBrindeau

.env.example

@@ -1,20 +1,2 @@
-# Dynadot API Configuration
-# Get your API key at: https://www.dynadot.com/help/question/api-key
-DYNADOT_API_KEY=your-api-key-here
-
-# Optional: Sandbox testing (https://www.dynadot.com/help/question/api-sandbox)
-# Generate sandbox key in Dynadot account > Tools > API > API Sandbox Key
-DYNADOT_SANDBOX=true
-DYNADOT_SANDBOX_KEY=your-sandbox-key-here
-
-# Test domain (replace with an actual domain you own)
-TEST_DOMAIN=example.com
-
-# Target username for domain push operations (another Dynadot account)
-DYNADOT_TARGET_USERNAME=testuser
-
-# Contact ID for WHOIS operations (get from: mcp__dynadot__dynadot_contact({ action: "list" }))
-TEST_CONTACT_ID=1234567
-
-# Folder ID for folder operations (use -1 for root folder)
-TEST_FOLDER_ID=-1
+DYNADOT_API_KEY=your_dynadot_api_key_here
+DYNADOT_SANDBOX=false

README.md

@@ -39,7 +39,7 @@ A Domain MCP server that brings natural language domain management to Claude, Cu
 ## Features
 
 - **🤖 Natural Language Domain Management**: Use AI assistants like Claude and Cursor to manage domains conversationally - no API knowledge needed
-- **📦 Complete Domain MCP Server**: 106 Dynadot API actions across 10 composite MCP tools for domains, DNS, transfers, and more
+- **📦 Complete Domain MCP Server**: 108 Dynadot API actions across 10 composite MCP tools for domains, DNS, transfers, and more
 - **⚡ Production-Ready AI Integration**: Built for Claude Code, Cursor, Claude Desktop, and any MCP-compatible client
 - **🔒 Type-Safe & Reliable**: TypeScript, Zod validation, comprehensive test suite with 100% tool coverage
 - **✅ MCP Protocol Compliant**: Full Model Context Protocol specification compliance with real CRUD operation tests
@@ -364,7 +364,7 @@ npm test
 # Integration tests (requires network access + Dynadot credentials)
 RUN_INTEGRATION_TESTS=true DYNADOT_API_KEY=your-api-key TEST_DOMAIN=your-domain.com npm test
 
-# E2E tests (validates all 106 API endpoints)
+# E2E tests (validates all 108 API endpoints)
 RUN_INTEGRATION_TESTS=true TEST_DOMAIN=your-domain.com npm test -- test/e2e.test.ts
 
 # Functional tests (real CRUD operations)
@@ -383,7 +383,7 @@ npm run dev
 ## Testing
 
 ### E2E Tests
-Validates that all 106 API actions are properly mapped and return valid responses.
+Validates that all 108 API actions are properly mapped and return valid responses.
 
 ### Functional Tests
 Tests real CRUD operations:
@@ -427,10 +427,10 @@ Unlocking domains may need to be done through the Dynadot control panel.
 
 ```
 src/
-├── index.ts       # MCP server entry point
-├── client.ts      # Dynadot API client
-├── schema.ts      # Tool and action definitions (10 tools, 106 actions)
-└── register.ts    # Tool registration with MCP server
+├── index.ts         # MCP server entry point
+├── client.ts        # Dynadot API client
+├── register.ts      # Tool registration with MCP server
+└── schemas/*.ts     # Tool and operation definitions (10 tools, 108 actions)
 
 test/
 ├── e2e.test.ts         # Endpoint validation tests

package.json

@@ -1,7 +1,7 @@
 {
   "name": "domain-mcp",
   "version": "1.1.1",
-  "description": "Domain MCP - AI-powered domain management for Dynadot API. Natural language domain operations via Claude, Cursor, and MCP clients. 106 commands: domain registration, DNS, transfers, WHOIS contacts, aftermarket.",
+  "description": "Domain MCP - AI-powered domain management for Dynadot API. Natural language domain operations via Claude, Cursor, and MCP clients. 108 commands: domain registration, DNS, transfers, WHOIS contacts, aftermarket.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/client.ts

@@ -1,5 +1,7 @@
 import ky, { type KyInstance } from 'ky';
 
+const RESERVED_PARAM_KEYS = new Set(['key', 'command']);
+
 /**
  * Parameters passed to Dynadot API commands.
  * Values can be string, number, boolean, or undefined (undefined values are filtered out).
@@ -123,6 +125,9 @@ export class DynadotClient {
     searchParams.set('command', command);
 
     for (const [key, value] of Object.entries(params)) {
+      if (RESERVED_PARAM_KEYS.has(key)) {
+        throw new Error(`Reserved parameter "${key}" cannot be set by tool input`);
+      }
       if (value !== undefined) {
         searchParams.set(key, String(value));
       }

src/prompts.ts

@@ -41,14 +41,14 @@ export function registerAllPrompts(server: McpServer): void {
             type: 'text',
             text: `Help me configure DNS for ${args.domain}:
 
-1. First, get current DNS records using dynadot_dns with action: get
+1. First, get current DNS records using dynadot_dns with operation: get
 2. Ask me what I want to set up:
    - Website hosting (A/AAAA records)
    - Email (MX records)
    - Domain verification (TXT records)
    - Subdomain (CNAME records)
 3. Guide me through the configuration
-4. Apply changes using dynadot_dns with action: set
+4. Apply changes using dynadot_dns with operation: set
 5. Verify the changes were applied`,
           },
         },

src/register.ts

@@ -12,19 +12,19 @@ import {
 
 export function registerAllTools(server: McpServer): void {
   for (const tool of compositeTools) {
-    // Build action enum from keys
-    const actionKeys = Object.keys(tool.actions) as [string, ...string[]];
+    // Build operation enum from keys
+    const operationKeys = Object.keys(tool.actions) as [string, ...string[]];
 
-    // Build combined input schema with action + all possible params
-    const actionDescriptions = actionKeys
+    // Build combined input schema with operation + all possible params
+    const operationDescriptions = operationKeys
       .map((k) => {
         const actionDef = tool.actions[k];
         return actionDef ? `${k}: ${actionDef.description}` : k;
       })
       .join(' | ');
 
     const inputSchema: Record<string, z.ZodTypeAny> = {
-      action: z.enum(actionKeys).describe(`Action to perform: ${actionDescriptions}`),
+      operation: z.enum(operationKeys).describe(`Operation to perform: ${operationDescriptions}`),
     };
 
     // Collect all unique params across actions
@@ -47,14 +47,14 @@ export function registerAllTools(server: McpServer): void {
         inputSchema,
       },
       async (input) => {
-        const action = input.action as string;
-        const actionDef = tool.actions[action];
+        const operation = input.operation as string;
+        const actionDef = tool.actions[operation];
 
         if (!actionDef) {
-          const error = createToolError(`Unknown action: ${action}`, {
+          const error = createToolError(`Unknown operation: ${operation}`, {
             type: 'UNKNOWN_ACTION',
-            action,
-            validActions: actionKeys,
+            action: operation,
+            validActions: operationKeys,
             tool: tool.name,
           });
           return {
@@ -63,19 +63,48 @@ export function registerAllTools(server: McpServer): void {
           };
         }
 
-        const client = getClient();
-        const params = actionDef.transform
-          ? actionDef.transform(action, input as Record<string, unknown>)
-          : (input as ApiParams);
+        const parsedInput = actionDef.params
+          ? actionDef.params.safeParse(input)
+          : ({ success: true, data: {} } as const);
 
-        // Remove 'action' from params sent to API
-        delete params.action;
+        if (!parsedInput.success) {
+          const details = parsedInput.error.issues
+            .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+            .join('; ');
 
-        const result = await client.execute(actionDef.command, params);
-        const normalized = normalizeResponse(actionDef.command, result);
-        return {
-          content: [{ type: 'text', text: JSON.stringify(normalized, null, 2) }],
-        };
+          const error = createToolError('Invalid tool input', {
+            type: 'VALIDATION_ERROR',
+            tool: tool.name,
+            message: details,
+          });
+          return {
+            content: [{ type: 'text', text: error.toJSON() }],
+            isError: true,
+          };
+        }
+
+        try {
+          const client = getClient();
+          const params = actionDef.transform
+            ? actionDef.transform(operation, parsedInput.data as Record<string, unknown>)
+            : (parsedInput.data as Record<string, unknown> as ApiParams);
+
+          const result = await client.execute(actionDef.command, params);
+          const normalized = normalizeResponse(actionDef.command, result);
+          return {
+            content: [{ type: 'text', text: JSON.stringify(normalized, null, 2) }],
+          };
+        } catch (error) {
+          const toolError = createToolError('Tool execution failed', {
+            type: 'API_ERROR',
+            tool: tool.name,
+            message: error instanceof Error ? error.message : String(error),
+          });
+          return {
+            content: [{ type: 'text', text: toolError.toJSON() }],
+            isError: true,
+          };
+        }
       },
     );
   }

src/tools/generate-ideas.ts

@@ -16,6 +16,15 @@ interface AvailableDomain {
   price?: string;
 }
 
+function shuffle<T>(items: T[]): T[] {
+  const shuffled = [...items];
+  for (let i = shuffled.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [shuffled[i], shuffled[j]] = [shuffled[j] as T, shuffled[i] as T];
+  }
+  return shuffled;
+}
+
 function generateExact(keywords: string[], tlds: string[]): string[] {
   const results: string[] = [];
   for (const keyword of keywords) {
@@ -155,7 +164,9 @@ export function registerGenerateIdeasTool(server: McpServer): void {
       const maxToCheck = (input.maxToCheck as number) ?? 100;
 
       // Generate exact matches first (always checked), then other patterns
-      const exactDomains = patterns.includes('exact') ? generateExact(keywords, tlds) : [];
+      const exactDomains = patterns.includes('exact')
+        ? [...new Set(generateExact(keywords, tlds))]
+        : [];
       const otherDomains = new Set<string>();
       for (const pattern of patterns) {
         if (pattern === 'exact') continue;
@@ -168,11 +179,10 @@ export function registerGenerateIdeasTool(server: McpServer): void {
       }
 
       // Exact matches always included, fill remaining capacity with shuffled others
-      const shuffledOthers = [...otherDomains].sort(() => Math.random() - 0.5);
-      const toCheck = [
-        ...exactDomains,
-        ...shuffledOthers.slice(0, maxToCheck - exactDomains.length),
-      ];
+      const shuffledOthers = shuffle([...otherDomains]);
+      const limitedExactDomains = exactDomains.slice(0, maxToCheck);
+      const remainingSlots = Math.max(0, maxToCheck - limitedExactDomains.length);
+      const toCheck = [...limitedExactDomains, ...shuffledOthers.slice(0, remainingSlots)];
 
       // Check availability in batches
       const available: AvailableDomain[] = [];

src/tools/help.ts

@@ -13,7 +13,7 @@ export function registerHelpTool(server: McpServer): void {
     'dynadot_help',
     {
       description:
-        'Discover available tools and actions. Use query: "tools" to list all tools, "actions" with a tool name to list actions, "examples" for usage examples.',
+        'Discover available tools and operations. Use query: "tools" to list all tools, "actions" with a tool name to list operations, "examples" for usage examples.',
       inputSchema,
     },
     async (input) => {
@@ -37,6 +37,10 @@ export function registerHelpTool(server: McpServer): void {
                   tools,
                   standalone: [
                     { name: 'check_domain', description: 'Check single domain availability' },
+                    {
+                      name: 'generate_domain_ideas',
+                      description: 'Generate available domain ideas from keywords',
+                    },
                     { name: 'dynadot_help', description: 'This help tool' },
                   ],
                 },
@@ -102,7 +106,7 @@ export function registerHelpTool(server: McpServer): void {
                     {
                       description: 'List all domains',
                       tool: 'dynadot_domain',
-                      input: { action: 'list' },
+                      input: { operation: 'list' },
                     },
                     {
                       description: 'Check domain availability',
@@ -112,7 +116,7 @@ export function registerHelpTool(server: McpServer): void {
                     {
                       description: 'Get domain DNS records',
                       tool: 'dynadot_dns',
-                      input: { action: 'get', domain: 'example.com' },
+                      input: { operation: 'get', domain: 'example.com' },
                     },
                   ],
                 },

test/client.test.ts

@@ -0,0 +1,40 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const getSpy = vi.fn();
+
+vi.mock('ky', () => ({
+  default: {
+    create: vi.fn(() => ({
+      get: getSpy,
+    })),
+  },
+}));
+
+import { DynadotClient } from '../src/client.js';
+
+describe('DynadotClient', () => {
+  beforeEach(() => {
+    getSpy.mockReset();
+    getSpy.mockReturnValue({
+      json: vi.fn().mockResolvedValue({ Status: 'success' }),
+    });
+  });
+
+  it('should reject reserved command parameter override', async () => {
+    const client = new DynadotClient({ apiKey: 'test-key' });
+
+    await expect(client.execute('domain_info', { command: 'delete' })).rejects.toThrow(
+      'Reserved parameter "command" cannot be set by tool input',
+    );
+  });
+
+  it('should preserve command and key when building search params', async () => {
+    const client = new DynadotClient({ apiKey: 'test-key' });
+    await client.execute('domain_info', { domain: 'example.com' });
+
+    const options = getSpy.mock.calls[0]?.[1] as { searchParams: URLSearchParams };
+    expect(options.searchParams.get('command')).toBe('domain_info');
+    expect(options.searchParams.get('key')).toBe('test-key');
+    expect(options.searchParams.get('domain')).toBe('example.com');
+  });
+});

test/register.test.ts

@@ -15,6 +15,15 @@ import { getClient } from '../src/client.js';
 import { normalizeResponse } from '../src/normalize.js';
 import { registerAllTools } from '../src/register.js';
 
+type RegisteredTool = {
+  handler: (input: Record<string, unknown>) => Promise<Record<string, unknown>>;
+};
+
+function getRegisteredTools(server: McpServer): Record<string, RegisteredTool> {
+  return (server as unknown as { _registeredTools: Record<string, RegisteredTool> })
+    ._registeredTools;
+}
+
 describe('Tool Registration with Normalizer', () => {
   let server: McpServer;
   let mockClient: { execute: ReturnType<typeof vi.fn> };
@@ -33,8 +42,39 @@ describe('Tool Registration with Normalizer', () => {
 
   it('should call normalizeResponse for tool results', async () => {
     registerAllTools(server);
+    const tools = getRegisteredTools(server);
+    const domainTool = tools.dynadot_domain;
+
+    await domainTool.handler({ operation: 'list' });
+
+    expect(normalizeResponse).toHaveBeenCalled();
+  });
+
+  it('should require operation-specific params before executing', async () => {
+    registerAllTools(server);
+    const tools = getRegisteredTools(server);
+    const domainTool = tools.dynadot_domain;
+
+    const result = await domainTool.handler({ operation: 'register' });
+
+    expect(result.isError).toBe(true);
+    expect(mockClient.execute).not.toHaveBeenCalled();
+  });
+
+  it('should preserve api action parameter for operations that need it', async () => {
+    registerAllTools(server);
+    const tools = getRegisteredTools(server);
+    const transferTool = tools.dynadot_transfer;
+
+    await transferTool.handler({
+      operation: 'set_push_request',
+      domain: 'example.com',
+      action: 'decline',
+    });
 
-    // The normalizer should be imported and used
-    expect(normalizeResponse).toBeDefined();
+    expect(mockClient.execute).toHaveBeenCalledWith('set_domain_push_request', {
+      domain: 'example.com',
+      action: 'decline',
+    });
   });
 });