fix: harden URL validation, body serialization, and Zod schema tests

- Validate VALIDKIT_API_URL has no path, query params, or fragments
- Strip trailing slash from URL to prevent double-slash routing issues
- Guard JSON.stringify(body) with clear error message
- Add Zod min/max validation tests for bulk emails (empty + >1000)
- Assert bulk request body content (not just endpoint URL)
- 44 tests, 100% coverage

Author: jesse-validkit

src/index.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
-import { createServer } from './index.js';
+import { createServer, callApi } from './index.js';
 
 // Mock fetch globally
 const mockFetch = vi.fn();
@@ -276,13 +276,38 @@ describe('ValidKit MCP Server', () => {
       expect(parsed.results).toHaveLength(2);
       expect(parsed.summary.total).toBe(2);
 
-      // Verify correct endpoint (not /v1/verify/batch)
+      // Verify correct endpoint and body
       expect(mockFetch).toHaveBeenCalledWith(
         'https://api.validkit.com/v1/verify/bulk',
-        expect.anything()
+        expect.objectContaining({
+          body: JSON.stringify({ emails: ['a@gmail.com', 'b@fake.xyz'] }),
+        })
       );
     });
 
+    it('rejects empty emails array via Zod schema', async () => {
+      const { client } = await createTestClient();
+
+      const result = await client.callTool({
+        name: 'validate_emails_bulk',
+        arguments: { emails: [] },
+      });
+
+      expect(result.isError).toBe(true);
+    });
+
+    it('rejects >1000 emails via Zod schema', async () => {
+      const { client } = await createTestClient();
+      const tooMany = Array.from({ length: 1001 }, (_, i) => `u${i}@test.com`);
+
+      const result = await client.callTool({
+        name: 'validate_emails_bulk',
+        arguments: { emails: tooMany },
+      });
+
+      expect(result.isError).toBe(true);
+    });
+
     it('handles API error on bulk', async () => {
       const { client } = await createTestClient();
       mockFetchResponse(401, { error: { message: 'Invalid API key' } });
@@ -507,6 +532,61 @@ describe('ValidKit MCP Server', () => {
       expect(getText(result)).toContain('must use https://');
     });
 
+    it('rejects URL with path', async () => {
+      process.env.VALIDKIT_API_URL = 'https://api.validkit.com/v1';
+      const { client } = await createTestClient();
+
+      const result = await client.callTool({
+        name: 'validate_email',
+        arguments: { email: 'test@gmail.com' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(getText(result)).toContain('origin URL without a path');
+    });
+
+    it('rejects invalid URL', async () => {
+      process.env.VALIDKIT_API_URL = 'https://not a valid url';
+      const { client } = await createTestClient();
+
+      const result = await client.callTool({
+        name: 'validate_email',
+        arguments: { email: 'test@gmail.com' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(getText(result)).toContain('not a valid URL');
+    });
+
+    it('rejects URL with query params', async () => {
+      process.env.VALIDKIT_API_URL = 'https://api.validkit.com?foo=bar';
+      const { client } = await createTestClient();
+
+      const result = await client.callTool({
+        name: 'validate_email',
+        arguments: { email: 'test@gmail.com' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(getText(result)).toContain('query parameters');
+    });
+
+    it('strips trailing slash from URL', async () => {
+      process.env.VALIDKIT_API_URL = 'https://api.validkit.com/';
+      const { client } = await createTestClient();
+      mockFetchResponse(200, { email: 'a@b.com', valid: true });
+
+      await client.callTool({
+        name: 'validate_email',
+        arguments: { email: 'a@b.com' },
+      });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.validkit.com/v1/verify',
+        expect.anything()
+      );
+    });
+
     it('handles non-JSON API response gracefully', async () => {
       const { client } = await createTestClient();
       mockFetch.mockResolvedValueOnce({
@@ -624,5 +704,14 @@ describe('ValidKit MCP Server', () => {
       expect(getText(result)).toContain('30 seconds');
       expect(getText(result)).not.toContain('was aborted');
     });
+
+    it('throws clear error when body cannot be serialized', async () => {
+      const circular: Record<string, unknown> = {};
+      circular.self = circular;
+
+      await expect(callApi('/v1/verify', 'POST', circular)).rejects.toThrow(
+        'Failed to serialize request body'
+      );
+    });
   });
 });

src/index.ts

@@ -17,13 +17,31 @@ export function formatCatchError(error: unknown, prefix: string): string {
 }
 
 export function getApiBaseUrl(): string {
-  const url = process.env.VALIDKIT_API_URL || 'https://api.validkit.com';
-  if (!url.startsWith('https://')) {
+  const raw = process.env.VALIDKIT_API_URL || 'https://api.validkit.com';
+  if (!raw.startsWith('https://')) {
     throw new Error(
-      `VALIDKIT_API_URL must use https:// (got "${url}")`
+      `VALIDKIT_API_URL must use https:// (got "${raw}")`
     );
   }
-  return url;
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(
+      `VALIDKIT_API_URL is not a valid URL (got "${raw}")`
+    );
+  }
+  if (parsed.pathname !== '/' && parsed.pathname !== '') {
+    throw new Error(
+      `VALIDKIT_API_URL must be an origin URL without a path (got "${raw}"). Use "https://api.validkit.com" not "https://api.validkit.com/v1"`
+    );
+  }
+  if (parsed.search || parsed.hash) {
+    throw new Error(
+      `VALIDKIT_API_URL must not include query parameters or fragments (got "${raw}")`
+    );
+  }
+  return raw.replace(/\/+$/, '');
 }
 
 export function getApiKey(): string {
@@ -43,15 +61,26 @@ export async function callApi(
 ): Promise<{ ok: boolean; status: number; data: unknown }> {
   const apiKey = getApiKey();
 
+  let serializedBody: string | undefined;
+  if (body !== undefined) {
+    try {
+      serializedBody = JSON.stringify(body);
+    } catch {
+      throw new Error('Failed to serialize request body');
+    }
+  }
+
   const response = await fetch(`${getApiBaseUrl()}${path}`, {
     method,
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
     headers: {
       'X-API-Key': apiKey,
       'User-Agent': `validkit-mcp/${VERSION}`,
-      ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+      ...(serializedBody !== undefined
+        ? { 'Content-Type': 'application/json' }
+        : {}),
     },
-    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    ...(serializedBody !== undefined ? { body: serializedBody } : {}),
   });
 
   let data: unknown;