SODAX Builders MCP

Instructions

Implementation Reference

• src/tools/gitbookProxy.ts:81-146 (registration)

  The registerGitBookProxyTools function dynamically fetches tools from the GitBook MCP server and registers them with a 'docs_' prefix. 'docs_searchDocumentation' would be registered if the GitBook server has a tool named 'searchDocumentation'.

  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/tools/gitbookProxy.ts:110-131 (handler)

  Handler function that executes when any docs_* tool is called. It proxies the call to the GitBook MCP server via callGitBookTool() and returns the result with helpful error context.

  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
    };
  }

• src/tools/gitbookProxy.ts:28-75 (schema)

  The convertToZodSchema function converts GitBook tool input schemas (JSON Schema format) to Zod schemas for type validation and schema generation.

  function convertToZodSchema(inputSchema: GitBookTool["inputSchema"]): z.ZodTypeAny {
    if (!inputSchema.properties || Object.keys(inputSchema.properties).length === 0) {
      return z.object({});
    }
    
    const shape: Record<string, z.ZodTypeAny> = {};
    const required = inputSchema.required || [];
    
    for (const [key, prop] of Object.entries(inputSchema.properties)) {
      const propDef = prop as { type?: string; description?: string; default?: unknown };
      let fieldSchema: z.ZodTypeAny;
      
      switch (propDef.type) {
        case "string":
          fieldSchema = z.string();
          break;
        case "number":
        case "integer":
          fieldSchema = z.number();
          break;
        case "boolean":
          fieldSchema = z.boolean();
          break;
        case "array":
          fieldSchema = z.array(z.unknown());
          break;
        case "object":
          fieldSchema = z.record(z.unknown());
          break;
        default:
          fieldSchema = z.unknown();
      }
      
      // Add description if available
      if (propDef.description) {
        fieldSchema = fieldSchema.describe(propDef.description);
      }
      
      // Make optional if not required
      if (!required.includes(key)) {
        fieldSchema = fieldSchema.optional();
      }
      
      shape[key] = fieldSchema;
    }
    
    return z.object(shape);
  }

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

  The fetchGitBookTools function fetches the list of available tools from the GitBook MCP server and caches them for 10 minutes. This is where 'searchDocumentation' tool definition comes from.

  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/gitbookProxy.ts:153-174 (helper)

  The callGitBookTool function sends JSON-RPC requests to the GitBook MCP server to execute the actual tool (e.g., 'searchDocumentation') and returns the result.

  export async function callGitBookTool(
    toolName: string, 
    args: Record<string, unknown>
  ): Promise<GitBookToolResult> {
    try {
      // Ensure connection is initialized
      await initializeConnection();
      
      const result = await sendMcpRequest("tools/call", {
        name: toolName,
        arguments: args
      }) as GitBookToolResult;
      
      return result;
    } catch (error) {
      const message = error instanceof Error ? error.message : "Unknown error";
      return {
        content: [{ type: "text", text: `Error calling GitBook tool: ${message}` }],
        isError: true
      };
    }
  }