yrb-hes-evidence-mcp

YRB-HES Evidence MCP

Overview

Use the MCP as a read-only evidence gateway for rag_sag.yrb3_v3. It connects metadata, abstract screening, heading/subchunk records, SAG Event/Entity associations, verified edges, embeddings-backed recall, and structured spatiotemporal evidence while preserving exact source locators.

The geospatial business layer is part of the same rag_sag.yrb3_v3 schema: entity_geocode, entity_geocode_log, entity_hydro_relation, spatial_units, the hydro_*_source tables, and their read-only summary views. The former yrb3.public copy is a frozen archive and is not an active MCP source. Table names remain unchanged after the copy. The response may retain a geocode_sidecar key for client compatibility, but it does not represent a second database connection.

Required workflow

1. Call healthcheck first. Confirm database identity, schema, table availability, and current counts.
2. For a research question, call search_evidence with a concise query. Apply language, publication-year, evidence-year, and exact document_ids filters when the question provides them.
3. Use compare_evidence for cross-paper comparison. Treat each comparison row as a lead until its returned sources and locators are checked.
4. Use get_subchunk_context to inspect local heading/subchunk context, get_document_overview for one-document status, and trace_source before quoting or making a document-level claim.
5. Use search_entity and expand_entity to follow canonical concepts across Events and documents. Use get_spatiotemporal_evidence for explicit spatial/temporal evidence and the is_research_area gate.
6. Use search_geocode for coordinates and verdicts of geocoded spatial entities, and get_document_geocode for all geocoded entities of one document. The search supports in_yrb (legacy envelope), in_yrb9 (nine-province administrative mask), and in_yrb_hydro (hydrological-basin point membership) as separate filters; never conflate their meanings. Treat geocodes as candidate anchoring: check verdict, score, and level before mapping claims (adopt/catalog_center/section are coordinate-bearing; out_of_basin/foreign_reference are explicit exclusions; region_no_point/non_spatial/needs_paper carry no point by design). doc_refs on each row lists the papers an entity came from. Use papercheck_brief to pull a condensed verification brief (evidence quotes, abstract sentence, optional full-text hits via include_text) when an entity's identity or location is in doubt.
7. Report coverage, warnings, and conflicts. Preserve document_id, subchunk_id, event_id, evidence IDs, heading paths, and source hashes in working notes.