semantic-search

Instructions

Implementation Reference

• src/tools/semantic-search.ts:17-33 (handler)

  The main handler function for the semantic-search tool. It POSTs a query to /search/vector/query on the OpenMetadata API with optional filters for entityType, owners, tags, domains, tier, and serviceType.

  export async function semanticSearch(params: z.infer<typeof semanticSearchSchema>) {
    const filters: Record<string, string[]> = {};
    if (params.entityType?.length) filters.entityType = params.entityType;
    if (params.owners?.length) filters.owners = params.owners;
    if (params.tags?.length) filters.tags = params.tags;
    if (params.domains?.length) filters.domains = params.domains;
    if (params.tier?.length) filters.tier = params.tier;
    if (params.serviceType?.length) filters.serviceType = params.serviceType;
  
    return omClient.post("/search/vector/query", {
      query: params.query,
      size: Math.min(params.size ?? 10, 100),
      k: Math.min(params.k ?? 500, 10000),
      threshold: params.threshold ?? 0.0,
      filters: Object.keys(filters).length > 0 ? filters : undefined,
    });
  }

• src/tools/semantic-search.ts:4-15 (schema)

  Zod schema defining the input parameters for semantic-search: query (string), size (default 10), k (default 500), threshold (default 0.0), and optional array filters: entityType, owners, tags, domains, tier, serviceType.

  export const semanticSearchSchema = z.object({
    query: z.string().describe("Natural language search text. Example: 'customer demographics purchase history'"),
    size: z.coerce.number().optional().default(10).describe("Number of distinct entities to return (max 100)"),
    k: z.coerce.number().optional().default(500).describe("KNN parameter — number of nearest neighbors to consider (max 10,000)"),
    threshold: z.coerce.number().optional().default(0.0).describe("Minimum similarity score (0.0–1.0) to include in results"),
    entityType: z.array(z.string()).optional().describe("Filter by entity types. Example: ['table','dashboard']"),
    owners: z.array(z.string()).optional().describe("Filter by owner names"),
    tags: z.array(z.string()).optional().describe("Filter by tag FQNs. Example: ['PII.Sensitive']"),
    domains: z.array(z.string()).optional().describe("Filter by domain names"),
    tier: z.array(z.string()).optional().describe("Filter by tier. Example: ['Tier.Tier1']"),
    serviceType: z.array(z.string()).optional().describe("Filter by service type. Example: ['Postgres']"),
  });

• src/index.ts:171-171 (registration)

  Registration of the 'semantic-search' tool with the MCP server under the 'search' category, using semanticSearchSchema and wrapped semanticSearch handler.

  tool("semantic-search", "Natural-language semantic search over OpenMetadata entities using vector embeddings (requires OM 1.12+ with semantic search enabled)", semanticSearchSchema.shape, wrapToolHandler(semanticSearch));

• src/tool-registry.ts:12-12 (registration)

  The 'search' category declaration in the tool registry, listing semantic-search alongside search-metadata and suggest-metadata.

  "search",          // search-metadata, suggest-metadata, semantic-search

• src/tools/utils.ts:18-43 (helper)

  wrapToolHandler utility used to wrap the semanticSearch handler for error handling and redaction.

  export const wrapToolHandler = createWrapToolHandler({
    redactionPatterns: [/OPENMETADATA_TOKEN/i],
    errorExtractors: [
      {
        match: (error) => error instanceof WriteBlockedError,
        extract: (error) => ({
          kind: "passthrough",
          text: (error as WriteBlockedError).message,
        }),
      },
      {
        match: (error) => error instanceof OpenMetadataError,
        extract: (error) => {
          const err = error as OpenMetadataError;
          return {
            kind: "structured",
            data: {
              message: err.message,
              status: err.status,
              details: err.body,
            },
          };
        },
      },
    ],
  });