YRB-HES Evidence MCP
Provides read-only evidence retrieval from a PostgreSQL database (rag_sag.yrb3_v3 schema), with tools for document overviews, evidence search, cross-paper comparison, entity expansion, spatiotemporal filtering, and source tracing.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@YRB-HES Evidence MCP Find evidence comparing water quality trends across the Yellow River Basin"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Tool | Purpose |
| Verify database identity, schema, tables, and current counts |
| Describe actual tables/columns and semantic data layers in the unified v3 foundation; defaults to a compact summary and accepts |
| Map a user concept or alias to registered YRB-HES semantic fields |
| Validate and structure a caller-defined five-layer contract for retrieval, evidence, analysis, response, and validation |
| Inspect one document's processing coverage |
| Retrieve lexical/vector/Event/Entity/spatiotemporal evidence |
| Build bounded cross-paper comparison rows |
| Read local heading and source context |
| Find canonical SAG entities |
| Expand entities to Events, evidence, edges, and geocode |
| Filter structured spatial/temporal evidence |
| Look up coordinates and verdicts for geocoded spatial entities (min_score filter, doc_refs provenance) |
| Return geocoded spatial entities linked to one document |
| Condensed verification brief for one entity: evidence quotes, abstract sentence, optional full-text hits |
| 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 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.serverRegister 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.pyA 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.
Available Tools
9 toolscompare_evidenceA
Build bounded cross-paper comparison rows with claims, entities, spatiotemporal evidence and source locators.
Inputs: query (required), limit, year_to, language, +5 more. Returns: result
expand_entityC
Expand one canonical entity to linked Event, Subchunk, spatiotemporal evidence and verified edges.
Inputs: entity_id (required), limit, request_id. Returns: result
get_document_overviewB
Return metadata, abstract screening, heading, Subchunk, SAG and spatiotemporal counts for one document.
Inputs: document_id (required), request_id. Returns: result
get_spatiotemporal_evidenceB
Query structured spatial and temporal evidence with document, Subchunk and research-area filters.
Inputs: limit, request_id, document_id, subchunk_id, +3 more. Returns: result
get_subchunk_contextB
Return one Subchunk, its title path, adjacent context and linked Event/spatiotemporal evidence.
Inputs: subchunk_id (required), radius, request_id. Returns: result
healthcheckB
Check PostgreSQL, yrb3_v3 tables, read-only identity and current row counts.
Inputs: request_id. Returns: result
search_entityA
Search canonical SAG entities by name, alias key and optional entity type.
Inputs: name (required), limit, request_id, entity_type. Returns: result
search_evidenceB
Search YRB3 evidence with exact if_yrbhg gate, lexical Subchunk recall, Event expansion and spatiotemporal attachment.
Inputs: query (required), limit, year_to, language, +5 more. Returns: result
trace_sourceB
Trace an Event, Subchunk or spatiotemporal evidence ID back to Markdown content and hashes.
Inputs: source_id (required), request_id. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct operation: document overview, subchunk context, evidence search, comparison, entity search, entity expansion, spatiotemporal query, source tracing, and health check. Though search_evidence and get_spatiotemporal_evidence both deal with evidence, the former is full-text with event expansion while the latter is structured query with filters, so they remain clearly distinguishable.
Most tools follow a clear verb_noun pattern (get_document_overview, search_evidence, compare_evidence, expand_entity, trace_source). The lone exception is 'healthcheck', which is a single compound noun rather than a verb-led name, making it a minor deviation from the otherwise consistent convention.
With 9 tools, the server is well-scoped for its purpose. Each tool addresses a distinct aspect of evidence retrieval and exploration, from document-level overview to fine-grained spatiotemporal queries and source tracing, without unnecessary redundancy or bloat.
The read-only evidence surface is fairly comprehensive: it covers document overview, subchunk context, evidence search, comparison, entity retrieval/expansion, spatiotemporal filtering, and source tracing. A minor gap is the lack of a direct document listing method, though search_evidence can partially compensate by returning relevant documents.
Maintenance
Related MCP Connectors
Read-only MCP over an agentic SLR workspace with per-claim citation verification
Read-only MCP over an agentic SLR workspace with per-claim citation verification
Auditable MCP server for PubMed, Europe PMC, ClinicalTrials.gov, and bioRxiv/medRxiv queries
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Related MCP Servers
- AlicenseAqualityCmaintenanceA traceable Chinese-history MCP server that enables querying of nine classical Chinese texts (e.g., 史记, 汉书) with citations and honest status labels. It provides four tools to search events, persons, places, and qualities, all with provenance.43MIT
- AlicenseAqualityCmaintenanceA read-only Chinese legal evidence MCP server that provides deterministic retrieval of authentic legal sources with chain-of-custody receipts, designed for Codex, Claude Code, and OpenCode.16Apache 2.0
- FlicenseNot gradedqualityCmaintenanceRead-only MCP server for querying an evidence-aware knowledge vault with temporal and provenance-aware data, supporting agent memory and semantic graph projections.-
- AlicenseNot gradedqualityDmaintenanceMCP server for local, source-agnostic research, turning briefs into platform-specific searches and cited evidence dossiers with PostgreSQL storage and optional browser capture.MIT