YRB HES Evidence

简体中文

Acknowledgement

This project is deeply inspired by Zleap-AI/SAG. We sincerely thank the SAG contributors for the Event/Entity organization, graph-oriented retrieval, and evidence synthesis ideas that shaped this adapter.

YRB-HES Evidence MCP is an independent YRB3 adaptation. Please consult and respect the upstream SAG license and attribution requirements when reusing SAG materials.

Overview

YRB-HES Evidence MCP is a read-only Model Context Protocol (MCP) server for evidence retrieval in Yellow River Basin human–earth systems reviews. It exposes bounded access to the rag_sag.yrb3_v3 PostgreSQL schema and preserves source provenance for every returned claim.

The service connects document metadata, abstract screening, heading/subchunk context, SAG Event/Entity associations, verified edges, optional BGE-M3 vector recall, structured spatial/temporal evidence, and the geospatial tables copied into rag_sag.yrb3_v3. Geocoded canonical entities, hydro relations, source boundaries, spatial units, and audit rows retain their original table names; the former yrb3.public copy is an archive, not an active MCP source. Production pipelines remain responsible for Qwen extraction, database writes, and audit runs.

Scope and tools

Tool	Purpose
healthcheck	Verify database identity, schema, tables, and current counts
describe_data_foundation	Describe actual tables/columns and semantic data layers in the unified v3 foundation; defaults to a compact summary and accepts detail=full
find_canonical_fields	Map a user concept or alias to registered YRB-HES semantic fields
build_question_schema	Build a read-only five-layer task plan for retrieval, evidence, analysis, response, and validation
get_document_overview	Inspect one document's processing coverage
search_evidence	Retrieve lexical/vector/Event/Entity/spatiotemporal evidence
compare_evidence	Build bounded cross-paper comparison rows
get_subchunk_context	Read local heading and source context
search_entity	Find canonical SAG entities
expand_entity	Expand entities to Events, evidence, edges, and geocode
get_spatiotemporal_evidence	Filter structured spatial/temporal evidence
search_geocode	Look up coordinates and verdicts for geocoded spatial entities (min_score filter, doc_refs provenance)
get_document_geocode	Return geocoded spatial entities linked to one document
papercheck_brief	Condensed verification brief for one entity: evidence quotes, abstract sentence, optional full-text hits
trace_source	Trace IDs back to Markdown content and hashes

search_evidence and compare_evidence accept compact=True to trim responses to identifiers, quotes and citations (~10x smaller for interactive use).

build_question_schema is planning-only. It does not execute a Q1-Q4 analysis, modify data, or expose arbitrary SQL. Its draft must be confirmed before any bounded analytical query is added.

describe_data_foundation discovers the geospatial tables in the same rag_sag.yrb3_v3 schema as the literature and SAG tables. The response retains the geocode_sidecar key for client compatibility, but it is a compatibility projection rather than a second database connection. The default summary lists table and column names without expanding every database-column descriptor; request detail=full when full column metadata is needed. Geocode fields such as coordinates, score, verdict, in_yrb9, and in_yrb_hydro describe spatial normalization only and do not replace formal study-area evidence or execute Q1-Q4 analyses.

The server is read-only: it performs no DDL, DML, UPSERT, deletion, model inference, or extraction. Use exact document_id, subchunk_id, Event/Entity IDs, evidence IDs, heading paths, and source hashes in downstream synthesis.

Install

git clone <repository-url> yrb_hes_mcp
cd yrb_hes_mcp
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

The runtime requires Python 3.11+ and PostgreSQL access. The default connection targets dbname=rag_sag through the remote Unix socket. Set YRB3_MCP_DATABASE_URL only when a controlled alternative is required; the legacy YRB3_MCP_GEOCODE_DATABASE_URL is no longer used.

Run over SSH/stdio

cd /home/wst/projects/yrb_hes_mcp
PYTHONPATH=/home/wst/projects/yrb_hes_mcp \
  /home/wst/projects/yrb_hes_mcp/.venv/bin/python \
  -m mcp_server.server

Register the same SSH-stdio command in the Codex MCP configuration. Keep database credentials outside the repository.

Tests

python -m pytest tests/test_import.py
python tests/protocol_smoke.py
python tests/current_state_audit.py

A passing protocol smoke verifies transport and tool contracts. It does not certify full-corpus processing or scientific validity.

Evidence rules

Call healthcheck before retrieval. Use search_evidence for discovery, compare_evidence for cross-paper scaffolding, and trace_source before quoting. Keep publication year distinct from study-evidence year. Treat spatial labels as candidates until the formal research-area field or source wording confirms them. If the edge table is empty, report the available Event–Entity neighborhood without inventing edges. Always report coverage, warnings, and conflicts.

Limitations

Coverage depends on the current Qwen, Embedding, spatiotemporal, and Edge processing state in rag_sag.yrb3_v3. The MCP provides retrieval and provenance; the Agent and human reviewer remain responsible for scientific interpretation and final acceptance.

SAG acknowledgement

We sincerely thank Zleap-AI/SAG and its contributors. SAG's structured Event/Entity, graph, and retrieval-enhancement design provided important methodological foundations for this cross-paper evidence index. This project adds YRB3-specific database contracts, human–earth systems categories, spatiotemporal evidence, and Markdown source tracing.

License

MIT. See LICENSE.