SourceSync.ai MCP Server

Instructions

Implementation Reference

• src/index.ts:352-405 (handler)

  Full tool registration and inline handler implementation for 'fetchDocuments'. Creates SourceSync client, processes parameters including enum conversions, and calls getDocuments API method wrapped in safeApiCall for error handling.

  server.tool(
    'fetchDocuments',
    'Fetches documents from the namespace based on filter criteria. Supports pagination and including specific document properties.',
    FetchDocumentsSchema.shape,
    async (params) => {
      return safeApiCall(async () => {
        const {
          namespaceId,
          tenantId,
          documentIds,
          pagination,
          filterConfig,
          includeConfig,
        } = params
  
        // Create a client with the provided parameters
        const client = createClient({ namespaceId, tenantId })
  
        // Add documentIds to filterConfig if provided
        if (documentIds && documentIds.length > 0 && !filterConfig.documentIds) {
          filterConfig.documentIds = documentIds
        }
  
        // Call the getDocuments method with properly structured parameters
        return await client.getDocuments({
          filterConfig: {
            ...filterConfig,
            // Convert string enum values to their SourceSync enum equivalents
            documentTypes: filterConfig.documentTypes?.map(
              (type: string) =>
                SourceSyncDocumentType[
                  type as keyof typeof SourceSyncDocumentType
                ],
            ),
            documentIngestionSources: filterConfig.documentIngestionSources?.map(
              (source: string) =>
                SourceSyncIngestionSource[
                  source as keyof typeof SourceSyncIngestionSource
                ],
            ),
            documentIngestionStatuses:
              filterConfig.documentIngestionStatuses?.map(
                (status: string) =>
                  SourceSyncIngestionStatus[
                    status as keyof typeof SourceSyncIngestionStatus
                  ],
              ),
          },
          pagination,
          includeConfig: includeConfig || { documents: true },
        })
      })
    },
  )

• src/schemas.ts:366-382 (schema)

  Zod schema defining the input validation for the fetchDocuments tool, including optional namespaceId, documentIds, pagination, required tenantId, filterConfig, and optional includeConfig.

  export const FetchDocumentsSchema = z.object({
    namespaceId: namespaceIdSchema.optional(),
    documentIds: z.array(z.string()).optional(),
    pagination: PaginationSchema.optional(),
    tenantId: tenantIdSchema,
    filterConfig: FilterConfigSchema,
    includeConfig: z
      .object({
        documents: z.boolean().optional(),
        stats: z.boolean().optional(),
        statsBySource: z.boolean().optional(),
        statsByStatus: z.boolean().optional(),
        rawFileUrl: z.boolean().optional(),
        parsedTextFileUrl: z.boolean().optional(),
      })
      .optional(),
  })

• src/index.ts:85-107 (helper)

  Helper function used by all tools, including fetchDocuments, to safely execute API calls, format successful responses as MCP content, and handle errors appropriately.

  async function safeApiCall<T>(apiCall: () => Promise<T>) {
    try {
      const result = await apiCall()
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify(result),
          },
        ],
      }
    } catch (error: any) {
      // Preserve the original error structure from SourceSync
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify(error),
          },
        ],
        isError: true,
      }
    }

• src/index.ts:64-78 (helper)

  Helper function to instantiate the SourceSync client used in the fetchDocuments handler, falling back to environment variables.

  function createClient({
    apiKey,
    namespaceId,
    tenantId,
  }: {
    apiKey?: string
    namespaceId?: string
    tenantId?: string
  }) {
    return sourcesync({
      apiKey: apiKey || process.env.SOURCESYNC_API_KEY || '',
      namespaceId: namespaceId || process.env.SOURCESYNC_NAMESPACE_ID || '',
      tenantId: tenantId || process.env.SOURCESYNC_TENANT_ID || '',
    })
  }