Research Kernel MCP is a durable, evidence-first research substrate for MCP clients. It stores public research artifacts and avoids hidden reasoning traces.
The model stays creative. The kernel stays deterministic:
- persistent SQLite state;
- append-only event log;
- typed research atoms and graph edges;
- source, artifact, benchmark, proof, and counterexample evidence;
- deterministic Morph-style reformulation templates;
- fail-closed PopperPad-style claim promotion;
- frontier scoring for the next research action;
- MCP tools, resources, and prompts.
Prerequisite: uv.
Run the deterministic backend self-test straight from GitHub:
uvx --from git+https://github.com/TheDarkLightX/Research-Kernel-MCP.git \
research-kernel-mcp --self-testRun the stdio MCP server:
RESEARCH_HOME="$HOME/.research-kernel" \
uvx --from git+https://github.com/TheDarkLightX/Research-Kernel-MCP.git \
research-kernel-mcpClaude Desktop / compatible stdio clients:
{
"mcpServers": {
"research-kernel": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/TheDarkLightX/Research-Kernel-MCP.git",
"research-kernel-mcp"
],
"env": {
"RESEARCH_HOME": "/absolute/path/to/research-kernel-state"
}
}
}
}The model proposes research objects; deterministic rules decide whether claims may be promoted. A claim cannot become SUPPORTED unless the promotion gate has the required support evidence, refutation attempt, dependencies, provenance, contradiction search, replay evidence when applicable, and rationale.
This repository is prepared for the three main MCP discovery paths:
- Official MCP Registry:
server.jsonuses the GitHub namespaceio.github.TheDarkLightX/research-kernel-mcp. - Glama:
glama.jsondeclares the repository maintainer for ownership/claiming. - Smithery: the source install above gives the repository a reproducible stdio entry point suitable for repository-based publishing.
The official MCP Registry validates the referenced package, so publishing research-kernel-mcp==0.1.0 to PyPI is the final prerequisite before running mcp-publisher publish. See docs/REGISTRY_LAUNCH.md.
By default the server writes to:
internal/research_kernel/
Override with:
RESEARCH_HOME=/absolute/path/to/research-vaultArtifacts are copied into RESEARCH_HOME/artifacts by SHA-256 hash. File
artifacts are accepted only from the repo root, RESEARCH_HOME, or paths in
RK_ARTIFACT_ALLOWLIST unless RK_ALLOW_OUTSIDE_ARTIFACTS=1 is set.
Every state-changing operation is also appended to RESEARCH_HOME/events.jsonl
for replay and external ledger ingestion.
The MCP exposes the compact tool surface from the design spec:
rk_startrk_atom_addrk_linkrk_retrieverk_semantic_search(optional Jev reading aid; preview by default)rk_kurate_discoverrk_literature_importrk_morphrk_refuterk_evidence_attachrk_scorerk_frontierrk_promoterk_report
rk_promote is fail-closed. A claim cannot become SUPPORTED unless it has
support evidence, a refutation attempt, dependencies, provenance, contradiction
search, replay evidence when required, and a rationale.
The hosted companion adds structured negative discovery memory: hard negatives are derived only from source-pinned bounded checker counterexamples for the exact tested recipe and original revision; soft negatives preserve attempted approaches, root causes, representation changes and conditions for revisiting them. rk_negative_record never grants proof authority. Its read path, rk_negative_memory, returns both with deterministic information-completeness triage and explicit generalization obligations. See docs/NEGATIVE_MEMORY_CONTRACT.md. The Python stdio MCP also exposes rk_negative_record and rk_negative_memory, using the same soft-negative discovery fields. It has no independently trusted bounded-check receipt verifier, so even a user-asserted rk_refute(counterexample_is_actual=true) is soft for negative-memory reuse; the legacy refutation status and promotion rules are unchanged. This feature does not silently grant the Python kernel new proof authority.
The Python server now also exposes rk_negative_record (reasoned failure, scope, assumptions, reported witness, possible generalization, alternative representation, revisit conditions) and rk_negative_memory (historical retrieval and next validation action). Both are advisory; no proof certificate or pruning power is inferred.
rk_refute treats counterexample text as planning context unless
counterexample_is_actual=true is set. Actual counterexamples create a
COUNTEREXAMPLE atom, add a REFUTES edge, and mark the target REFUTED.
Evidence attached with only a summary can support a claim, but it does not
satisfy promotion provenance. Include source_uri, artifact_path, or
artifact_text on at least one evidence record before promoting a claim.
rk_semantic_search scores every record in a bounded run with Jev, caches exact
validated responses, and retains linked evidence/corrections independently of
relevance scores. It returns original text and source hashes, without changing
claim status or promotion rules. Preview is offline; live export needs an exact
run allowlist and a locally configured TypeSafe credential. See
the adapter contract.
rk_kurate_discover performs a bounded, read-only query against Kurate's
paper-ranking feed and stores each result as a RESULT atom in CANDIDATE
state. The adapter preserves exact arXiv versions, null metrics, a canonical
snapshot hash, and an immutable copy of the response. Scores are stored as
integer milli-points so the discovery receipt is deterministic. The normalized
research-discovery/candidate/v1 object matches PopperPad's Kurate adapter,
while each system retains its own validation and authority gate.
The authority boundary is deliberate:
- Kurate objects use
authority="triage_only"; - evidence uses
source_type="kurate_discovery"orkurate_discovery_batch; - neither source type belongs to the promotion gate's supporting-evidence allowlist;
- failed requests and schema drift become
UNKNOWNnegative-knowledge atoms; - a later assessment for the same arXiv work supersedes the older discovery receipt without deleting it.
Example MCP call:
rk_kurate_discover(
run_id="my-run",
search="symmetric projection operator",
categories_json="[\"math.AG\",\"math.NT\"]",
sort_key="novelty",
limit=8
)
Set apply_triage_scores=true only when the run explicitly authorizes Kurate's
novelty, significance, and refutation-value assessments to influence frontier
ordering. Even then, the imported evidence score remains zero. Verify the exact
primary source and attach independent paper, proof, experiment, or test
evidence before attempting claim promotion.
rk_literature_import consumes an existing provider JSON export. Citracer
imports retain normalized paper nodes and citation relations. MOSAIC imports
retain deduplicated papers and any partial-source errors. The exact JSON bytes
are stored by content hash.
rk_literature_import(
run_id="my-run",
provider="citracer",
artifact_path="research/trace.json"
)
The artifact must be inside the repository, RESEARCH_HOME, or an explicit
RK_ARTIFACT_ALLOWLIST root. Both providers remain triage_only. Parsed
citations use a CITES graph edge that is excluded from support, refutation,
dependency, and promotion gates. Missing retrieval-policy metadata is recorded
as unspecified, not inferred.
Fleet coordinators can use the receipt-bound command adapter. It verifies the
frozen export hash before and after import and writes a
codex-fleet-literature-import-receipt/v1 file containing stable rk://
references:
python3 internal/research_kernel_mcp/literature_importer.py \
--home RESEARCH_HOME --run-id fleet-literature \
--goal "Fleet literature triage" \
--artifact export.json --artifact-sha256 sha256:... \
--provider mosaic --receipt receipt.json \
--import-id mosaic-broad --importer-id research-kernelThe receipt remains triage_only and does not satisfy a promotion gate.
rk://runs/{run_id}/summaryrk://runs/{run_id}/graphrk://runs/{run_id}/frontierrk://atoms/{atom_id}rk://claims/{claim_id}rk://artifacts/{artifact_hash}rk://memory/similar/{query}rk://memory/contradictions/{claim_id}rk://reports/latest
research.kernel_moderesearch.startresearch.decomposeresearch.refuteresearch.morphresearch.evidence_reviewresearch.promote_claimresearch.reportresearch.next_frontier
Self-test:
.venv/bin/python internal/research_kernel_mcp/server.py --self-testStdio MCP:
uv run --no-project --with mcp python internal/research_kernel_mcp/server.pyStreamable HTTP:
uv run --no-project --with mcp python internal/research_kernel_mcp/server.py \
--transport streamable-http \
--mount-path /mcpFocused tests:
pytest -q tests/internal/test_research_kernel_mcp.py- The kernel stores research artifacts, evidence, and graph state.
- Hidden chain-of-thought stays outside the artifact store.
SUPPORTEDmeans the local gate passed. External publication or production posture still needs the relevant replay, review, and release gates.- Morph reformulations are candidate search objects until separately tested.
Research Kernel MCP is licensed under the Apache License, Version 2.0. See
the repository root LICENSE file.
A Sites-compatible FCIS companion adds private team workspaces, revision-bound claims, bounded checker receipts, selected package exchange, negative result memory and a non-monetary contribution ledger. See the pilot documentation. The Python kernel retains its existing tools and adds selected-output export/import bridges.