SourceSync.ai MCP Server

Instructions

Implementation Reference

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

  Registration of the 'fetchDocuments' MCP tool. Includes inline handler that processes input parameters, creates a SourceSync client, handles document ID filtering, converts string enums to proper enum values, and calls client.getDocuments() with pagination and include options.

  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 definition for the fetchDocuments tool input parameters, including optional namespaceId, documentIds, pagination, required tenantId and 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:64-78 (helper)

  Helper function used by the fetchDocuments handler to instantiate the SourceSync client with provided or env-based credentials.

  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 || '',
    })
  }

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

  Helper function used by the fetchDocuments handler to wrap API calls, formatting successful results as MCP content and 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,
      }
    }
  }