@rog0x/mcp-api-tools 1.0.0

package/README.md

@@ -0,0 +1,81 @@
+# @rog0x/mcp-api-tools
+
+HTTP/API testing tools for AI agents, built on the [Model Context Protocol](https://modelcontextprotocol.io).
+
+## Tools
+
+### `http_request`
+Make any HTTP request (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) with full control over headers, body, authentication, and timeouts. Returns status code, response headers, body, and timing information.
+
+### `api_health`
+Check the health of multiple API endpoints in parallel. Returns HTTP status, response time, SSL certificate validity and expiry, and optional response body validation. Includes a summary with counts of healthy, unhealthy, and errored endpoints.
+
+### `jwt_decode`
+Decode a JWT token without cryptographic verification. Returns the decoded header and payload, issued-at time, expiry time, and whether the token is currently expired.
+
+### `url_parse`
+Parse a URL into its component parts (protocol, host, port, path, query parameters, hash) or build a URL from individual parts.
+
+### `header_analyzer`
+Analyze HTTP response headers for security posture (HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy), caching directives, CORS configuration, and cookie attributes. Provides a letter grade for security. Can fetch headers from a live URL or analyze a provided headers object.
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "api-tools": {
+      "command": "node",
+      "args": ["D:/products/mcp-servers/mcp-api-tools/dist/index.js"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add api-tools node D:/products/mcp-servers/mcp-api-tools/dist/index.js
+```
+
+## Examples
+
+**Make a POST request:**
+```
+Use http_request to POST to https://httpbin.org/post with JSON body {"key": "value"}
+```
+
+**Check API health:**
+```
+Use api_health to check these endpoints: https://api.github.com, https://httpbin.org/get
+```
+
+**Decode a JWT:**
+```
+Use jwt_decode to decode this token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+**Parse a URL:**
+```
+Use url_parse to break down https://example.com:8080/api/v1?key=value&debug=true#section
+```
+
+**Analyze security headers:**
+```
+Use header_analyzer to check security headers for https://github.com
+```
+
+## 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,269 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const http_request_js_1 = require("./tools/http-request.js");
+const api_health_js_1 = require("./tools/api-health.js");
+const jwt_decode_js_1 = require("./tools/jwt-decode.js");
+const url_parser_js_1 = require("./tools/url-parser.js");
+const header_analyzer_js_1 = require("./tools/header-analyzer.js");
+const server = new index_js_1.Server({
+    name: "mcp-api-tools",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "http_request",
+            description: "Make an HTTP request with full control over method, headers, body, authentication, and timeouts. Returns status, headers, body, and timing information.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    method: {
+                        type: "string",
+                        description: "HTTP method: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS",
+                    },
+                    url: {
+                        type: "string",
+                        description: "The full URL to send the request to",
+                    },
+                    headers: {
+                        type: "object",
+                        description: "Key-value pairs of HTTP headers to include",
+                        additionalProperties: { type: "string" },
+                    },
+                    body: {
+                        type: "string",
+                        description: "Request body (for POST, PUT, PATCH)",
+                    },
+                    timeout: {
+                        type: "number",
+                        description: "Request timeout in milliseconds (default: 30000)",
+                    },
+                    follow_redirects: {
+                        type: "boolean",
+                        description: "Whether to follow redirects (default: true)",
+                    },
+                    auth: {
+                        type: "object",
+                        description: "Authentication configuration",
+                        properties: {
+                            type: {
+                                type: "string",
+                                enum: ["basic", "bearer"],
+                                description: "Auth type: basic or bearer",
+                            },
+                            username: { type: "string", description: "Username for basic auth" },
+                            password: { type: "string", description: "Password for basic auth" },
+                            token: { type: "string", description: "Token for bearer auth" },
+                        },
+                        required: ["type"],
+                    },
+                },
+                required: ["method", "url"],
+            },
+        },
+        {
+            name: "api_health",
+            description: "Check the health of multiple API endpoints. Returns status, response time, SSL certificate validity, and optional response body validation for each endpoint.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    endpoints: {
+                        type: "array",
+                        description: "Array of endpoints to check (max 20)",
+                        items: {
+                            type: "object",
+                            properties: {
+                                url: { type: "string", description: "Endpoint URL" },
+                                expected_status: {
+                                    type: "number",
+                                    description: "Expected HTTP status code (default: 200)",
+                                },
+                                expected_body_contains: {
+                                    type: "string",
+                                    description: "String the response body must contain",
+                                },
+                            },
+                            required: ["url"],
+                        },
+                    },
+                },
+                required: ["endpoints"],
+            },
+        },
+        {
+            name: "jwt_decode",
+            description: "Decode a JWT token without verification. Returns header, payload, expiry, issued-at time, and whether the token is expired.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    token: {
+                        type: "string",
+                        description: "The JWT token string to decode",
+                    },
+                },
+                required: ["token"],
+            },
+        },
+        {
+            name: "url_parse",
+            description: "Parse a URL into its component parts: protocol, host, port, path, query parameters, hash, and more. Can also build a URL from parts.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    url: {
+                        type: "string",
+                        description: "URL to parse (use this OR build_params, not both)",
+                    },
+                    build_params: {
+                        type: "object",
+                        description: "Build a URL from parts instead of parsing",
+                        properties: {
+                            protocol: { type: "string", description: "Protocol (default: https:)" },
+                            hostname: { type: "string", description: "Hostname (required)" },
+                            port: { type: "string", description: "Port number" },
+                            pathname: { type: "string", description: "Path (default: /)" },
+                            query_params: {
+                                type: "object",
+                                description: "Query parameters as key-value pairs",
+                                additionalProperties: {
+                                    oneOf: [
+                                        { type: "string" },
+                                        { type: "array", items: { type: "string" } },
+                                    ],
+                                },
+                            },
+                            hash: { type: "string", description: "Hash/fragment" },
+                            username: { type: "string", description: "URL username" },
+                            password: { type: "string", description: "URL password" },
+                        },
+                        required: ["hostname"],
+                    },
+                },
+            },
+        },
+        {
+            name: "header_analyzer",
+            description: "Analyze HTTP response headers for security (HSTS, CSP, X-Frame-Options, etc.), caching directives, CORS configuration, cookies, and server information. Provides a security grade.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    headers: {
+                        type: "object",
+                        description: "HTTP response headers as key-value pairs to analyze",
+                        additionalProperties: { type: "string" },
+                    },
+                    url: {
+                        type: "string",
+                        description: "Alternatively, provide a URL to fetch and analyze its response headers",
+                    },
+                },
+            },
+        },
+    ],
+}));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "http_request": {
+                const result = await (0, http_request_js_1.httpRequest)({
+                    method: args?.method,
+                    url: args?.url,
+                    headers: args?.headers,
+                    body: args?.body,
+                    timeout: args?.timeout,
+                    follow_redirects: args?.follow_redirects,
+                    auth: args?.auth,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "api_health": {
+                const endpoints = args?.endpoints;
+                const result = await (0, api_health_js_1.apiHealth)(endpoints);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "jwt_decode": {
+                const result = (0, jwt_decode_js_1.jwtDecode)(args?.token);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "url_parse": {
+                if (args?.build_params) {
+                    const built = (0, url_parser_js_1.buildUrl)(args.build_params);
+                    return {
+                        content: [
+                            { type: "text", text: JSON.stringify({ built_url: built }, null, 2) },
+                        ],
+                    };
+                }
+                if (args?.url) {
+                    const parsed = (0, url_parser_js_1.parseUrl)(args.url);
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(parsed, null, 2) }],
+                    };
+                }
+                throw new Error("Provide either 'url' to parse or 'build_params' to build");
+            }
+            case "header_analyzer": {
+                if (args?.url) {
+                    const controller = new AbortController();
+                    const timer = setTimeout(() => controller.abort(), 15000);
+                    try {
+                        const response = await fetch(args.url, {
+                            method: "HEAD",
+                            signal: controller.signal,
+                            redirect: "follow",
+                        });
+                        const fetchedHeaders = {};
+                        response.headers.forEach((value, key) => {
+                            fetchedHeaders[key] = value;
+                        });
+                        const result = (0, header_analyzer_js_1.analyzeHeaders)(fetchedHeaders);
+                        return {
+                            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
+                    finally {
+                        clearTimeout(timer);
+                    }
+                }
+                if (args?.headers) {
+                    const result = (0, header_analyzer_js_1.analyzeHeaders)(args.headers);
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                    };
+                }
+                throw new Error("Provide either 'headers' object or 'url' to fetch headers from");
+            }
+            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,
+        };
+    }
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP API Tools server running on stdio");
+}
+main().catch(console.error);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,31 @@
+export interface HealthEndpoint {
+    url: string;
+    expected_status?: number;
+    expected_body_contains?: string;
+}
+export interface EndpointHealth {
+    url: string;
+    status: "healthy" | "unhealthy" | "error";
+    http_status: number | null;
+    response_time_ms: number;
+    ssl: SslInfo | null;
+    body_valid: boolean | null;
+    error: string | null;
+}
+export interface SslInfo {
+    valid: boolean;
+    issuer: string;
+    subject: string;
+    expires: string;
+    days_remaining: number;
+}
+export declare function apiHealth(endpoints: HealthEndpoint[]): Promise<{
+    results: EndpointHealth[];
+    summary: {
+        total: number;
+        healthy: number;
+        unhealthy: number;
+        errors: number;
+    };
+}>;
+//# sourceMappingURL=api-health.d.ts.map

