first

generate-parameter-documentation.js

@@ -0,0 +1,296 @@
+#!/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"
+);