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, and structured spatial/temporal evidence. 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
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, and edges
get_spatiotemporal_evidence	Filter structured spatial/temporal evidence
trace_source	Trace IDs back to Markdown content and hashes

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.

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.