docs_health

Instructions

Implementation Reference

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

  Main handler function that registers the docs_health tool on the MCP server. It checks GitBook health and returns either a success message with available tools or a warning with troubleshooting steps.

  function registerGitBookMetaTools(server: McpServer): void {
    // Tool to check GitBook MCP health
    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 service function that checks GitBook MCP server reachability by attempting to fetch tools. Returns health status and tool count.

  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/tools/gitbookProxy.ts:81-146 (registration)

  Registration flow: registerGitBookProxyTools() is called from src/index.ts with the server instance, which calls registerGitBookMetaTools() that registers docs_health via server.tool().

  export async function registerGitBookProxyTools(server: McpServer): Promise<number> {
    let registeredCount = 0;
    
    // Register meta tools (work even if GitBook is down)
    registerGitBookMetaTools(server);
    
    try {
      const tools = await fetchGitBookTools();
      
      if (tools.length === 0) {
        console.error("No tools found from GitBook MCP - meta-tools registered, proxy tools skipped");
        return 0;
      }
      
      console.error(`Registering ${tools.length} GitBook tools as docs_* proxies...`);
      
      for (const tool of tools) {
        try {
          // Prefix with "docs_" to indicate these are from SDK docs
          const proxyToolName = `docs_${tool.name}`;
          const zodSchema = convertToZodSchema(tool.inputSchema);
          
          server.tool(
            proxyToolName,
            `[SDK Docs] ${tool.description}`,
            zodSchema._def.typeName === "ZodObject" 
              ? (zodSchema as z.ZodObject<z.ZodRawShape>).shape 
              : {},
            DOCS_READ_ONLY,
            async (args) => {
              const result = await callGitBookTool(tool.name, args as Record<string, unknown>);
              
              // Add helpful context if the call failed
              if (result.isError) {
                return {
                  content: [{
                    type: "text" as const,
                    text: `⚠️ docs_${tool.name} failed: ${result.content[0]?.text || "Unknown error"}\n\nTry docs_refresh to reconnect, or visit https://docs.sodax.com directly.`
                  }],
                  isError: true
                };
              }
              
              return {
                content: result.content.map(c => ({
                  type: c.type as "text",
                  text: c.text || JSON.stringify(c)
                })),
                isError: result.isError
              };
            }
          );
          
          registeredCount++;
        } catch (toolError) {
          console.error(`Failed to register GitBook tool ${tool.name}:`, toolError);
        }
      }
      
      console.error(`Registered ${registeredCount} tools from GitBook MCP`);
    } catch (error) {
      console.error("Failed to register GitBook proxy tools:", error);
    }
    
    return registeredCount;
  }

• src/index.ts:44-45 (registration)

  Top-level entry point where registerGitBookProxyTools is called during server creation, triggering docs_health registration.

  registerSodaxApiTools(server);
  await registerGitBookProxyTools(server);

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

  Analytics mapping groups docs_health into 'sdk-docs' category for PostHog event tracking.

    // GitBook SDK docs meta-tools
    docs_health: "sdk-docs",
    docs_refresh: "sdk-docs",
    docs_list_tools: "sdk-docs",
  };