SourceSync.ai MCP Server

Instructions

Implementation Reference

• src/index.ts:606-632 (handler)

  MCP server tool handler for 'hybridSearch'. Extracts parameters, creates SourceSyncApiClient using createClient, calls its hybridSearch method with appropriate defaults, wrapped in safeApiCall for error handling.

  async (params: any) => {
    return safeApiCall(async () => {
      const {
        namespaceId,
        query,
        topK,
        scoreThreshold,
        filter,
        hybridConfig,
        tenantId,
        searchType,
      } = params
  
      // Create a client with the provided parameters
      const client = createClient({ namespaceId, tenantId })
  
      // Call the hybridSearch method with the searchType (default to HYBRID if not provided)
      return await client.hybridSearch({
        query,
        topK,
        scoreThreshold,
        filter,
        hybridConfig,
        searchType: searchType || SourceSyncSearchType.HYBRID,
      })
    })
  },

• src/schemas.ts:446-462 (schema)

  Zod schema defining the input parameters for the hybridSearch tool, including query, optional topK, scoreThreshold, filter, required hybridConfig with weights, optional namespaceId and searchType, and tenantId.

  export const HybridSearchSchema = z.object({
    namespaceId: namespaceIdSchema.optional(),
    query: z.string(),
    topK: z.number().optional(),
    scoreThreshold: z.number().optional(),
    filter: z
      .object({
        metadata: z.record(z.union([z.string(), z.array(z.string())])).optional(),
      })
      .optional(),
    hybridConfig: z.object({
      semanticWeight: z.number(),
      keywordWeight: z.number(),
    }),
    tenantId: tenantIdSchema,
    searchType: SearchTypeEnum.optional(),
  })

• src/index.ts:602-633 (registration)

  Registration of the 'hybridSearch' MCP tool using server.tool(), specifying the tool name, description, input schema, and handler function.

  server.tool(
    'hybridSearch',
    'Performs a combined keyword and semantic search, balancing between exact matches and semantic similarity. Requires hybridConfig with weights for both search types.',
    HybridSearchSchema.shape,
    async (params: any) => {
      return safeApiCall(async () => {
        const {
          namespaceId,
          query,
          topK,
          scoreThreshold,
          filter,
          hybridConfig,
          tenantId,
          searchType,
        } = params
  
        // Create a client with the provided parameters
        const client = createClient({ namespaceId, tenantId })
  
        // Call the hybridSearch method with the searchType (default to HYBRID if not provided)
        return await client.hybridSearch({
          query,
          topK,
          scoreThreshold,
          filter,
          hybridConfig,
          searchType: searchType || SourceSyncSearchType.HYBRID,
        })
      })
    },
  )

• src/sourcesync.ts:589-613 (helper)

  Underlying implementation of hybridSearch in SourceSyncApiClient class. Sends a POST request to the /v1/search/hybrid API endpoint with the search parameters and namespaceId, returning the search response.

  public async hybridSearch({
    query,
    topK,
    scoreThreshold,
    filter,
    hybridConfig,
    searchType,
  }: Omit<
    SourceSyncHybridSearchRequest,
    'namespaceId'
  >): Promise<SourceSyncSearchResponse> {
    return this.client
      .url('/v1/search/hybrid')
      .json({
        query,
        namespaceId: this.namespaceId,
        topK,
        scoreThreshold,
        filter,
        hybridConfig,
        searchType,
      } satisfies SourceSyncHybridSearchRequest)
      .post()
      .json<SourceSyncSearchResponse>()
  }