mocktail-mcp 3.1.4

package/README.md

@@ -0,0 +1,91 @@
+# Mocktail MCP Server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets AI assistants manage [Mocktail](https://github.com/Huseyinnurbaki/mocktail) mock API endpoints through natural language.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_mocks` | List all configured mock endpoints |
+| `create_mock` | Create a single mock endpoint |
+| `update_mock` | Update an existing mock by ID |
+| `delete_mock` | Delete a mock by ID |
+| `import_mocks` | Bulk import multiple mock endpoints (skips duplicates) |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MOCKTAIL_URL` | Yes | Base URL of your Mocktail instance (e.g. `http://localhost:4000`) |
+| `MOCKTAIL_API_KEY` | No | API key, sent as `X-API-Key` header |
+
+> **Note:** If you're running Mocktail behind a reverse proxy or custom domain (via `MOCKTAIL_BASE_URL`), use that host as `MOCKTAIL_URL` (e.g. `MOCKTAIL_URL=https://api.mycompany.com`).
+
+## Setup
+
+### npx (Recommended)
+
+**Claude Code:**
+```bash
+claude mcp add mocktail \
+  -e MOCKTAIL_URL=http://localhost:4000 \
+  -e MOCKTAIL_API_KEY=your-api-key \
+  -- npx mocktail-mcp
+```
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "mocktail": {
+      "command": "npx",
+      "args": ["mocktail-mcp"],
+      "env": {
+        "MOCKTAIL_URL": "http://localhost:4000",
+        "MOCKTAIL_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### From Source (Development)
+
+If you cloned the repo and want to run the MCP server locally:
+
+```bash
+cd mcp-server && npm install
+```
+
+**Claude Code:**
+```bash
+claude mcp add mocktail \
+  -e MOCKTAIL_URL=http://localhost:4000 \
+  -e MOCKTAIL_API_KEY=your-api-key \
+  -- node /absolute/path/to/mcp-server/index.js
+```
+
+**Claude Desktop:**
+```json
+{
+  "mcpServers": {
+    "mocktail": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-server/index.js"],
+      "env": {
+        "MOCKTAIL_URL": "http://localhost:4000",
+        "MOCKTAIL_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Usage Examples
+
+Once connected, you can use natural language:
+
+- "List all my mock endpoints"
+- "Create a GET /api/users mock that returns a list of 3 users"
+- "Delete mock endpoint #5"
+- "Import mock endpoints for a blog API with posts, comments, and authors"

package/index.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const MOCKTAIL_URL = process.env.MOCKTAIL_URL;
+const MOCKTAIL_API_KEY = process.env.MOCKTAIL_API_KEY || "";
+
+if (!MOCKTAIL_URL) {
+  console.error("MOCKTAIL_URL environment variable is required");
+  process.exit(1);
+}
+
+async function mocktailRequest(path, options = {}) {
+  const url = `${MOCKTAIL_URL}${path}`;
+  const headers = { "Content-Type": "application/json" };
+  if (MOCKTAIL_API_KEY) {
+    headers["X-API-Key"] = MOCKTAIL_API_KEY;
+  }
+
+  const res = await fetch(url, { ...options, headers });
+  const body = await res.json();
+
+  if (!res.ok) {
+    throw new Error(body.message || `Request failed with status ${res.status}`);
+  }
+  return body;
+}
+
+const server = new McpServer({
+  name: "mocktail",
+  version: "3.1.4",
+});
+
+// list_mocks
+server.tool(
+  "list_mocks",
+  "List all configured mock endpoints in Mocktail",
+  {},
+  async () => {
+    try {
+      const mocks = await mocktailRequest("/core/v1/apis");
+      return {
+        content: [{ type: "text", text: JSON.stringify(mocks, null, 2) + `\n\nMock endpoints are accessible at: ${MOCKTAIL_URL}/mocktail{Endpoint}` }],
+      };
+    } catch (err) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+      };
+    }
+  }
+);
+
+// create_mock
+server.tool(
+  "create_mock",
+  "Create a new mock endpoint. Method must be GET, POST, PUT, PATCH, or DELETE. Response should be a JSON value (object, array, string, etc.). The endpoint path is relative — e.g. '/api/users' becomes accessible at MOCKTAIL_URL/mocktail/api/users.",
+  {
+    method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).describe("HTTP method"),
+    endpoint: z.string().describe("URL path starting with /, e.g. /api/users. Accessible at MOCKTAIL_URL/mocktail/api/users"),
+    response: z.string().describe("JSON string for the response body"),
+    statusCode: z.number().optional().describe("HTTP status code (default 200)"),
+    delay: z.number().optional().describe("Response delay in ms (0-30000, default 0)"),
+  },
+  async ({ method, endpoint, response, statusCode, delay }) => {
+    try {
+      const parsed = JSON.parse(response);
+      const result = await mocktailRequest("/core/v1/api", {
+        method: "POST",
+        body: JSON.stringify({
+          Method: method,
+          Endpoint: endpoint,
+          Response: parsed,
+          StatusCode: statusCode ?? 200,
+          Delay: delay ?? 0,
+        }),
+      });
+      const accessUrl = `${MOCKTAIL_URL}/mocktail${endpoint}`;
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) + `\n\nAccessible at: ${method} ${accessUrl}` }],
+      };
+    } catch (err) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+      };
+    }
+  }
+);
+
+// update_mock
+server.tool(
+  "update_mock",
+  "Update an existing mock endpoint by ID. All fields are required since the entire mock is replaced. The endpoint path is relative — e.g. '/api/users' becomes accessible at MOCKTAIL_URL/mocktail/api/users.",
+  {
+    id: z.number().describe("Mock endpoint ID"),
+    method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).describe("HTTP method"),
+    endpoint: z.string().describe("URL path starting with /, e.g. /api/users"),
+    response: z.string().describe("JSON string for the response body"),
+    statusCode: z.number().optional().describe("HTTP status code (default 200)"),
+    delay: z.number().optional().describe("Response delay in ms (0-30000, default 0)"),
+  },
+  async ({ id, method, endpoint, response, statusCode, delay }) => {
+    try {
+      const parsed = JSON.parse(response);
+      const result = await mocktailRequest(`/core/v1/api/${id}`, {
+        method: "PUT",
+        body: JSON.stringify({
+          Method: method,
+          Endpoint: endpoint,
+          Response: parsed,
+          StatusCode: statusCode ?? 200,
+          Delay: delay ?? 0,
+        }),
+      });
+      const accessUrl = `${MOCKTAIL_URL}/mocktail${endpoint}`;
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) + `\n\nAccessible at: ${method} ${accessUrl}` }],
+      };
+    } catch (err) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+      };
+    }
+  }
+);
+
+// delete_mock
+server.tool(
+  "delete_mock",
+  "Delete a mock endpoint by ID",
+  {
+    id: z.number().describe("Mock endpoint ID to delete"),
+  },
+  async ({ id }) => {
+    try {
+      const result = await mocktailRequest(`/core/v1/api/${id}`, {
+        method: "DELETE",
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (err) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+      };
+    }
+  }
+);
+
+// import_mocks
+server.tool(
+  "import_mocks",
+  "Bulk import multiple mock endpoints. Existing endpoints (same method+path) are skipped. Response fields should be JSON strings.",
+  {
+    mocks: z.array(
+      z.object({
+        method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).describe("HTTP method"),
+        endpoint: z.string().describe("URL path starting with /, e.g. /api/users"),
+        response: z.string().describe("JSON string for the response body"),
+        statusCode: z.number().optional().describe("HTTP status code (default 200)"),
+        delay: z.number().optional().describe("Response delay in ms (default 0)"),
+      })
+    ).describe("Array of mock endpoints to import"),
+  },
+  async ({ mocks }) => {
+    try {
+      const apis = mocks.map((m) => ({
+        Method: m.method,
+        Endpoint: m.endpoint,
+        Response: JSON.parse(m.response),
+        StatusCode: m.statusCode ?? 200,
+        Delay: m.delay ?? 0,
+      }));
+      const result = await mocktailRequest("/core/v1/import", {
+        method: "POST",
+        body: JSON.stringify({ Apis: apis }),
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (err) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+      };
+    }
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "mocktail-mcp",
+  "version": "3.1.4",
+  "description": "MCP server for managing Mocktail mock API endpoints",
+  "type": "module",
+  "bin": {
+    "mocktail-mcp": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mocktail",
+    "mcp",
+    "mock",
+    "api"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.2"
+  }
+}