Skip to main content
Glama
YRB-HES Evidence MCP

YRB-HES Evidence MCP

by TIGERwu0118

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

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

Validate and structure a caller-defined five-layer contract 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 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.

Available Tools

9 tools
compare_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

    A3.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      A 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.
      4
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      A 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.
      1
      6
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Read-only MCP server for querying an evidence-aware knowledge vault with temporal and provenance-aware data, supporting agent memory and semantic graph projections.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for local, source-agnostic research, turning briefs into platform-specific searches and cited evidence dossiers with PostgreSQL storage and optional browser capture.
      MIT