Insforge MCP Server

Instructions

Implementation Reference

• src/shared/tools.ts:279-309 (handler)

  Core handler logic for the 'fetch-docs' tool. Fetches documentation using fetchDocumentation helper, adds background context, and handles specific errors like 404.

  withUsageTracking('fetch-docs', async ({ docType }) => {
    try {
      const content = await fetchDocumentation(docType);
  
      return await addBackgroundContext({
        content: [
          {
            type: 'text',
            text: content,
          },
        ],
      });
    } catch (error) {
      const errMsg = error instanceof Error ? error.message : 'Unknown error occurred';
  
      // Friendly error for not found (likely due to old backend version)
      if (errMsg.includes('404') || errMsg.toLowerCase().includes('not found')) {
        return {
          content: [{
            type: 'text' as const,
            text: `Documentation for "${docType}" is not available. This is likely because your backend version is too old and doesn't support this documentation endpoint yet. This won't affect the functionality of the tools - they will still work correctly.`
          }],
        };
      }
  
      // Generic error response - no background context
      return {
        content: [{ type: 'text' as const, text: `Error fetching ${docType} documentation: ${errMsg}` }],
      };
    }
  })

• src/shared/tools.ts:274-310 (registration)

  Registration of the 'fetch-docs' tool on the MCP server, including name, description, input schema, and handler function.

    'fetch-docs',
    'Fetch Insforge documentation. Use "instructions" for essential backend setup (MANDATORY FIRST), or select specific SDK docs for database, auth, storage, functions, or AI integration.',
    {
      docType: docTypeSchema
    },
    withUsageTracking('fetch-docs', async ({ docType }) => {
      try {
        const content = await fetchDocumentation(docType);
  
        return await addBackgroundContext({
          content: [
            {
              type: 'text',
              text: content,
            },
          ],
        });
      } catch (error) {
        const errMsg = error instanceof Error ? error.message : 'Unknown error occurred';
  
        // Friendly error for not found (likely due to old backend version)
        if (errMsg.includes('404') || errMsg.toLowerCase().includes('not found')) {
          return {
            content: [{
              type: 'text' as const,
              text: `Documentation for "${docType}" is not available. This is likely because your backend version is too old and doesn't support this documentation endpoint yet. This won't affect the functionality of the tools - they will still work correctly.`
            }],
          };
        }
  
        // Generic error response - no background context
        return {
          content: [{ type: 'text' as const, text: `Error fetching ${docType} documentation: ${errMsg}` }],
        };
      }
    })
  );

• src/shared/tools.ts:277-278 (schema)

  Input schema definition for the tool using imported docTypeSchema Zod schema.

    docType: docTypeSchema
  },

• src/shared/tools.ts:201-232 (helper)

  Helper function that performs the HTTP request to fetch documentation from the backend API endpoint `/api/docs/${docType}` and processes/replaces URLs in the content.

  const fetchDocumentation = async (docType: string): Promise<string> => {
    try {
      const response = await fetch(`${API_BASE_URL}/api/docs/${docType}`, {
        method: 'GET',
        headers: {
          'Content-Type': 'application/json',
        },
      });
  
      // Check for 404 before processing response
      if (response.status === 404) {
        throw new Error('Documentation not found. This feature may not be supported in your project version. Please contact the Insforge team for assistance.');
      }
  
      const result = await handleApiResponse(response);
  
      if (result && typeof result === 'object' && 'content' in result) {
        let content = result.content;
        // Replace all example/placeholder URLs with actual API_BASE_URL
        // Handle URLs whether they're in backticks, quotes, or standalone
        // Preserve paths after the domain by only replacing the base URL
        content = content.replace(/http:\/\/localhost:7130/g, API_BASE_URL);
        content = content.replace(/https:\/\/your-app\.region\.insforge\.app/g, API_BASE_URL);
        return content;
      }
  
      throw new Error('Invalid response format from documentation endpoint');
    } catch (error) {
      const errMsg = error instanceof Error ? error.message : 'Unknown error occurred';
      throw new Error(`Unable to retrieve ${docType} documentation: ${errMsg}`);
    }
  };