@rog0x/mcp-api-tools 1.0.0

package/dist/tools/header-analyzer.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeHeaders = analyzeHeaders;
+function get(headers, key) {
+    const lower = key.toLowerCase();
+    for (const [k, v] of Object.entries(headers)) {
+        if (k.toLowerCase() === lower)
+            return v;
+    }
+    return null;
+}
+function analyzeSecurityHeaders(headers) {
+    const checks = [];
+    let score = 0;
+    const maxScore = 7;
+    const securityHeaders = [
+        {
+            header: "strict-transport-security",
+            name: "Strict-Transport-Security (HSTS)",
+            recommendation: "Add HSTS header with max-age of at least 31536000",
+        },
+        {
+            header: "content-security-policy",
+            name: "Content-Security-Policy (CSP)",
+            recommendation: "Define a Content-Security-Policy to prevent XSS attacks",
+        },
+        {
+            header: "x-frame-options",
+            name: "X-Frame-Options",
+            recommendation: "Set to DENY or SAMEORIGIN to prevent clickjacking",
+        },
+        {
+            header: "x-content-type-options",
+            name: "X-Content-Type-Options",
+            recommendation: "Set to nosniff to prevent MIME type sniffing",
+        },
+        {
+            header: "referrer-policy",
+            name: "Referrer-Policy",
+            recommendation: "Set to strict-origin-when-cross-origin or no-referrer",
+        },
+        {
+            header: "permissions-policy",
+            name: "Permissions-Policy",
+            recommendation: "Restrict browser features with Permissions-Policy",
+        },
+        {
+            header: "x-xss-protection",
+            name: "X-XSS-Protection",
+            recommendation: "Set to 1; mode=block (legacy protection for older browsers)",
+        },
+    ];
+    for (const sh of securityHeaders) {
+        const value = get(headers, sh.header);
+        const present = value !== null;
+        if (present)
+            score++;
+        checks.push({
+            header: sh.name,
+            present,
+            value,
+            recommendation: present ? "Present" : sh.recommendation,
+        });
+    }
+    const pct = (score / maxScore) * 100;
+    let grade;
+    if (pct >= 85)
+        grade = "A";
+    else if (pct >= 70)
+        grade = "B";
+    else if (pct >= 50)
+        grade = "C";
+    else if (pct >= 30)
+        grade = "D";
+    else
+        grade = "F";
+    return { score, max_score: maxScore, grade, checks };
+}
+function analyzeCaching(headers) {
+    const cacheControl = get(headers, "cache-control");
+    const etag = get(headers, "etag");
+    const lastModified = get(headers, "last-modified");
+    const expires = get(headers, "expires");
+    const age = get(headers, "age");
+    const pragma = get(headers, "pragma");
+    const isNoCacheOrNoStore = cacheControl !== null &&
+        (cacheControl.includes("no-store") || cacheControl.includes("no-cache"));
+    const isCacheable = !isNoCacheOrNoStore && (cacheControl !== null || etag !== null || expires !== null);
+    let summary;
+    if (isNoCacheOrNoStore) {
+        summary = "Response is explicitly not cached";
+    }
+    else if (isCacheable) {
+        summary = "Response appears cacheable";
+    }
+    else {
+        summary = "No explicit caching directives found";
+    }
+    return {
+        cache_control: cacheControl,
+        etag,
+        last_modified: lastModified,
+        expires,
+        age,
+        pragma,
+        is_cacheable: isCacheable,
+        summary,
+    };
+}
+function analyzeCors(headers) {
+    const origin = get(headers, "access-control-allow-origin");
+    const methods = get(headers, "access-control-allow-methods");
+    const allowHeaders = get(headers, "access-control-allow-headers");
+    const credentials = get(headers, "access-control-allow-credentials");
+    const expose = get(headers, "access-control-expose-headers");
+    const maxAge = get(headers, "access-control-max-age");
+    const isOpen = origin === "*";
+    let summary;
+    if (origin === null) {
+        summary = "No CORS headers present";
+    }
+    else if (isOpen && credentials === "true") {
+        summary = "WARNING: Open CORS with credentials allowed is a security risk";
+    }
+    else if (isOpen) {
+        summary = "CORS is open to all origins";
+    }
+    else {
+        summary = `CORS restricted to origin: ${origin}`;
+    }
+    return {
+        allow_origin: origin,
+        allow_methods: methods,
+        allow_headers: allowHeaders,
+        allow_credentials: credentials,
+        expose_headers: expose,
+        max_age: maxAge,
+        is_open: isOpen,
+        summary,
+    };
+}
+function analyzeCookies(headers) {
+    const cookies = [];
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() !== "set-cookie")
+            continue;
+        const parts = value.split(";").map((p) => p.trim());
+        const nameValue = parts[0];
+        const eqIndex = nameValue.indexOf("=");
+        const name = eqIndex >= 0 ? nameValue.slice(0, eqIndex) : nameValue;
+        const flags = parts.slice(1).map((p) => p.toLowerCase());
+        const getFlag = (prefix) => {
+            const f = flags.find((fl) => fl.startsWith(prefix));
+            if (!f)
+                return null;
+            const idx = f.indexOf("=");
+            return idx >= 0 ? f.slice(idx + 1).trim() : "";
+        };
+        cookies.push({
+            raw: value,
+            name,
+            secure: flags.some((f) => f === "secure"),
+            http_only: flags.some((f) => f === "httponly"),
+            same_site: getFlag("samesite"),
+            path: getFlag("path"),
+            domain: getFlag("domain"),
+            expires: getFlag("expires"),
+            max_age: getFlag("max-age"),
+        });
+    }
+    return cookies;
+}
+function analyzeHeaders(headers) {
+    if (!headers || Object.keys(headers).length === 0) {
+        throw new Error("Provide a non-empty headers object to analyze");
+    }
+    return {
+        raw_headers: headers,
+        security: analyzeSecurityHeaders(headers),
+        caching: analyzeCaching(headers),
+        cors: analyzeCors(headers),
+        cookies: analyzeCookies(headers),
+        server_info: {
+            server: get(headers, "server"),
+            powered_by: get(headers, "x-powered-by"),
+        },
+    };
+}
+//# sourceMappingURL=header-analyzer.js.map

