lfx-mcp: Skill for Claude Code

Validate Search Filters

Validate every filter parameter across all tools that use the query service SDK in internal/tools/ against the live OpenSearch resources index and the upstream indexer-contract documentation. Produce a per-filter verdict table and optionally apply fixes.

Gotchas

• The OpenSearch cluster is AWS-managed and not port-forward accessible. All curl queries must be run via kubectl exec into the NATS box pod.
• Discover the pod name dynamically — never hardcode it. Use the label selector app.kubernetes.io/component=nats-box,app.kubernetes.io/instance=lfx-platform in namespace lfx.
• Discover the OpenSearch URL dynamically from the indexer deployment env var OPENSEARCH_URL. The index name is in OPENSEARCH_INDEX (currently resources). Combine them into OPENSEARCH_BASEURL as shown in Step 1.
• tags entries may have empty values (e.g. "committee_uid:", "project_uid:") — these are indexed but useless for filtering. A tag key is only valid evidence when at least one document has a non-empty value for it.
• Mixed old/new data means partial parent_refs coverage is expected on some resource types. A non-zero hit count on a prefix query is sufficient evidence that the mechanism works.
• payload.Parent in the query service is a single string. A tool that accepts both project_uid and committee_uid can only send one at a time.
• handleSearchPastMeetingParticipants and handleSearchPastMeetingSummaries are dedicated handlers — each owns its own filter logic independently.
• Prefer count-only queries over random sampling. A handful of random documents proves nothing — you can get lucky and see the right fields while 90% of the corpus has them missing. Always run "size": 0 prefix count queries first. Only pull sample documents ("size": 3) as a secondary debugging aid when a count is zero or surprising (e.g. to understand what fields are actually present on that resource type).
• payload.Filters (singular) is a distinct mechanism from FiltersAll and is easy to skip. It shows up disproportionately in single-record get_* lookups (Filters: []string{"uid:" + id}) rather than multi-param search_* tools, so a review organized by tool name or by the reference table below can walk right past it. Grep for the literal mechanism (Filters: / FiltersAll: / Tags: / TagsAll: / Parent: / payload.Parent), not for tool-name patterns like get_* or search_* — any handler that builds a QueryResourcesPayload is in scope, regardless of what it's named. Don't assume a Filters: uid:<id> clause is "obviously correct" just because it looks like a primary-key lookup — but also don't assume it's broken without checking the right field (see the next point).
• Filters/FiltersAll target the data flat_object, not a literal top-level document field. "uid:<value>" resolves to data.uid, exactly like the name:/legal_parent_uid: examples in project.go resolve to data.name/data.legal_parent_uid. This is not the same field space as tags and parent_refs, which are genuinely top-level. When checking whether a Filters/FiltersAll clause matches the index, always query data.<field> (e.g. {"exists": {"field": "data.uid"}} or a term query against data.uid), never a bare top-level {"exists": {"field": "uid"}} — the latter will show 0 hits for every resource type regardless of whether the filter actually works, producing a false "broken" verdict. (This distinction was missed in an earlier pass of this skill, which incorrectly flagged get_meeting_registrant and get_past_meeting_participant as broken using exactly this wrong top-level check; data.uid is in fact populated and correct for both. Only v1_meeting and v1_past_meeting_summary lack a populated data.uid — those two were genuinely broken and are fixed by the meeting_id:/past_meeting_summary_id: tag lookup.)