Universal Research MCP connects a Codex host to research records, original sources, and rebuildable search indexes. Before a material claim can receive an evidence-eligibility receipt, the server re-reads the exact registered source range and checks its current SHA-256 revision.

The contract: search returns candidates; verification establishes source integrity; the host still reviews relevance, conflicts, and the final claim.

v0.8.5 documentation release. The runtime feature baseline remains frozen at v0.8.4. This release adds the detailed Korean user guide and ships the session-scope confirmation workflow; it adds no retrieval or ingest capability and grants no operating-system or host permissions.

The problem it addresses

A retrieved passage can come from an old index, the wrong line range, or a file that changed after registration. A plausible answer can hide that broken connection. This project makes the connection inspectable.

Architecture

flowchart LR
    A[Candidate search] --> B[Re-read registered source]
    B --> C{Range and SHA-256 match?}
    C -- No --> D[Block evidence]
    C -- Yes --> E[Evidence eligibility]
    E --> F[Host reviews meaning and conflicts]
    F --> G[Answer or abstain]

The workflow verifies source identity and location. It does not decide whether the source is relevant, resolve conflicts, or prove that the source is true.

Write path: prepare immutable draft → external human approval → commit the bound transaction. A shared writer lock and journal protect canonical writes; interrupted multi-file work remains recoverable rather than silently successful.

Module map and authority boundaries

One minute through the workflow

Open the demo guide →

The offline interactive workflow highlights five steps over 60 seconds. Download the HTML file and open it in a browser; GitHub's file view shows its source. It uses only explanatory text, makes no model calls, and is not a recording of a live MCP run.

The guide links each step to the implementation. It does not create a source registration, approval, or benchmark.

Three design decisions

Read the decisions and alternatives: ADR-0001 · ADR-0002 · ADR-0003.

Try the released package

For the complete installation, Codex setup, source-registration, approved ingest, semantic retrieval, troubleshooting, and update flow, read the Korean user guide.

python -m pip install "universal-research-mcp==0.8.5"
universal-research --version
universal-research init ./my-research

Expected version: 0.8.5. Initialization creates an empty project; it does not crawl your files. Use the input tutorial to register sources and create an approved record before expecting search results.

Then register the local server in Codex:

[mcp_servers.universal_research]
command = "universal-research"
args = ["serve", "--no-auto-index"]
cwd = "/absolute/path/to/my-research"

--no-auto-index explicitly disables index writes at startup. Refresh derived indexes separately when that operation is approved; omitting the flag enables automatic indexing in the CLI. Do not use a read-only reference project as the writable research root. See the host integration guide for the full setup.

What ships in v0.8.5

• Lexical, local semantic, hybrid, and adaptive candidate retrieval.
• Exact registered-range fetch and deterministic evidence-eligibility receipts.
• Append-only records, shared CLI/MCP writer locking, and recoverable ingestion.
• Codex governance contracts and a secure harness for separately approved runs.
• An optional, explicitly published read-only demo corpus.
• Managed local semantic snapshots bound to an immutable model revision and verified file inventory; setup requires its own approved plan.

The supported host is Codex. The wheel excludes experimental generation providers, plugin-owned agent runtime, and provider execution harness modules. Local embeddings do not imply generation-provider support.

Semantic retrieval · Secure harness · Public demo deployment

Experiments and limits

Completed development evidence exists. A full confirmatory product-effect benchmark does not. These are separate studies; their sample sizes and scores must not be pooled.

A completed 96-run development study

24 public synthetic tasks × four conditions, one run per task and condition. The separate condition-blinded evaluator was an LLM, not a human reviewer.

Public synthetic development corpus: 24 tasks × 4 conditions × 1 run. The paired 95% interval includes zero; this is not confirmatory product evidence.

For filesystem → MCP + eligibility, the paired unsafe-assertion difference was −11.1 percentage points, with a task-bootstrap 95% interval of −33.3 to +11.1 points. It includes zero. The gated condition used 1.55× tokens and 1.61× time, and still failed on conflicting and semantically irrelevant current evidence. Evidence-only retrieval had more unsafe assertions than filesystem. These are narrow development observations, not proof of general hallucination reduction or improved research quality.

Methods, evaluation cost, and all caveats remain in the full four-condition report. Historical reports call the eligibility check “Claim Gate”; those names are retained for provenance, not a claim that the tool verifies truth.

Other evidence, kept separate

All five completed reports · Integration diagnostic · Benchmark disclosure

Boundaries that remain

• Hashes establish revision identity, not the truth of source prose.
• Evidence count is based on distinct event records, not independent authors or independent scientific observations.
• The MCP cannot globally control native agents or other processes started by an unrestricted host. Approval enforcement has a defined execution boundary.
• This is not an authenticated private remote service or a multi-tenant SaaS. Public deployment needs a separately reviewed operational boundary.
• Historical synthetic results do not establish released-v0.8.5 efficacy, production reliability, or statistically decisive superiority.

Security model · Governance contracts

Development reference

python -m pip install ".[test]"
python -m pytest -q
ruff check universal_research_mcp
mypy --no-incremental --cache-dir=/dev/null universal_research_mcp
python -m build
python scripts/validate_distribution_artifact.py dist/*.whl
python scripts/ci_smoke.py dist/*.whl

License: MIT