mcp-tool/generate-parameter-documentation.js

#!/usr/bin/env node

/**
 * @fileoverview Generate comprehensive parameter documentation for all MCP tools
 * Extracts parameter schemas from endpoints.js and formats them for documentation
 */

import {
  PUBLIC_ENDPOINTS,
  PROVIDER_ENDPOINTS,
  PATIENT_ENDPOINTS,
  PARTNER_ENDPOINTS,
  AFFILIATE_ENDPOINTS,
  NETWORK_ENDPOINTS,
  ENDPOINT_CATEGORIES,
} from "./src/config/endpoints.js";

/**
 * Generate tool name from endpoint and auth type
 */
function generateToolName(endpoint, authType) {
  const action = getActionFromMethod(endpoint.method);
  const resource = getResourceFromPath(endpoint.path);

  if (authType === "public") {
    return `public_${action}_${resource}`;
  }

  return `${authType}_${action}_${resource}`;
}

/**
 * Get action from HTTP method
 */
function getActionFromMethod(method) {
  const methodMap = {
    GET: "get",
    POST: "create",
    PUT: "update",
    DELETE: "delete",
    PATCH: "update",
    ANY: "manage",
  };

  return methodMap[method.toUpperCase()] || "manage";
}

/**
 * Get resource name from path
 */
function getResourceFromPath(path) {
  // Remove leading slash and api prefix
  let cleanPath = path.replace(/^\/api\//, "").replace(/^\//, "");

  // Remove path parameters
  cleanPath = cleanPath.replace(/\{[^}]+\}/g, "");

  // Split by slashes and take meaningful parts
  const parts = cleanPath.split("/").filter((part) => part && part.length > 0);

  // Join parts with camelCase
  return parts
    .map((part, index) => {
      if (index === 0) return part;
      return part.charAt(0).toUpperCase() + part.slice(1);
    })
    .join("");
}

/**
 * Format parameter documentation for a single parameter
 */
function formatParameter(paramName, paramConfig) {
  const type = paramConfig.type || "string";
  const required = paramConfig.required ? "required" : "optional";
  const description = paramConfig.description || "No description provided";

  let formattedParam = `- **${paramName}** (${type}, ${required}): ${description}`;

  // Add additional details if available
  if (paramConfig.default !== undefined) {
    formattedParam += ` (default: ${paramConfig.default})`;
  }

  if (paramConfig.enum) {
    formattedParam += ` (values: ${paramConfig.enum.join(", ")})`;
  }

  if (paramConfig.min !== undefined || paramConfig.max !== undefined) {
    const range = [];
    if (paramConfig.min !== undefined) range.push(`min: ${paramConfig.min}`);
    if (paramConfig.max !== undefined) range.push(`max: ${paramConfig.max}`);
    formattedParam += ` (${range.join(", ")})`;
  }

  if (paramConfig.format) {
    formattedParam += ` (format: ${paramConfig.format})`;
  }

  return formattedParam;
}

/**
 * Format all parameters for an endpoint
 */
function formatEndpointParameters(endpoint) {
  if (!endpoint.parameters || Object.keys(endpoint.parameters).length === 0) {
    return "No parameters required";
  }

  const parameterDocs = [];

  // Separate required and optional parameters
  const requiredParams = [];
  const optionalParams = [];

  Object.entries(endpoint.parameters).forEach(([paramName, paramConfig]) => {
    const formattedParam = formatParameter(paramName, paramConfig);
    if (paramConfig.required) {
      requiredParams.push(formattedParam);
    } else {
      optionalParams.push(formattedParam);
    }
  });

  // Add required parameters first
  if (requiredParams.length > 0) {
    parameterDocs.push("**Required Parameters:**");
    parameterDocs.push(...requiredParams);
  }

  // Add optional parameters
  if (optionalParams.length > 0) {
    if (requiredParams.length > 0) {
      parameterDocs.push("");
    }
    parameterDocs.push("**Optional Parameters:**");
    parameterDocs.push(...optionalParams);
  }

  return parameterDocs.join("\n");
}

/**
 * Generate tool documentation with parameters for a set of endpoints
 */
