chore: builder proper api route for mcp clients

Author: boringContributor

package.json

@@ -6,7 +6,9 @@
     "docusaurus": "docusaurus",
     "dev": "docusaurus start",
     "start": "docusaurus start",
+    "prebuild": "npm run generate-api-discovery",
     "build": "docusaurus build",
+    "generate-api-discovery": "node scripts/generate-api-discovery.js",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",

redoc.config.js

@@ -1,3 +1,5 @@
+// Adding an API here also publishes it to static/openapi-specs/apis.json,
+// the discovery document used by MCP clients (npm run generate-api-discovery).
 module.exports.specs = [
   {
     layout: { title: 'Access Token API' },

scripts/generate-api-discovery.js

@@ -0,0 +1,151 @@
+/**
+ * Generates static/openapi-specs/apis.json — the discovery document consumed by
+ * openapi-analyzer-mcp (see docs/architecture/api-first.md).
+ *
+ * The API list comes from redoc.config.js so the discovery document always
+ * matches the published API reference. Each baseURL is read from the spec's own
+ * `servers` entry rather than being maintained here.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { specs } = require('../redoc.config');
+
+const OUTPUT_PATH = path.join(__dirname, '..', 'static', 'openapi-specs', 'apis.json');
+const CONCURRENCY = 8;
+
+/**
+ * Reads the first `servers[].url` out of an OpenAPI YAML document.
+ *
+ * Avoids a YAML dependency: `servers` is always a top-level key, so scan from it
+ * until the next top-level key and take the first `url`.
+ */
+function extractBaseURL(spec) {
+  const lines = spec.split('\n');
+  const start = lines.findIndex((line) => /^servers:/.test(line));
+
+  if (start === -1) return null;
+
+  for (const line of lines.slice(start + 1)) {
+    // A new top-level key ends the block; sequence items may sit at column 0 too.
+    if (/^[^\s-]/.test(line)) break;
+
+    const match = line.match(/^\s*-?\s*url:\s*(.+?)\s*$/);
+
+    if (match) return match[1].replace(/^['"]|['"]$/g, '');
+  }
+
+  return null;
+}
+
+async function resolveBaseURL(spec, previousBaseURL) {
+  const fallback = () => {
+    if (!previousBaseURL) return null;
+    console.warn(`  keeping previously known baseURL ${previousBaseURL}`);
+
+    return previousBaseURL;
+  };
+
+  let response;
+
+  try {
+    response = await fetch(spec.specUrl);
+  } catch (error) {
+    console.warn(`✗ ${spec.layout.title}: ${spec.specUrl} — ${error.message}`);
+
+    return fallback();
+  }
+
+  if (!response.ok) {
+    console.warn(`✗ ${spec.layout.title}: ${spec.specUrl} — HTTP ${response.status}`);
+
+    return fallback();
+  }
+
+  const baseURL = extractBaseURL(await response.text());
+
+  if (!baseURL) {
+    console.warn(`✗ ${spec.layout.title}: no servers entry in ${spec.specUrl}`);
+
+    return fallback();
+  }
+
+  return baseURL;
+}
+
+async function mapWithConcurrency(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+
+  const worker = async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await fn(items[index]);
+    }
+  };
+
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+
+  return results;
+}
+
+function readPreviousBaseURLs() {
+  try {
+    const previous = JSON.parse(fs.readFileSync(OUTPUT_PATH, 'utf8'));
+
+    return new Map(previous.apis.map((api) => [api.properties[0].url, api.baseURL]));
+  } catch {
+    return new Map();
+  }
+}
+
+async function main() {
+  const previousBaseURLs = readPreviousBaseURLs();
+
+  const apis = (
+    await mapWithConcurrency(specs, CONCURRENCY, async (spec) => {
+      const baseURL = await resolveBaseURL(spec, previousBaseURLs.get(spec.specUrl));
+
+      if (!baseURL) {
+        console.warn(`  skipping ${spec.layout.title} — no baseURL available`);
+
+        return null;
+      }
+
+      return {
+        name: spec.layout.title,
+        baseURL,
+        properties: [{ type: 'Swagger', url: spec.specUrl }],
+      };
+    })
+  ).filter(Boolean);
+
+  if (!apis.length) {
+    throw new Error('No APIs could be resolved — refusing to write an empty discovery document');
+  }
+
+  const document = {
+    name: 'Epilot APIs',
+    description: 'Collection of Epilot API specifications',
+    url: 'https://docs.epilot.io',
+    apis,
+  };
+
+  const contents = `${JSON.stringify(document, null, 2)}\n`;
+  const unchanged = fs.existsSync(OUTPUT_PATH) && fs.readFileSync(OUTPUT_PATH, 'utf8') === contents;
+
+  if (unchanged) {
+    console.log(`apis.json already up to date (${apis.length} APIs)`);
+
+    return;
+  }
+
+  fs.writeFileSync(OUTPUT_PATH, contents);
+  console.log(`Wrote apis.json with ${apis.length} of ${specs.length} APIs`);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

static/openapi-specs/apis.json

@@ -382,6 +382,86 @@
           "url": "https://docs.api.epilot.io/kanban.yaml"
         }
       ]
+    },
+    {
+      "name": "Validation Rules API",
+      "baseURL": "https://validation-rules.sls.epilot.io",
+      "properties": [
+        {
+          "type": "Swagger",
+          "url": "https://docs.api.epilot.io/validation-rules.yaml"
+        }
+      ]
+    },
+    {
+      "name": "Integration Toolkit API",
+      "baseURL": "https://integration-toolkit.sls.epilot.io",
+      "properties": [
+        {
+          "type": "Swagger",
+          "url": "https://docs.api.epilot.io/erp-integration.yaml"
+        }
+      ]
+    },
+    {
+      "name": "Environments API",
+      "baseURL": "https://environments.sls.epilot.io",
+      "properties": [
+        {
+          "type": "Swagger",
+          "url": "https://docs.api.epilot.io/environments.yaml"
+        }
+      ]
+    },
+    {
+      "name": "Event Catalog API",
+      "baseURL": "https://event-catalog.sls.epilot.io",
+      "properties": [
+        {
+          "type": "Swagger",
+          "url": "https://docs.api.epilot.io/event-catalog.yaml"
+        }
+      ]
+    },
+    {
+      "name": "Targeting API",
+      "baseURL": "https://targeting.sls.epilot.io",
+      "properties": [
+        {
+          "type": "Swagger",
+          "url": "https://docs.api.epilot.io/targeting.yaml"
+        }
+      ]
+    },
+    {
+      "name": "App API",
+      "baseURL": "https://app.sls.epilot.io",
+      "properties": [
+        {
+          "type": "Swagger",
+          "url": "https://docs.api.epilot.io/app.yaml"
+        }
+      ]
+    },
+    {
+      "name": "Audit Log API",
+      "baseURL": "https://audit-logs.sls.epilot.io",
+      "properties": [
+        {
+          "type": "Swagger",
+          "url": "https://docs.api.epilot.io/audit-log.yaml"
+        }
+      ]
+    },
+    {
+      "name": "Data Governance API",
+      "baseURL": "https://data-governance.sls.epilot.io",
+      "properties": [
+        {
+          "type": "Swagger",
+          "url": "https://docs.api.epilot.io/data-governance.yaml"
+        }
+      ]
     }
   ]
 }