# YRB-HES Evidence MCP

[简体中文](readme_cn.md)

> **Acknowledgement**
>
> This project is deeply inspired by [Zleap-AI/SAG](https://github.com/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` | 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

```bash
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

```bash
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

```bash
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](https://github.com/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](LICENSE).