package/dist/tools/api-health.js

@@ -0,0 +1,167 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiHealth = apiHealth;
+const tls = __importStar(require("node:tls"));
+function checkSsl(hostname, port) {
+    return new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            socket.destroy();
+            resolve(null);
+        }, 5000);
+        const socket = tls.connect({ host: hostname, port, servername: hostname }, () => {
+            clearTimeout(timeout);
+            const cert = socket.getPeerCertificate();
+            if (!cert || !cert.valid_to) {
+                socket.destroy();
+                resolve(null);
+                return;
+            }
+            const expiresDate = new Date(cert.valid_to);
+            const now = new Date();
+            const daysRemaining = Math.floor((expiresDate.getTime() - now.getTime()) / (1000 * 60 * 60 * 24));
+            const flatten = (val) => {
+                if (!val)
+                    return "Unknown";
+                return Array.isArray(val) ? val[0] : val;
+            };
+            resolve({
+                valid: socket.authorized,
+                issuer: typeof cert.issuer === "object"
+                    ? flatten(cert.issuer.O) !== "Unknown"
+                        ? flatten(cert.issuer.O)
+                        : flatten(cert.issuer.CN)
+                    : "Unknown",
+                subject: typeof cert.subject === "object"
+                    ? flatten(cert.subject.CN)
+                    : "Unknown",
+                expires: cert.valid_to,
+                days_remaining: daysRemaining,
+            });
+            socket.destroy();
+        });
+        socket.on("error", () => {
+            clearTimeout(timeout);
+            resolve(null);
+        });
+    });
+}
+async function checkEndpoint(endpoint) {
+    const { url, expected_status = 200, expected_body_contains } = endpoint;
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(url);
+    }
+    catch {
+        return {
+            url,
+            status: "error",
+            http_status: null,
+            response_time_ms: 0,
+            ssl: null,
+            body_valid: null,
+            error: "Invalid URL",
+        };
+    }
+    const isHttps = parsedUrl.protocol === "https:";
+    const sslPromise = isHttps
+        ? checkSsl(parsedUrl.hostname, Number(parsedUrl.port) || 443)
+        : Promise.resolve(null);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 15000);
+    const start = Date.now();
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            signal: controller.signal,
+            redirect: "follow",
+        });
+        const body = await response.text();
+        const elapsed = Date.now() - start;
+        let bodyValid = null;
+        if (expected_body_contains) {
+            bodyValid = body.includes(expected_body_contains);
+        }
+        const isHealthy = response.status === expected_status &&
+            (bodyValid === null || bodyValid === true);
+        const ssl = await sslPromise;
+        return {
+            url,
+            status: isHealthy ? "healthy" : "unhealthy",
+            http_status: response.status,
+            response_time_ms: elapsed,
+            ssl,
+            body_valid: bodyValid,
+            error: null,
+        };
+    }
+    catch (err) {
+        const elapsed = Date.now() - start;
+        const ssl = await sslPromise;
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            url,
+            status: "error",
+            http_status: null,
+            response_time_ms: elapsed,
+            ssl,
+            body_valid: null,
+            error: message,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function apiHealth(endpoints) {
+    if (!endpoints || endpoints.length === 0) {
+        throw new Error("Provide at least one endpoint to check");
+    }
+    const capped = endpoints.slice(0, 20);
+    const results = await Promise.all(capped.map(checkEndpoint));
+    const healthy = results.filter((r) => r.status === "healthy").length;
+    const unhealthy = results.filter((r) => r.status === "unhealthy").length;
+    const errors = results.filter((r) => r.status === "error").length;
+    return {
+        results,
+        summary: {
+            total: results.length,
+            healthy,
+            unhealthy,
+            errors,
+        },
+    };
+}
+//# sourceMappingURL=api-health.js.map

package/dist/tools/header-analyzer.d.ts

@@ -0,0 +1,56 @@
+export interface HeaderAnalysis {
+    raw_headers: Record<string, string>;
+    security: SecurityAnalysis;
+    caching: CachingAnalysis;
+    cors: CorsAnalysis;
+    cookies: CookieAnalysis[];
+    server_info: {
+        server: string | null;
+        powered_by: string | null;
+    };
+}
+export interface SecurityAnalysis {
+    score: number;
+    max_score: number;
+    grade: string;
+    checks: SecurityCheck[];
+}
+export interface SecurityCheck {
+    header: string;
+    present: boolean;
+    value: string | null;
+    recommendation: string;
+}
+export interface CachingAnalysis {
+    cache_control: string | null;
+    etag: string | null;
+    last_modified: string | null;
+    expires: string | null;
+    age: string | null;
+    pragma: string | null;
+    is_cacheable: boolean;
+    summary: string;
+}
+export interface CorsAnalysis {
+    allow_origin: string | null;
+    allow_methods: string | null;
+    allow_headers: string | null;
+    allow_credentials: string | null;
+    expose_headers: string | null;
+    max_age: string | null;
+    is_open: boolean;
+    summary: string;
+}
+export interface CookieAnalysis {
+    raw: string;
+    name: string;
+    secure: boolean;
+    http_only: boolean;
+    same_site: string | null;
+    path: string | null;
+    domain: string | null;
+    expires: string | null;
+    max_age: string | null;
+}
+export declare function analyzeHeaders(headers: Record<string, string>): HeaderAnalysis;
+//# sourceMappingURL=header-analyzer.d.ts.map