@aibuilders/mcp-coach-server 1.0.8 → 1.0.10

package/dist/index.js

@@ -16,6 +16,46 @@ const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"),
 const PACKAGE_VERSION = packageJson.version;
 const CACHE_DIR = join(homedir(), ".ai-builders-mcp-cache");
 const DEPLOYMENT_GUIDE_CACHE = join(CACHE_DIR, "deployment_guide_cache.json");
+const OPENAPI_SPEC_CACHE = join(CACHE_DIR, "openapi_spec_cache.json");
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const API_ORIGIN = "https://space.ai-builders.com";
+const DEFAULT_API_BASE_URL = `${API_ORIGIN}/backend`;
+const OPENAPI_SPEC_URL = `${DEFAULT_API_BASE_URL}/openapi.json`;
+const DEPLOYMENT_GUIDE_URL = `${API_ORIGIN}/deployment-prompt.md`;
+function isCacheFresh(cachedAt) {
+    if (!cachedAt) {
+        return false;
+    }
+    const cachedTime = new Date(cachedAt);
+    if (Number.isNaN(cachedTime.getTime())) {
+        return false;
+    }
+    return Date.now() - cachedTime.getTime() < CACHE_TTL_MS;
+}
+function isMissingFileError(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function deriveBaseUrl(openapiSpec) {
+    let baseUrl = DEFAULT_API_BASE_URL;
+    try {
+        if (openapiSpec?.servers?.length) {
+            const url = openapiSpec.servers[0].url;
+            if (typeof url === "string" && url.startsWith("http")) {
+                baseUrl = url;
+            }
+            else if (typeof url === "string") {
+                baseUrl = `${API_ORIGIN}${url}`;
+            }
+        }
+    }
+    catch (error) {
+        console.error("Failed to derive base URL from OpenAPI spec:", error);
+    }
+    return baseUrl;
+}
+function getSdkBaseUrl(baseUrl) {
+    return baseUrl.endsWith('/v1') ? baseUrl : `${baseUrl}/v1`;
+}
 async function ensureCacheDir() {
     try {
         await access(CACHE_DIR);
@@ -65,14 +105,17 @@ async function getCachedDeploymentGuide() {
         const cacheData = JSON.parse(cacheContent);
         const cachedTime = new Date(cacheData.cached_at);
         const now = new Date();
-        if (now.getTime() - cachedTime.getTime() < 24 * 60 * 60 * 1000) {
+        if (now.getTime() - cachedTime.getTime() < CACHE_TTL_MS) {
             return cacheData;
         }
     }
-    catch {
+    catch (error) {
+        if (!isMissingFileError(error)) {
+            console.error("Deployment guide cache read failed:", error);
+        }
     }
     try {
-        const response = await fetch("https://space.ai-builders.com/deployment-prompt.md");
+        const response = await fetch(DEPLOYMENT_GUIDE_URL);
         if (response.ok) {
             const content = await response.text();
             const cacheData = {
@@ -98,6 +141,60 @@ async function getCachedDeploymentGuide() {
         source: "default"
     };
 }
+async function getCachedOpenApiSpec(forceRefresh = false) {
+    await ensureCacheDir();
+    let cachedSpec = null;
+    try {
+        const cacheContent = await readFile(OPENAPI_SPEC_CACHE, "utf-8");
+        cachedSpec = JSON.parse(cacheContent);
+        if (cachedSpec && !forceRefresh && isCacheFresh(cachedSpec.cached_at)) {
+            return {
+                spec: cachedSpec.spec,
+                cached_at: cachedSpec.cached_at,
+                source: "cache"
+            };
+        }
+    }
+    catch (error) {
+        if (!isMissingFileError(error)) {
+            console.error("OpenAPI cache read failed:", error);
+        }
+    }
+    try {
+        const response = await fetch(OPENAPI_SPEC_URL);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch OpenAPI specification: HTTP ${response.status}`);
+        }
+        const spec = await response.json();
+        const cacheData = {
+            spec,
+            cached_at: new Date().toISOString(),
+            url: OPENAPI_SPEC_URL
+        };
+        try {
+            await writeFile(OPENAPI_SPEC_CACHE, JSON.stringify(cacheData, null, 2));
+        }
+        catch (error) {
+            console.error("OpenAPI cache write failed:", error);
+        }
+        return {
+            spec,
+            cached_at: cacheData.cached_at,
+            source: "remote"
+        };
+    }
+    catch (error) {
+        if (cachedSpec?.spec) {
+            console.error("Failed to fetch OpenAPI specification; using stale cache:", error);
+            return {
+                spec: cachedSpec.spec,
+                cached_at: cachedSpec.cached_at,
+                source: "stale_cache"
+            };
+        }
+        throw error;
+    }
+}
 const server = new Server({
     name: "ai-builder-mcp",
     version: PACKAGE_VERSION,
@@ -111,32 +208,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         switch (name) {
             case "get_api_specification": {
-                const response = await fetch("https://space.ai-builders.com/backend/openapi.json");
-                if (!response.ok) {
-                    throw new Error(`Failed to fetch OpenAPI specification: HTTP ${response.status}`);
-                }
-                const openapiSpec = await response.json();
-                let baseUrl = "https://space.ai-builders.com/backend";
-                try {
-                    if (openapiSpec?.servers?.length) {
-                        const url = openapiSpec.servers[0].url;
-                        if (url.startsWith("http")) {
-                            baseUrl = url;
-                        }
-                        else {
-                            baseUrl = `https://space.ai-builders.com${url}`;
-                        }
-                    }
-                }
-                catch { }
+                const forceRefresh = args?.force_refresh === true;
+                const cachedOpenApi = await getCachedOpenApiSpec(forceRefresh);
+                const openapiSpec = cachedOpenApi.spec;
+                const baseUrl = deriveBaseUrl(openapiSpec);
                 // For OpenAI SDK, baseURL should include /v1 since SDK appends paths directly
-                const sdkBaseUrl = baseUrl.endsWith('/v1') ? baseUrl : `${baseUrl}/v1`;
+                const sdkBaseUrl = getSdkBaseUrl(baseUrl);
                 return {
                     content: [
                         {
                             type: "text",
                             text: JSON.stringify({
                                 openapi_spec: openapiSpec,
+                                cache: {
+                                    source: cachedOpenApi.source,
+                                    cached_at: cachedOpenApi.cached_at,
+                                    ttl_hours: 24,
+                                    openapi_spec_url: OPENAPI_SPEC_URL
+                                },
                                 endpoint_info: {
                                     base_url: baseUrl,
                                     description: "Base URL for the AI Builders API",
@@ -333,6 +422,89 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ]
                 };
             }
+            case "get_base_url": {
+                const forceRefresh = args?.force_refresh === true;
+                let baseUrl = DEFAULT_API_BASE_URL;
+                let source = "default";
+                let cache = null;
+                try {
+                    const cachedOpenApi = await getCachedOpenApiSpec(forceRefresh);
+                    baseUrl = deriveBaseUrl(cachedOpenApi.spec);
+                    source = "openapi_spec";
+                    cache = {
+                        source: cachedOpenApi.source,
+                        cached_at: cachedOpenApi.cached_at,
+                        ttl_hours: 24,
+                        openapi_spec_url: OPENAPI_SPEC_URL
+                    };
+                }
+                catch (error) {
+                    console.error("Failed to fetch OpenAPI specification for base URL; using default:", error);
+                }
+                // For OpenAI SDK, baseURL should include /v1 since SDK appends paths directly
+                const sdkBaseUrl = getSdkBaseUrl(baseUrl);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                base_url: baseUrl,
+                                sdk_base_url: sdkBaseUrl,
+                                source,
+                                cache,
+                                prompt_for_ai: `The base URL for AI Builders Space API is: ${baseUrl}
+
+This is the base URL you should use for all API calls to the AI Builders Space platform. When making HTTP requests, prepend this base URL to the API endpoint paths.
+
+For example:
+- Full endpoint URL: ${baseUrl}/v1/chat/completions
+- Full endpoint URL: ${baseUrl}/v1/deployments
+
+If you are using the OpenAI SDK (recommended), use this base URL: ${sdkBaseUrl}
+
+The base URL is also documented in the deployment guide, but this tool provides a direct way to retrieve it without parsing the full deployment guide.`,
+                                usage_examples: {
+                                    direct_http: {
+                                        description: "Direct HTTP requests",
+                                        base_url: baseUrl,
+                                        example: `const response = await fetch('${baseUrl}/v1/chat/completions', {
+  method: 'POST',
+  headers: {
+    'Authorization': \`Bearer \${process.env.AI_BUILDER_TOKEN}\`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({ model: 'grok-4-fast', messages: [...] })
+});`
+                                    },
+                                    openai_sdk: {
+                                        description: "OpenAI SDK (recommended)",
+                                        base_url: sdkBaseUrl,
+                                        example_node: `import OpenAI from 'openai';
+
+const openai = new OpenAI({
+  baseURL: '${sdkBaseUrl}',
+  apiKey: process.env.AI_BUILDER_TOKEN,
+});`,
+                                        example_python: `from openai import OpenAI
+import os
+
+client = OpenAI(
+    base_url='${sdkBaseUrl}',
+    api_key=os.getenv('AI_BUILDER_TOKEN')
+)`
+                                    }
+                                },
+                                important_notes: [
+                                    "Always use this base URL when making API calls to AI Builders Space",
+                                    "The base URL includes the /backend path",
+                                    "For OpenAI SDK compatibility, use the sdk_base_url which includes /v1",
+                                    "All API calls require authentication via AI_BUILDER_TOKEN in the Authorization header"
+                                ]
+                            }, null, 2)
+                        }
+                    ]
+                };
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -361,7 +533,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 description: "Retrieve the OpenAPI specification with endpoint details",
                 inputSchema: {
                     type: "object",
-                    properties: {}
+                    properties: {
+                        force_refresh: {
+                            type: "boolean",
+                            description: "Bypass the 24-hour OpenAPI cache and fetch the latest specification",
+                            default: false
+                        }
+                    }
                 }
             },
             {
@@ -399,6 +577,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         }
                     }
                 }
+            },
+            {
+                name: "get_base_url",
+                description: "Get the base URL for AI Builders Space API. This tool provides a direct way to retrieve the base URL without parsing the deployment guide.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        force_refresh: {
+                            type: "boolean",
+                            description: "Bypass the 24-hour OpenAPI cache and fetch the latest specification",
+                            default: false
+                        }
+                    }
+                }
             }
         ]
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibuilders/mcp-coach-server",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "AI Builder MCP server for AI Builders platform",
   "main": "dist/index.js",
   "type": "module",