@rog0x/mcp-testing-tools 1.0.0

package/README.md

@@ -0,0 +1,109 @@
+# @rog0x/mcp-testing-tools
+
+Testing and quality assurance tools for AI agents, exposed via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
+
+## Tools
+
+### generate_tests
+
+Generate test cases from a function signature. Produces four categories of tests as ready-to-run Jest or Vitest code:
+
+- **Happy path** -- valid inputs, expected outputs
+- **Edge cases** -- empty strings, zero values, null parameters
+- **Error cases** -- missing arguments, wrong types
+- **Boundary values** -- extreme numbers, large arrays, NaN
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `signature` | string | Yes | Function signature, e.g. `async function fetchUser(id: number): Promise<User>` |
+| `framework` | string | No | `jest` or `vitest` (default: `vitest`) |
+| `module_path` | string | No | Import path for the module under test (default: `./module`) |
+
+### generate_mock_data
+
+Generate realistic mock data for testing. Supported types:
+
+`name`, `email`, `address`, `date`, `uuid`, `phone`, `company`, `credit_card`, `ip`
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `type` | string | Yes | Data type to generate |
+| `count` | number | No | Number of items (default: 10, max: 1000) |
+| `locale` | string | No | `en` or `es` (default: `en`) |
+| `types` | string[] | No | Generate mixed records with multiple field types |
+
+### generate_api_mock
+
+Generate mock API responses from a schema definition. Creates realistic JSON payloads for REST endpoints by inferring values from field names and types.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `endpoint` | string | Yes | API endpoint path |
+| `method` | string | No | HTTP method (default: `GET`) |
+| `fields` | object[] | Yes | Field schemas with `name`, `type`, optional `items`, `fields`, `nullable`, `enum` |
+| `count` | number | No | Number of records (default: 1, max: 100) |
+| `status_code` | number | No | HTTP status code (default: 200) |
+| `wrap_in_envelope` | boolean | No | Wrap in `{ success, data, meta }` (default: true) |
+
+### analyze_test_coverage
+
+Analyze source code and test code to find untested functions. Prioritizes suggestions by:
+
+- Export status (public API surface)
+- Cyclomatic complexity estimate
+- Parameter count
+- Async functions (more error paths)
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `source_code` | string | Yes | Source code to analyze |
+| `test_code` | string | Yes | Existing test code |
+| `source_file_name` | string | No | Filename label (default: `source.ts`) |
+
+### generate_assertions
+
+Generate detailed assertion code by comparing expected and actual values. Performs deep diff and produces per-field assertions with descriptive comments.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `expected` | string | Yes | Expected value as JSON string |
+| `actual` | string | Yes | Actual value as JSON string |
+| `label` | string | No | Description for the comparison |
+| `framework` | string | No | `jest`, `vitest`, or `chai` (default: `jest`) |
+| `deep` | boolean | No | Deep equality for objects/arrays (default: true) |
+
+## Setup
+
+```bash
+npm install
+npm run build
+```
+
+## Usage with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "testing-tools": {
+      "command": "node",
+      "args": ["path/to/mcp-testing-tools/dist/index.js"]
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { generateTests } from "./tools/test-generator.js";
+import { generateMockData, generateMixedMockData } from "./tools/mock-data.js";
+import { generateApiMockResponse } from "./tools/api-mock.js";
+import { analyzeCoverage } from "./tools/test-coverage-analyzer.js";
+import { generateAssertions } from "./tools/assertion-helper.js";
+const server = new Server({
+    name: "mcp-testing-tools",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "generate_tests",
+            description: "Generate test cases from a function signature. Produces happy path, edge cases, error cases, and boundary value tests as Jest/Vitest test code.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    signature: {
+                        type: "string",
+                        description: 'The function signature to generate tests for, e.g. "export async function fetchUser(id: number): Promise<User>"',
+                    },
+                    framework: {
+                        type: "string",
+                        enum: ["jest", "vitest"],
+                        description: "Test framework to generate for (default: vitest)",
+                    },
+                    module_path: {
+                        type: "string",
+                        description: 'Import path for the module under test (default: "./module")',
+                    },
+                },
+                required: ["signature"],
+            },
+        },
+        {
+            name: "generate_mock_data",
+            description: "Generate realistic mock data: names, emails, addresses, dates, UUIDs, phone numbers, company names, credit cards (fake), IP addresses. Configurable count and locale.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    type: {
+                        type: "string",
+                        description: "Type of data to generate: name, email, address, date, uuid, phone, company, credit_card, ip",
+                    },
+                    count: {
+                        type: "number",
+                        description: "Number of items to generate (default: 10, max: 1000)",
+                    },
+                    locale: {
+                        type: "string",
+                        description: 'Locale for generated data: "en" or "es" (default: "en")',
+                    },
+                    types: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Generate mixed records with multiple field types (alternative to single type). Each record will have all specified fields.",
+                    },
+                },
+                required: ["type"],
+            },
+        },
+        {
+            name: "generate_api_mock",
+            description: "Generate mock API responses from a schema. Creates realistic JSON responses for REST endpoints based on field names and types.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    endpoint: {
+                        type: "string",
+                        description: 'API endpoint path, e.g. "/api/v1/users"',
+                    },
+                    method: {
+                        type: "string",
+                        enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+                        description: "HTTP method (default: GET)",
+                    },
+                    fields: {
+                        type: "array",
+                        description: "Array of field schemas. Each field has: name (string), type (string|number|boolean|date|array|object), optional items (for arrays), optional fields (for nested objects), optional nullable, optional enum.",
+                        items: {
+                            type: "object",
+                            properties: {
+                                name: { type: "string" },
+                                type: { type: "string" },
+                                items: { type: "array" },
+                                fields: { type: "array" },
+                                nullable: { type: "boolean" },
+                                enum: { type: "array", items: { type: "string" } },
+                            },
+                            required: ["name", "type"],
+                        },
+                    },
+                    count: {
+                        type: "number",
+                        description: "Number of records to generate (default: 1, max: 100)",
+                    },
+                    status_code: {
+                        type: "number",
+                        description: "HTTP status code for the response (default: 200)",
+                    },
+                    wrap_in_envelope: {
+                        type: "boolean",
+                        description: "Wrap response in { success, data, meta } envelope (default: true)",
+                    },
+                },
+                required: ["endpoint", "fields"],
+            },
+        },
+        {
+            name: "analyze_test_coverage",
+            description: "Parse source code and test code to identify untested functions. Suggests which functions need tests most based on complexity, export status, and parameter count.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    source_code: {
+                        type: "string",
+                        description: "The source code to analyze for functions",
+                    },
+                    test_code: {
+                        type: "string",
+                        description: "The test code to check which functions are already tested",
+                    },
+                    source_file_name: {
+                        type: "string",
+                        description: 'Filename for the source (used in output, default: "source.ts")',
+                    },
+                },
+                required: ["source_code", "test_code"],
+            },
+        },
+        {
+            name: "generate_assertions",
+            description: "Given expected and actual values (as JSON strings), generate detailed assertion code with descriptive messages. Supports deep object comparison, array comparison, and type checking.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    expected: {
+                        type: "string",
+                        description: "The expected value as a JSON string (or plain string for primitives)",
+                    },
+                    actual: {
+                        type: "string",
+                        description: "The actual value as a JSON string (or plain string for primitives)",
+                    },
+                    label: {
+                        type: "string",
+                        description: 'Descriptive label for the comparison (default: "value comparison")',
+                    },
+                    framework: {
+                        type: "string",
+                        enum: ["jest", "vitest", "chai"],
+                        description: "Assertion framework to generate for (default: jest)",
+                    },
+                    deep: {
+                        type: "boolean",
+                        description: "Use deep equality for objects/arrays (default: true)",
+                    },
+                },
+                required: ["expected", "actual"],
+            },
+        },
+    ],
+}));
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "generate_tests": {
+                const result = generateTests(args?.signature, args?.framework || "vitest", args?.module_path || "./module");
+                return {
+                    content: [{ type: "text", text: result }],
+                };
+            }
+            case "generate_mock_data": {
+                if (args?.types && Array.isArray(args.types)) {
+                    const result = generateMixedMockData(args.types, args?.count || 10, args?.locale || "en");
+                    return {
+                        content: [
+                            { type: "text", text: JSON.stringify(result, null, 2) },
+                        ],
+                    };
+                }
+                const result = generateMockData(args?.type, args?.count || 10, args?.locale || "en");
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "generate_api_mock": {
+                const result = generateApiMockResponse({
+                    endpoint: args?.endpoint,
+                    method: args?.method || "GET",
+                    fields: args?.fields,
+                    count: args?.count || 1,
+                    statusCode: args?.status_code || 200,
+                    wrapInEnvelope: args?.wrap_in_envelope !== undefined
+                        ? args.wrap_in_envelope
+                        : true,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "analyze_test_coverage": {
+                const result = analyzeCoverage(args?.source_code, args?.test_code, args?.source_file_name || "source.ts");
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "generate_assertions": {
+                const result = generateAssertions({
+                    expected: args?.expected,
+                    actual: args?.actual,
+                    label: args?.label || "value comparison",
+                    framework: args?.framework || "jest",
+                    deep: args?.deep !== undefined ? args.deep : true,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP Testing Tools server running on stdio");
+}
+main().catch(console.error);
+//# sourceMappingURL=index.js.map

package/dist/tools/api-mock.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Generate mock API responses from a schema definition.
+ * Creates realistic JSON responses for REST endpoints
+ * based on field names and types.
+ */
+interface FieldSchema {
+    name: string;
+    type: string;
+    items?: FieldSchema[];
+    fields?: FieldSchema[];
+    nullable?: boolean;
+    enum?: string[];
+}
+interface ApiMockOptions {
+    endpoint: string;
+    method: string;
+    fields: FieldSchema[];
+    count?: number;
+    statusCode?: number;
+    wrapInEnvelope?: boolean;
+}
+export declare function generateApiMockResponse(options: ApiMockOptions): {
+    endpoint: string;
+    method: string;
+    statusCode: number;
+    headers: Record<string, string>;
+    body: unknown;
+};
+export {};
+//# sourceMappingURL=api-mock.d.ts.map

package/dist/tools/api-mock.js

@@ -0,0 +1,193 @@
+/**
+ * Generate mock API responses from a schema definition.
+ * Creates realistic JSON responses for REST endpoints
+ * based on field names and types.
+ */
+class MockRng {
+    s;
+    constructor(seed) {
+        this.s = seed;
+    }
+    next() {
+        this.s = (this.s * 1664525 + 1013904223) & 0x7fffffff;
+        return this.s / 0x7fffffff;
+    }
+    int(min, max) {
+        return Math.floor(this.next() * (max - min + 1)) + min;
+    }
+    pick(arr) {
+        return arr[this.int(0, arr.length - 1)];
+    }
+    float(min, max, decimals = 2) {
+        return parseFloat((this.next() * (max - min) + min).toFixed(decimals));
+    }
+}
+const SAMPLE_WORDS = [
+    "alpha", "bravo", "charlie", "delta", "echo", "foxtrot", "golf",
+    "hotel", "india", "juliet", "kilo", "lima", "mike", "november",
+];
+const SAMPLE_NAMES = [
+    "Alice Morgan", "Bob Chen", "Carol Evans", "Dan Walsh", "Eve Porter",
+    "Frank Santos", "Grace Kim", "Henry Liu", "Irene Cruz", "Jack Reed",
+];
+const SAMPLE_TITLES = [
+    "Getting Started Guide", "Advanced Configuration", "Performance Tuning",
+    "Security Best Practices", "API Reference Manual", "Migration Notes",
+    "Release Highlights", "Troubleshooting Tips", "Architecture Overview",
+];
+const SAMPLE_DESCRIPTIONS = [
+    "A comprehensive solution for modern workflows.",
+    "Streamlined process with enterprise-grade reliability.",
+    "Built for scalability and high availability.",
+    "Designed with developer experience in mind.",
+    "Optimized for performance and low latency.",
+];
+const SAMPLE_URLS = [
+    "https://api.example.com/v1/resource",
+    "https://cdn.example.com/assets/image.png",
+    "https://docs.example.com/guides/setup",
+];
+const SAMPLE_EMAILS = [
+    "user@example.com", "admin@testdomain.org", "support@mockapi.net",
+];
+function inferValueFromName(name, rng) {
+    const lower = name.toLowerCase();
+    if (lower === "id" || lower.endsWith("_id") || lower.endsWith("Id")) {
+        return rng.int(1, 99999);
+    }
+    if (lower === "uuid" || lower.endsWith("_uuid")) {
+        const hex = () => rng.int(0, 15).toString(16);
+        const seg = (n) => Array.from({ length: n }, hex).join("");
+        return `${seg(8)}-${seg(4)}-4${seg(3)}-${rng.pick(["8", "9", "a", "b"])}${seg(3)}-${seg(12)}`;
+    }
+    if (lower.includes("email"))
+        return rng.pick(SAMPLE_EMAILS);
+    if (lower.includes("name") || lower === "author" || lower === "user")
+        return rng.pick(SAMPLE_NAMES);
+    if (lower.includes("title") || lower === "subject")
+        return rng.pick(SAMPLE_TITLES);
+    if (lower.includes("description") || lower.includes("summary") || lower === "body" || lower === "content")
+        return rng.pick(SAMPLE_DESCRIPTIONS);
+    if (lower.includes("url") || lower.includes("link") || lower.includes("href"))
+        return rng.pick(SAMPLE_URLS);
+    if (lower.includes("image") || lower.includes("avatar") || lower.includes("photo"))
+        return `https://picsum.photos/seed/${rng.int(1, 999)}/200/200`;
+    if (lower.includes("price") || lower.includes("amount") || lower.includes("cost") || lower.includes("total"))
+        return rng.float(1, 999, 2);
+    if (lower.includes("count") || lower.includes("quantity") || lower === "total" || lower === "size")
+        return rng.int(0, 500);
+    if (lower.includes("rating") || lower.includes("score"))
+        return rng.float(1, 5, 1);
+    if (lower.includes("active") || lower.includes("enabled") || lower.includes("verified") || lower.startsWith("is_") || lower.startsWith("has_"))
+        return rng.next() > 0.3;
+    if (lower.includes("date") || lower.includes("created") || lower.includes("updated") || lower.includes("timestamp")) {
+        const y = rng.int(2020, 2026);
+        const m = String(rng.int(1, 12)).padStart(2, "0");
+        const d = String(rng.int(1, 28)).padStart(2, "0");
+        return `${y}-${m}-${d}T${String(rng.int(0, 23)).padStart(2, "0")}:${String(rng.int(0, 59)).padStart(2, "0")}:00Z`;
+    }
+    if (lower.includes("phone"))
+        return `+1 (${rng.int(200, 999)}) ${rng.int(200, 999)}-${rng.int(1000, 9999)}`;
+    if (lower.includes("status"))
+        return rng.pick(["active", "inactive", "pending", "completed"]);
+    if (lower.includes("type") || lower.includes("category"))
+        return rng.pick(["standard", "premium", "basic", "enterprise"]);
+    if (lower.includes("tag"))
+        return rng.pick(SAMPLE_WORDS);
+    if (lower.includes("color"))
+        return `#${rng.int(0, 0xffffff).toString(16).padStart(6, "0")}`;
+    if (lower.includes("ip"))
+        return `${rng.int(1, 254)}.${rng.int(0, 255)}.${rng.int(0, 255)}.${rng.int(1, 254)}`;
+    if (lower.includes("latitude") || lower === "lat")
+        return rng.float(-90, 90, 6);
+    if (lower.includes("longitude") || lower === "lng" || lower === "lon")
+        return rng.float(-180, 180, 6);
+    return rng.pick(SAMPLE_WORDS);
+}
+function generateFieldValue(field, rng) {
+    if (field.nullable && rng.next() < 0.15)
+        return null;
+    if (field.enum && field.enum.length > 0)
+        return rng.pick(field.enum);
+    const type = field.type.toLowerCase();
+    if (type === "string")
+        return String(inferValueFromName(field.name, rng));
+    if (type === "number" || type === "integer" || type === "int") {
+        const inferred = inferValueFromName(field.name, rng);
+        return typeof inferred === "number" ? inferred : rng.int(1, 1000);
+    }
+    if (type === "float" || type === "decimal" || type === "double") {
+        const inferred = inferValueFromName(field.name, rng);
+        return typeof inferred === "number" ? inferred : rng.float(0, 1000, 2);
+    }
+    if (type === "boolean" || type === "bool") {
+        const inferred = inferValueFromName(field.name, rng);
+        return typeof inferred === "boolean" ? inferred : rng.next() > 0.5;
+    }
+    if (type === "date" || type === "datetime" || type === "timestamp") {
+        return inferValueFromName(field.name.includes("date") ? field.name : "created_at", rng);
+    }
+    if (type === "array") {
+        const arrLen = rng.int(1, 5);
+        if (field.items && field.items.length > 0) {
+            if (field.items.length === 1 && !field.items[0].fields) {
+                return Array.from({ length: arrLen }, () => generateFieldValue(field.items[0], rng));
+            }
+            return Array.from({ length: arrLen }, () => {
+                const obj = {};
+                for (const sub of field.items) {
+                    obj[sub.name] = generateFieldValue(sub, rng);
+                }
+                return obj;
+            });
+        }
+        return Array.from({ length: arrLen }, () => rng.pick(SAMPLE_WORDS));
+    }
+    if (type === "object") {
+        if (field.fields && field.fields.length > 0) {
+            const obj = {};
+            for (const sub of field.fields) {
+                obj[sub.name] = generateFieldValue(sub, rng);
+            }
+            return obj;
+        }
+        return {};
+    }
+    return inferValueFromName(field.name, rng);
+}
+function generateSingleRecord(fields, rng) {
+    const record = {};
+    for (const field of fields) {
+        record[field.name] = generateFieldValue(field, rng);
+    }
+    return record;
+}
+export function generateApiMockResponse(options) {
+    const { endpoint, method = "GET", fields, count = 1, statusCode = 200, wrapInEnvelope = true, } = options;
+    const rng = new MockRng(Date.now() % 100000);
+    const safeCount = Math.min(Math.max(1, count), 100);
+    const isList = safeCount > 1 || method.toUpperCase() === "GET" && endpoint.match(/\/\w+\/?$/);
+    let body;
+    if (safeCount === 1 && !isList) {
+        const record = generateSingleRecord(fields, rng);
+        body = wrapInEnvelope ? { success: true, data: record } : record;
+    }
+    else {
+        const records = Array.from({ length: safeCount }, () => generateSingleRecord(fields, rng));
+        body = wrapInEnvelope
+            ? { success: true, data: records, meta: { total: rng.int(safeCount, safeCount * 10), page: 1, perPage: safeCount } }
+            : records;
+    }
+    return {
+        endpoint,
+        method: method.toUpperCase(),
+        statusCode,
+        headers: {
+            "Content-Type": "application/json",
+            "X-Request-Id": String(rng.int(100000, 999999)),
+            "X-RateLimit-Remaining": String(rng.int(50, 1000)),
+        },
+        body,
+    };
+}
+//# sourceMappingURL=api-mock.js.map

package/dist/tools/assertion-helper.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Given expected vs actual values, generate detailed assertion code
+ * with descriptive messages. Supports deep object comparison,
+ * array comparison, and type checking.
+ */
+interface AssertionOptions {
+    expected: string;
+    actual: string;
+    label?: string;
+    framework?: "jest" | "vitest" | "chai";
+    deep?: boolean;
+}
+interface DiffEntry {
+    path: string;
+    expected: unknown;
+    actual: unknown;
+    type: "missing" | "extra" | "type_mismatch" | "value_mismatch";
+}
+export declare function generateAssertions(options: AssertionOptions): {
+    code: string;
+    diffs: DiffEntry[];
+    summary: string;
+};
+export {};
+//# sourceMappingURL=assertion-helper.d.ts.map