mcp-apitools 1.0.5 → 1.1.0

package/README.md

@@ -1,83 +1,8 @@
-# mcp-apitools
 
-MCP server with 8 API & web development utilities for Claude, Cursor, and other MCP-compatible AI assistants.
 
-## Quick Start
+## Support
 
-```bash
-npx mcp-apitools
-```
+If this tool saves you time, consider supporting development:
 
-### Claude Desktop
-
-Add to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "apitools": {
-      "command": "npx",
-      "args": ["-y", "mcp-apitools"]
-    }
-  }
-}
-```
-
-### Cursor
-
-Add to MCP settings:
-
-```json
-{
-  "mcpServers": {
-    "apitools": {
-      "command": "npx",
-      "args": ["-y", "mcp-apitools"]
-    }
-  }
-}
-```
-
-## Tools (8)
-
-| Tool | Description |
-|------|-------------|
-| `http_status` | Look up any HTTP status code — phrase, category, description |
-| `mime_lookup` | Get MIME type for file extension or find extensions for a MIME type |
-| `jwt_create` | Create unsigned JWTs for testing with custom claims |
-| `mock_data` | Generate fake people with names, emails, phones, addresses |
-| `cors_headers` | Generate CORS response headers for your API |
-| `cookie_parse` | Parse Cookie or Set-Cookie headers into structured data |
-| `basic_auth` | Generate Basic Authorization headers |
-| `query_string` | Parse or build URL query strings |
-
-## Examples
-
-**Look up HTTP 429:**
-> "What does HTTP 429 mean?" → `Too Many Requests — User has sent too many requests (rate limiting).`
-
-**Generate test data:**
-> "Generate 3 fake users for testing" → Returns 3 people with realistic names, emails, addresses
-
-**Create a test JWT:**
-> "Make a JWT with sub=123 and role=admin" → Returns unsigned JWT token
-
-**Parse cookies:**
-> "Parse this cookie header: session=abc123; theme=dark" → `{"session": "abc123", "theme": "dark"}`
-
-## See Also
-
-- [mcp-devutils](https://www.npmjs.com/package/mcp-devutils) — UUID, hash, base64, timestamps, JWT decode, and more
-- [mcp-texttools](https://www.npmjs.com/package/mcp-texttools) — 10 text transformation tools: case convert, slugify, word count, lorem ipsum, regex replace, markdown strip
-- [mcp-mathtools](https://www.npmjs.com/package/mcp-mathtools) — 12 math & statistics tools: arithmetic, statistics, unit conversion, financial calculations, matrices
-- [mcp-datetime](https://www.npmjs.com/package/mcp-datetime) — 10 date & time tools: timezone conversion, date math, cron explanation, business days
-- [mcp-quick-calc](https://www.npmjs.com/package/mcp-quick-calc) — 5 calculator tools: currency conversion, percentages, compound interest, unit conversion, loan payments
-- **[mcp-all-tools](https://www.npmjs.com/package/mcp-all-tools)** — All 54+ tools in a single MCP server
-
-## License
-
-MIT
-
----
-
-☕ If this saves you time, [buy me a coffee](https://buymeacoffee.com/gl89tu25lp)
+- [Buy me a coffee](https://buymeacoffee.com/gl89tu25lp)
+- [Tip via Stripe ($3)](https://buy.stripe.com/dRm8wP8R295Z9VyeN59Zm00)

package/index.js

@@ -6,7 +6,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import crypto from "crypto";
 
 const server = new Server(
-  { name: "mcp-apitools", version: "1.0.0" },
+  { name: "mcp-apitools", version: "1.1.0" },
   { capabilities: { tools: {} } }
 );
 
@@ -180,6 +180,79 @@ const TOOLS = [
       },
       required: ["input"]
     }
+  },
+  {
+    name: "url_parse",
+    description: "Parse a URL into its components — protocol, host, port, pathname, search params, hash, origin",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "URL to parse (e.g. 'https://api.example.com:8080/v1/users?page=2#section')" }
+      },
+      required: ["url"]
+    }
+  },
+  {
+    name: "bearer_token",
+    description: "Generate a Bearer Authorization header from a token string",
+    inputSchema: {
+      type: "object",
+      properties: {
+        token: { type: "string", description: "Bearer token value" }
+      },
+      required: ["token"]
+    }
+  },
+  {
+    name: "request_id",
+    description: "Generate unique request/correlation IDs for distributed tracing (UUID v4, prefixed, or nanoid-style)",
+    inputSchema: {
+      type: "object",
+      properties: {
+        format: { type: "string", enum: ["uuid", "prefixed", "short"], description: "ID format: uuid (default), prefixed (req_xxx), or short (12-char alphanumeric)" },
+        prefix: { type: "string", description: "Custom prefix for 'prefixed' format (default: 'req')" },
+        count: { type: "number", description: "Number of IDs to generate (1-20, default 1)" }
+      }
+    }
+  },
+  {
+    name: "api_error",
+    description: "Generate a standard API error response body (RFC 7807 Problem Details format)",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: { type: "number", description: "HTTP status code (e.g. 404)" },
+        title: { type: "string", description: "Short error title" },
+        detail: { type: "string", description: "Detailed error description" },
+        instance: { type: "string", description: "URI reference identifying the specific occurrence" }
+      },
+      required: ["status"]
+    }
+  },
+  {
+    name: "rate_limit_headers",
+    description: "Generate standard rate limit response headers (X-RateLimit-* and Retry-After)",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Max requests per window (default 100)" },
+        remaining: { type: "number", description: "Remaining requests in window (default 99)" },
+        windowSeconds: { type: "number", description: "Window duration in seconds (default 3600)" },
+        retryAfter: { type: "number", description: "Seconds until rate limit resets (omit if not rate limited)" }
+      }
+    }
+  },
+  {
+    name: "form_encode",
+    description: "Encode a JSON object as application/x-www-form-urlencoded, or decode form data back to JSON",
+    inputSchema: {
+      type: "object",
+      properties: {
+        input: { type: "string", description: "JSON object to encode, or URL-encoded form string to decode" },
+        action: { type: "string", enum: ["encode", "decode"], description: "Action: encode (default) or decode" }
+      },
+      required: ["input"]
+    }
   }
 ];
 
@@ -298,6 +371,117 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return { content: [{ type: "text", text: `Parsed query parameters:\n${JSON.stringify(result, null, 2)}` }] };
     }
 
+    case "url_parse": {
+      try {
+        const u = new URL(args.url);
+        const params = {};
+        for (const [k, v] of u.searchParams) {
+          if (params[k]) params[k] = Array.isArray(params[k]) ? [...params[k], v] : [params[k], v];
+          else params[k] = v;
+        }
+        const result = {
+          href: u.href,
+          origin: u.origin,
+          protocol: u.protocol,
+          host: u.host,
+          hostname: u.hostname,
+          port: u.port || "(default)",
+          pathname: u.pathname,
+          search: u.search,
+          searchParams: params,
+          hash: u.hash,
+          username: u.username || undefined,
+          password: u.password || undefined,
+        };
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch {
+        return { content: [{ type: "text", text: `Invalid URL: "${args.url}". Provide a full URL (e.g. https://example.com/path?key=val).` }], isError: true };
+      }
+    }
+
+    case "bearer_token": {
+      return { content: [{ type: "text", text: `Authorization: Bearer ${args.token}\n\n⚠️ Bearer tokens should be transmitted over HTTPS only.` }] };
+    }
+
+    case "request_id": {
+      const fmt = args.format || "uuid";
+      const count = Math.max(1, Math.min(20, args.count || 1));
+      const ids = [];
+      for (let i = 0; i < count; i++) {
+        if (fmt === "uuid") {
+          ids.push(crypto.randomUUID());
+        } else if (fmt === "prefixed") {
+          const prefix = args.prefix || "req";
+          ids.push(`${prefix}_${crypto.randomUUID().replace(/-/g, "").slice(0, 20)}`);
+        } else {
+          const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+          let id = "";
+          for (let j = 0; j < 12; j++) id += chars[Math.floor(Math.random() * chars.length)];
+          ids.push(id);
+        }
+      }
+      const header = count === 1
+        ? `X-Request-ID: ${ids[0]}`
+        : ids.map((id, i) => `${i + 1}. ${id}`).join("\n");
+      return { content: [{ type: "text", text: header }] };
+    }
+
+    case "api_error": {
+      const status = args.status;
+      const info = HTTP_STATUSES[status];
+      const title = args.title || (info ? info[0] : "Error");
+      const detail = args.detail || (info ? info[1] : "An error occurred.");
+      const body = {
+        type: `about:blank`,
+        title,
+        status,
+        detail,
+      };
+      if (args.instance) body.instance = args.instance;
+      return { content: [{ type: "text", text: `Content-Type: application/problem+json\n\n${JSON.stringify(body, null, 2)}\n\nSee RFC 7807 for Problem Details specification.` }] };
+    }
+
+    case "rate_limit_headers": {
+      const limit = args.limit || 100;
+      const remaining = args.remaining ?? 99;
+      const windowSec = args.windowSeconds || 3600;
+      const resetTime = Math.floor(Date.now() / 1000) + windowSec;
+      const headers = [
+        `X-RateLimit-Limit: ${limit}`,
+        `X-RateLimit-Remaining: ${remaining}`,
+        `X-RateLimit-Reset: ${resetTime}`,
+      ];
+      if (args.retryAfter != null) {
+        headers.push(`Retry-After: ${args.retryAfter}`);
+      }
+      return { content: [{ type: "text", text: `Rate Limit Headers:\n\n${headers.join("\n")}\n\nWindow: ${windowSec}s | Limit: ${limit} req/window | Remaining: ${remaining}` }] };
+    }
+
+    case "form_encode": {
+      const action = args.action || "encode";
+      if (action === "encode") {
+        try {
+          const obj = JSON.parse(args.input);
+          const params = new URLSearchParams();
+          for (const [k, v] of Object.entries(obj)) {
+            if (Array.isArray(v)) v.forEach(item => params.append(k, String(item)));
+            else params.append(k, String(v));
+          }
+          return { content: [{ type: "text", text: `Content-Type: application/x-www-form-urlencoded\n\n${params.toString()}` }] };
+        } catch {
+          return { content: [{ type: "text", text: `Invalid JSON input. Provide a JSON object to encode.` }], isError: true };
+        }
+      } else {
+        const params = new URLSearchParams(args.input);
+        const result = {};
+        for (const [k, v] of params) {
+          if (result[k]) result[k] = Array.isArray(result[k]) ? [...result[k], v] : [result[k], v];
+          else result[k] = v;
+        }
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+    }
+
     default:
       return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-apitools",
-  "version": "1.0.5",
-  "description": "MCP server with API & web development utilities — HTTP status codes, MIME types, JWT creation, mock data generation, CORS headers, cookie parsing",
+  "version": "1.1.0",
+  "description": "MCP server with 14 API & web development utilities — HTTP status codes, MIME types, JWT creation, mock data, CORS headers, cookie parsing, URL parser, Bearer auth, request IDs, RFC 7807 errors, rate limit headers, form encoding",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -24,7 +24,15 @@
     "claude",
     "cursor",
     "developer-tools",
-    "rest-api"
+    "rest-api",
+    "url-parser",
+    "bearer-auth",
+    "request-id",
+    "rate-limit",
+    "rfc-7807",
+    "form-encode",
+    "distributed-tracing",
+    "ai-tools"
   ],
   "author": "Hong Teoh",
   "license": "MIT",
@@ -34,5 +42,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hlteoh37/mcp-apitools.git"
+  },
+  "homepage": "https://github.com/hlteoh37/mcp-apitools#readme",
+  "bugs": {
+    "url": "https://github.com/hlteoh37/mcp-apitools/issues"
   }
 }