SourceSync.ai MCP Server

Instructions

Implementation Reference

• src/index.ts:411-475 (handler)

  MCP tool handler for 'updateDocuments': processes input params, creates SourceSync client, handles document IDs and metadata merging, converts enums, and invokes the API client's updateDocuments method wrapped in safeApiCall.

  async (params: any) => {
    return safeApiCall(async () => {
      const { namespaceId, documents, tenantId, filterConfig, data } = params
  
      // Create a client with the provided parameters
      const client = createClient({ namespaceId, tenantId })
  
      // Extract document IDs and add to filter if not already present
      if (documents && documents.length > 0 && !filterConfig.documentIds) {
        filterConfig.documentIds = documents.map((doc: any) => doc.documentId)
      }
  
      // Prepare metadata for update
      const metadata: Record<string, any> = {}
  
      if (documents) {
        documents.forEach((doc: any) => {
          if (doc.metadata) {
            // Combine all document metadata
            Object.assign(metadata, doc.metadata)
          }
        })
      }
  
      // Prepare the data object
      if (Object.keys(metadata).length > 0) {
        data.metadata = metadata
      }
  
      // Call the updateDocuments method with properly structured parameters
      return await client.updateDocuments({
        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
                ],
            ),
        },
        data: {
          metadata: data?.metadata || {},
          $metadata: data?.$metadata || {
            $set: {},
            $append: {},
            $remove: {},
          },
        },
      })
    })
  },

• src/index.ts:407-476 (registration)

  MCP server registration of the 'updateDocuments' tool, specifying name, description, input schema, and handler function.

  server.tool(
    'updateDocuments',
    'Updates metadata for documents that match the specified filter criteria.',
    UpdateDocumentsSchema.shape,
    async (params: any) => {
      return safeApiCall(async () => {
        const { namespaceId, documents, tenantId, filterConfig, data } = params
  
        // Create a client with the provided parameters
        const client = createClient({ namespaceId, tenantId })
  
        // Extract document IDs and add to filter if not already present
        if (documents && documents.length > 0 && !filterConfig.documentIds) {
          filterConfig.documentIds = documents.map((doc: any) => doc.documentId)
        }
  
        // Prepare metadata for update
        const metadata: Record<string, any> = {}
  
        if (documents) {
          documents.forEach((doc: any) => {
            if (doc.metadata) {
              // Combine all document metadata
              Object.assign(metadata, doc.metadata)
            }
          })
        }
  
        // Prepare the data object
        if (Object.keys(metadata).length > 0) {
          data.metadata = metadata
        }
  
        // Call the updateDocuments method with properly structured parameters
        return await client.updateDocuments({
          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
                  ],
              ),
          },
          data: {
            metadata: data?.metadata || {},
            $metadata: data?.$metadata || {
              $set: {},
              $append: {},
              $remove: {},
            },
          },
        })
      })
    },
  )

• src/schemas.ts:384-404 (schema)

  Zod schema defining the input structure for the updateDocuments tool, including namespace, documents list, tenant, filter config, and update data.

  export const UpdateDocumentsSchema = z.object({
    namespaceId: namespaceIdSchema.optional(),
    documents: z.array(
      z.object({
        documentId: z.string(),
        metadata: z.record(z.string()).optional(),
      }),
    ),
    tenantId: tenantIdSchema,
    filterConfig: FilterConfigSchema,
    data: z.object({
      metadata: z.record(z.string()).optional(),
      $metadata: z
        .object({
          $set: z.record(z.union([z.string(), z.array(z.string())])).optional(),
          $append: z.record(z.array(z.string())).optional(),
          $remove: z.record(z.array(z.string())).optional(),
        })
        .optional(),
    }),
  })

• src/sourcesync.ts:503-519 (helper)

  SourceSyncApiClient's updateDocuments method: sends PATCH request to /v1/documents endpoint with filterConfig and data to update matching documents.

  public async updateDocuments({
    filterConfig,
    data,
  }: Omit<
    SourceSyncUpdateDocumentsRequest,
    'namespaceId'
  >): Promise<SourceSyncUpdateDocumentsResponse> {
    return this.client
      .url(`/v1/documents`)
      .json({
        namespaceId: this.namespaceId,
        filterConfig,
        data,
      } satisfies SourceSyncUpdateDocumentsRequest)
      .patch()
      .json<SourceSyncUpdateDocumentsResponse>()
  }