YRB-HES Evidence MCP

简体中文

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.

Related MCP server: DeepLaw

Scope and tools

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 question-agnostic and planning-only. It does not register, classify, or infer scientific question modules. The caller or Agent may supply any opaque question_id (for example D1Q1) together with the population, analysis unit, deduplication keys, measures, evidence policy, boundary policy, retrieval tools, and expected output claims. The builder validates and structures that contract without executing retrieval, modifying data, or exposing arbitrary SQL.

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 perform scientific-question analysis.

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.