SODAX Builders MCP

Instructions

Implementation Reference

• src/tools/gitbookProxy.ts:153-179 (handler)

  The docs_health tool handler implementation. This async function checks SDK documentation availability by calling checkGitBookHealth() and fetchGitBookTools(), returning status information about available documentation tools.

  server.tool(
    "docs_health",
    "Check SDK documentation availability. Call this first if docs tools seem unavailable.",
    {},
    DOCS_READ_ONLY,
    async () => {
      const health = await checkGitBookHealth();
      const tools = await fetchGitBookTools();
      
      if (health.healthy && tools.length > 0) {
        const toolNames = tools.slice(0, 5).map(t => `docs_${t.name}`).join(", ");
        return {
          content: [{
            type: "text",
            text: `✅ SDK Docs available. ${health.toolCount} tools ready.\n\nExample tools: ${toolNames}${tools.length > 5 ? "..." : ""}\n\nUse docs_list_tools for the full list, or call any docs_* tool directly.`
          }]
        };
      }
      
      return {
        content: [{
          type: "text",
          text: `⚠️ SDK Docs temporarily unavailable.\n\n**What you can do:**\n1. Try \`docs_refresh\` to reconnect\n2. Visit https://docs.sodax.com directly\n3. Use SODAX API tools (sodax_*) which work independently`
        }]
      };
    }
  );

• src/tools/gitbookProxy.ts:153-179 (registration)

  Registration of the docs_health tool using server.tool() with name 'docs_health', description, empty schema (no parameters), DOCS_READ_ONLY annotations, and the async handler function.

  server.tool(
    "docs_health",
    "Check SDK documentation availability. Call this first if docs tools seem unavailable.",
    {},
    DOCS_READ_ONLY,
    async () => {
      const health = await checkGitBookHealth();
      const tools = await fetchGitBookTools();
      
      if (health.healthy && tools.length > 0) {
        const toolNames = tools.slice(0, 5).map(t => `docs_${t.name}`).join(", ");
        return {
          content: [{
            type: "text",
            text: `✅ SDK Docs available. ${health.toolCount} tools ready.\n\nExample tools: ${toolNames}${tools.length > 5 ? "..." : ""}\n\nUse docs_list_tools for the full list, or call any docs_* tool directly.`
          }]
        };
      }
      
      return {
        content: [{
          type: "text",
          text: `⚠️ SDK Docs temporarily unavailable.\n\n**What you can do:**\n1. Try \`docs_refresh\` to reconnect\n2. Visit https://docs.sodax.com directly\n3. Use SODAX API tools (sodax_*) which work independently`
        }]
      };
    }
  );

• src/services/gitbookProxy.ts:179-186 (helper)

  Helper function checkGitBookHealth() that checks if the GitBook MCP server is reachable and returns a health status with the count of available tools.

  export async function checkGitBookHealth(): Promise<{ healthy: boolean; toolCount: number }> {
    try {
      const tools = await fetchGitBookTools();
      return { healthy: true, toolCount: tools.length };
    } catch {
      return { healthy: false, toolCount: 0 };
    }
  }

• src/services/gitbookProxy.ts:120-148 (helper)

  Helper function fetchGitBookTools() that fetches the list of available tools from the GitBook MCP server with caching support (10-minute cache duration).

  export async function fetchGitBookTools(): Promise<GitBookTool[]> {
    // Return cached tools if still valid
    if (cachedTools && Date.now() - toolsCacheTime < TOOLS_CACHE_DURATION) {
      return cachedTools;
    }
    
    try {
      // Initialize connection first
      await initializeConnection();
      
      // Fetch tools list
      const result = await sendMcpRequest("tools/list") as { tools: GitBookTool[] };
      
      cachedTools = result.tools || [];
      toolsCacheTime = Date.now();
      
      if (cachedTools.length > 0) {
        console.error(`✅ Fetched ${cachedTools.length} tools from GitBook MCP`);
      } else {
        console.error(`⚠️ GitBook MCP returned empty tools list`);
      }
      return cachedTools;
    } catch (error) {
      const errorMsg = error instanceof Error ? error.message : "unknown error";
      console.error(`❌ Failed to fetch GitBook tools: ${errorMsg}`);
      // Return cached tools even if expired, or empty array
      return cachedTools || [];
    }
  }

• src/services/analytics.ts:41-41 (helper)

  Analytics tracking configuration for docs_health tool in the TOOL_GROUPS mapping to the 'sdk-docs' group for PostHog event tracking.

  docs_health: "sdk-docs",