package/dist/tools/http-request.d.ts

@@ -0,0 +1,29 @@
+export interface HttpRequestParams {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: string;
+    timeout?: number;
+    follow_redirects?: boolean;
+    auth?: {
+        type: "basic" | "bearer";
+        username?: string;
+        password?: string;
+        token?: string;
+    };
+}
+export interface HttpRequestResult {
+    status: number;
+    status_text: string;
+    headers: Record<string, string>;
+    body: string;
+    timing: {
+        start_ms: number;
+        end_ms: number;
+        duration_ms: number;
+    };
+    redirected: boolean;
+    final_url: string;
+}
+export declare function httpRequest(params: HttpRequestParams): Promise<HttpRequestResult>;
+//# sourceMappingURL=http-request.d.ts.map

package/dist/tools/http-request.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpRequest = httpRequest;
+async function httpRequest(params) {
+    const { method, url, headers = {}, body, timeout = 30000, follow_redirects = true, auth, } = params;
+    const upperMethod = method.toUpperCase();
+    const validMethods = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];
+    if (!validMethods.includes(upperMethod)) {
+        throw new Error(`Invalid HTTP method: ${method}. Supported: ${validMethods.join(", ")}`);
+    }
+    try {
+        new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid URL: ${url}`);
+    }
+    const requestHeaders = { ...headers };
+    if (auth) {
+        if (auth.type === "basic" && auth.username && auth.password) {
+            const encoded = Buffer.from(`${auth.username}:${auth.password}`).toString("base64");
+            requestHeaders["Authorization"] = `Basic ${encoded}`;
+        }
+        else if (auth.type === "bearer" && auth.token) {
+            requestHeaders["Authorization"] = `Bearer ${auth.token}`;
+        }
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    const startMs = Date.now();
+    try {
+        const response = await fetch(url, {
+            method: upperMethod,
+            headers: requestHeaders,
+            body: upperMethod !== "GET" && upperMethod !== "HEAD" ? body : undefined,
+            signal: controller.signal,
+            redirect: follow_redirects ? "follow" : "manual",
+        });
+        const responseBody = await response.text();
+        const endMs = Date.now();
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        return {
+            status: response.status,
+            status_text: response.statusText,
+            headers: responseHeaders,
+            body: responseBody.length > 50000
+                ? responseBody.slice(0, 50000) + "\n...[truncated]"
+                : responseBody,
+            timing: {
+                start_ms: startMs,
+                end_ms: endMs,
+                duration_ms: endMs - startMs,
+            },
+            redirected: response.redirected,
+            final_url: response.url,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=http-request.js.map

package/dist/tools/jwt-decode.d.ts

@@ -0,0 +1,12 @@
+export interface JwtDecodeResult {
+    header: Record<string, unknown>;
+    payload: Record<string, unknown>;
+    signature_present: boolean;
+    issued_at: string | null;
+    expires_at: string | null;
+    not_before: string | null;
+    is_expired: boolean;
+    time_until_expiry: string | null;
+}
+export declare function jwtDecode(token: string): JwtDecodeResult;
+//# sourceMappingURL=jwt-decode.d.ts.map

package/dist/tools/jwt-decode.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jwtDecode = jwtDecode;
+function base64UrlDecode(input) {
+    let base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+    const padding = base64.length % 4;
+    if (padding === 2)
+        base64 += "==";
+    else if (padding === 3)
+        base64 += "=";
+    return Buffer.from(base64, "base64").toString("utf-8");
+}
+function formatDuration(ms) {
+    if (ms <= 0)
+        return "expired";
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    const parts = [];
+    if (days > 0)
+        parts.push(`${days}d`);
+    if (hours % 24 > 0)
+        parts.push(`${hours % 24}h`);
+    if (minutes % 60 > 0)
+        parts.push(`${minutes % 60}m`);
+    if (seconds % 60 > 0 && days === 0)
+        parts.push(`${seconds % 60}s`);
+    return parts.join(" ") || "0s";
+}
+function timestampToIso(ts) {
+    if (typeof ts !== "number")
+        return null;
+    return new Date(ts * 1000).toISOString();
+}
+function jwtDecode(token) {
+    const trimmed = token.trim();
+    const parts = trimmed.split(".");
+    if (parts.length < 2 || parts.length > 3) {
+        throw new Error(`Invalid JWT: expected 2 or 3 parts separated by dots, got ${parts.length}`);
+    }
+    let header;
+    let payload;
+    try {
+        header = JSON.parse(base64UrlDecode(parts[0]));
+    }
+    catch {
+        throw new Error("Invalid JWT: unable to decode header");
+    }
+    try {
+        payload = JSON.parse(base64UrlDecode(parts[1]));
+    }
+    catch {
+        throw new Error("Invalid JWT: unable to decode payload");
+    }
+    const now = Date.now();
+    const exp = typeof payload.exp === "number" ? payload.exp * 1000 : null;
+    const isExpired = exp !== null ? now > exp : false;
+    const timeUntilExpiry = exp !== null ? formatDuration(exp - now) : null;
+    return {
+        header,
+        payload,
+        signature_present: parts.length === 3 && parts[2].length > 0,
+        issued_at: timestampToIso(payload.iat),
+        expires_at: timestampToIso(payload.exp),
+        not_before: timestampToIso(payload.nbf),
+        is_expired: isExpired,
+        time_until_expiry: timeUntilExpiry,
+    };
+}
+//# sourceMappingURL=jwt-decode.js.map

package/dist/tools/url-parser.d.ts

@@ -0,0 +1,27 @@
+export interface ParsedUrl {
+    href: string;
+    protocol: string;
+    host: string;
+    hostname: string;
+    port: string;
+    pathname: string;
+    search: string;
+    query_params: Record<string, string | string[]>;
+    hash: string;
+    origin: string;
+    username: string;
+    password: string;
+}
+export interface BuildUrlParams {
+    protocol?: string;
+    hostname: string;
+    port?: string | number;
+    pathname?: string;
+    query_params?: Record<string, string | string[]>;
+    hash?: string;
+    username?: string;
+    password?: string;
+}
+export declare function parseUrl(url: string): ParsedUrl;
+export declare function buildUrl(params: BuildUrlParams): string;
+//# sourceMappingURL=url-parser.d.ts.map

package/dist/tools/url-parser.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseUrl = parseUrl;
+exports.buildUrl = buildUrl;
+function parseUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid URL: ${url}`);
+    }
+    const queryParams = {};
+    parsed.searchParams.forEach((value, key) => {
+        const existing = queryParams[key];
+        if (existing === undefined) {
+            queryParams[key] = value;
+        }
+        else if (Array.isArray(existing)) {
+            existing.push(value);
+        }
+        else {
+            queryParams[key] = [existing, value];
+        }
+    });
+    return {
+        href: parsed.href,
+        protocol: parsed.protocol,
+        host: parsed.host,
+        hostname: parsed.hostname,
+        port: parsed.port,
+        pathname: parsed.pathname,
+        search: parsed.search,
+        query_params: queryParams,
+        hash: parsed.hash,
+        origin: parsed.origin,
+        username: parsed.username,
+        password: parsed.password,
+    };
+}
+function buildUrl(params) {
+    const { protocol = "https:", hostname, port, pathname = "/", query_params, hash, username, password, } = params;
+    if (!hostname) {
+        throw new Error("hostname is required to build a URL");
+    }
+    const proto = protocol.endsWith(":") ? protocol : protocol + ":";
+    const url = new URL(`${proto}//${hostname}`);
+    if (port !== undefined && port !== "") {
+        url.port = String(port);
+    }
+    url.pathname = pathname;
+    if (query_params) {
+        for (const [key, value] of Object.entries(query_params)) {
+            if (Array.isArray(value)) {
+                for (const v of value) {
+                    url.searchParams.append(key, v);
+                }
+            }
+            else {
+                url.searchParams.set(key, value);
+            }
+        }
+    }
+    if (hash) {
+        url.hash = hash.startsWith("#") ? hash : `#${hash}`;
+    }
+    if (username)
+        url.username = username;
+    if (password)
+        url.password = password;
+    return url.href;
+}
+//# sourceMappingURL=url-parser.js.map

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@rog0x/mcp-api-tools",
+  "version": "1.0.0",
+  "description": "HTTP/API testing tools for AI agents via MCP",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "api",
+    "http",
+    "testing",
+    "tools"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  }
+}