function generateToolDocumentation(endpoints, authType) {
  const documentation = [];

  // Group endpoints by category
  const categorizedEndpoints = {};

  endpoints.forEach((endpoint) => {
    const category = endpoint.category || "undefined";
    if (!categorizedEndpoints[category]) {
      categorizedEndpoints[category] = [];
    }
    categorizedEndpoints[category].push(endpoint);
  });

  // Generate documentation for each category
  Object.entries(categorizedEndpoints).forEach(
    ([category, categoryEndpoints]) => {
      const categoryName = category
        .split("_")
        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
        .join(" ");

      documentation.push(`### ${categoryName}`);
      documentation.push("");

      categoryEndpoints.forEach((endpoint) => {
        const toolName = generateToolName(endpoint, authType);

        documentation.push(`#### \`${toolName}\``);
        documentation.push("");
        documentation.push(`**Method:** ${endpoint.method}`);
        documentation.push(`**Endpoint:** \`${endpoint.path}\``);
        documentation.push(`**Description:** ${endpoint.description}`);
        documentation.push("");
        documentation.push("**Parameters:**");
        documentation.push("");
        documentation.push(formatEndpointParameters(endpoint));
        documentation.push("");
        documentation.push("---");
        documentation.push("");
      });
    }
  );

  return documentation.join("\n");
}

/**
 * Main function to generate complete parameter documentation
 */
function generateCompleteParameterDocumentation() {
  console.log(
    "📋 Generating comprehensive parameter documentation for all MCP tools...\n"
  );

  const documentation = [];

  // Header
  documentation.push("# MCP Tools Parameter Reference");
  documentation.push("");
  documentation.push(
    "Complete parameter documentation for all 175 MCP tools in the Laravel Healthcare MCP Server."
  );
  documentation.push("");
  documentation.push("---");
  documentation.push("");

  // Public Tools
  if (PUBLIC_ENDPOINTS.length > 0) {
    documentation.push(`## Public Tools (${PUBLIC_ENDPOINTS.length} tools)`);
    documentation.push("");
    documentation.push(
      "Public tools require no authentication and are accessible without any credentials."
    );
    documentation.push("");
    documentation.push(generateToolDocumentation(PUBLIC_ENDPOINTS, "public"));
  }

  // Provider Tools
  if (PROVIDER_ENDPOINTS.length > 0) {
    documentation.push(
      `## Provider Tools (${PROVIDER_ENDPOINTS.length} tools)`
    );
    documentation.push("");
    documentation.push(
      "Provider tools require Sanctum authentication with a valid provider token."
    );
    documentation.push("");
    documentation.push(
      generateToolDocumentation(PROVIDER_ENDPOINTS, "provider")
    );
  }

  // Patient Tools
  if (PATIENT_ENDPOINTS && PATIENT_ENDPOINTS.length > 0) {
    documentation.push(`## Patient Tools (${PATIENT_ENDPOINTS.length} tools)`);
    documentation.push("");
    documentation.push("Patient tools require patient portal authentication.");
    documentation.push("");
    documentation.push(generateToolDocumentation(PATIENT_ENDPOINTS, "patient"));
  }

  // Partner Tools
  if (PARTNER_ENDPOINTS && PARTNER_ENDPOINTS.length > 0) {
    documentation.push(`## Partner Tools (${PARTNER_ENDPOINTS.length} tools)`);
    documentation.push("");
    documentation.push(
      "Partner tools require partner business authentication."
    );
    documentation.push("");
    documentation.push(generateToolDocumentation(PARTNER_ENDPOINTS, "partner"));
  }

  // Affiliate Tools
  if (AFFILIATE_ENDPOINTS && AFFILIATE_ENDPOINTS.length > 0) {
    documentation.push(
      `## Affiliate Tools (${AFFILIATE_ENDPOINTS.length} tools)`
    );
    documentation.push("");
    documentation.push(
      "Affiliate tools require affiliate business authentication."
    );
    documentation.push("");
    documentation.push(
      generateToolDocumentation(AFFILIATE_ENDPOINTS, "affiliate")
    );
  }

  // Network Tools
  if (NETWORK_ENDPOINTS && NETWORK_ENDPOINTS.length > 0) {
    documentation.push(`## Network Tools (${NETWORK_ENDPOINTS.length} tools)`);
    documentation.push("");
    documentation.push(
      "Network tools require network business authentication."
    );
    documentation.push("");
    documentation.push(generateToolDocumentation(NETWORK_ENDPOINTS, "network"));
  }

  return documentation.join("\n");
}

// Generate and output the documentation
const parameterDocumentation = generateCompleteParameterDocumentation();
console.log(parameterDocumentation);

console.log("\n=== PARAMETER DOCUMENTATION GENERATED ===");
console.log(
  "Copy the output above to create a comprehensive parameter reference document"
);