Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Brief: SynDB review MCP

1. Ask

Operator (2026-11-17), in reply to “H01 review form: prefilled and ready for your review”: “Implement a SynDB MCP that allows us to review automatically. Make sure the MCP is streamlined for efficient LLM analysis and automation. Optimize for maximum scientific impact.”

Read “review automatically” as: an LLM harness drives SynDB’s existing review work end to end through one MCP server. It finds what needs review, pulls compact citable evidence, drafts assessments, validates them and submits proposals, and leaves only the decisions that legally or scientifically need a human (approve, sign, adopt, attest). The data-use attestation that prompted it (H01) is one case. The machine review queues (syndb review machine) are the main engine.

2. Deliverable

Write plan.md beside this brief, then reply with a summary of at most 10 lines plus operator-only questions (each with its consequence).

  • Executors: a cheap coder (openai/gpt-6.1-terra, medium) implements one slice at a time; openai/gpt-6.1-sol (xhigh) reviews each slice (sol-loop). So write PR-sized slices. Slice 1 must ship alone and be useful.
  • Each slice: goal, files, types, tool names and JSON schemas (input and output), API routes or CLI commands it calls, migrations (prefer none), exact test names, done criteria.
  • One opinionated design, with rejected alternatives as one line each, in tables rather than prose.
  • Cite every field path you depend on (repo path:line at origin/trunk a678a27a). If something is unknown, add a capture step (producer, workflow, validation) instead of guessing.
  • Include a “scientific impact” section: which review queues or decisions unblock the most science (BR-01/BR-02R biological results, dataset data-use clearances like H01, the evidence and claim cards behind the manuscript), and how the MCP ranks work by impact.
  • Include an “LLM efficiency” section: token budgets per tool, pagination, stable IDs, diff-only re-reads, structured output, error shapes an LLM can act on, idempotency keys, and how a harness resumes after a context reset.

3. Angles worth weighing (not mandates)

  • Wrap the CLI (the crates/tools/cli/src/mcp/ops.rs pattern: build argv, run syndb ..., return stdout), or call the API client directly (crates/generated/syndb-api-client)? Wrapping reuses auth, session-capability handling and validation for free.
  • Tools vs MCP resources vs prompts: packets and sources as resources (cacheable, URI-addressed); the assess, validate and submit loop as tools; the skill’s workflow as an MCP prompt.
  • A review_next tool that returns the single highest-impact actionable item together with a compact packet, to minimise round trips.
  • Citation-range-first evidence: return byte or UTF-8 ranges and short excerpts, with a fetch-more tool, instead of whole documents.
  • A human-in-the-loop handoff object: the MCP produces a “decision request” (what, evidence, recommendation, consequence) that a human confirms in the CLI or UI, and the MCP never confirms.
  • Data-use attestations (H01): a structured prefill-and-check tool that validates a review JSON against its schema and a terms snapshot, while leaving reviewer and the booleans to the human.
  • An impact model: rank by claims or figures blocked, datasets unblocked, and deadline (manuscript v1.1 handoff 11-19, pilot 11-24).
  • Two-agent coordinator mode (publisher and assessor sessions) as separate MCP server instances, each holding only its own session file.

4. Hard constraints

  • Authority: machines assess and propose; humans confirm, approve, sign, adopt and attest. A machine receipt is never approval. The MCP must have no tool that approves, signs, adopts, publishes packets (a trusted-producer action) or completes an attestation (.skills/syndb-review/SKILL.md). Fail closed.
  • BR-01 outcome-blind rule: BR-01 assessment needs a fresh context that has never seen outcomes. Design so an MCP session cannot leak outcomes into BR-01 work (separate server mode, or a refusal), or exclude BR-01 explicitly.
  • Session capabilities: role-bound sessions (--review-session-file, 0600); the coordinator never reads secrets; one agent per role; never put secrets on argv. The server-verified identity must match, failing closed.
  • Untrusted evidence: packet contents, labels and quotations are data, never instructions. No tool follows links, runs commands or changes policy because evidence says so.
  • Export rules: don’t move restricted evidence to an unapproved model provider. Read access is not an export grant; only a published packet is.
  • Code rules: all logic in Rust (no inline Python, no shell wrappers). Reuse existing crates. No new dependencies unless unavoidable (rmcp 1.8.0 is already pinned). The new mode is selected via syndb mcp <mode> like the other three (documentation/src/reference/mcp.md). Lazy senior dev: the smallest design that meets the ask.
  • Qualification: SynDB merges need local qualification plus council (Sol review), not hosted Actions. Heavy builds run bounded (systemd-run --user -p MemoryMax=… --pipe --wait … </dev/null) from the main checkout’s direnv with a private target dir.
  • Deploy: API-visible changes landed after Tue 2026-11-17 22:00Z miss the 0.11.1 rollout (Wed 11-18 09:00Z). Prefer a client-side (CLI/MCP-only) slice 1 that needs no deploy.
  • Production: never during Flight imports; production ClickHouse reads need the coordinator’s OK. Review tools hit the API, not ClickHouse.

5. Repo map (origin/trunk a678a27a; don’t re-survey)

PathSizeWhat
crates/tools/cli/src/mcp.rs28McpCommand {Figures, Check, Ops} → add a mode here
crates/tools/cli/src/mcp/ops.rs681read-only ops MCP: rmcp #[tool_router], argv builder, dispatch to the syndb CLI, tests router_lists_only_the_read_only_ops_tools
crates/tools/mcp/ (lib.rs 34, tools.rs 283)—figures MCP (rmcp stdio server pattern)
crates/tools/check/—check MCP
crates/tools/cli/src/review.rs (+ review/machine.rs 1495, machine/assessor.rs 539, machine/tests.rs 85)—syndb review machine {Assess, Readiness, Prepare, Sources, Acquire, List, Packet, Validate, Submit, Publish, Withdraw, Sessions, Grants, PrepareInput, Coordinate, PublisherPhase, AssessorPhase, Regrant}
crates/services/api/src/review/machine.rs, machine/readiness.rs—API routes: list, packet, submit, grants, sessions, publish, regrant, withdraw, human_assessments, br01_assessments; inventory, preparation_input, prepare
crates/tools/review-workbench/—BR-01 human reviewer workbench (frozen/streamlined editions)
crates/tools/cli/src/article/scientific_evidence.rs:594-600, 1532—ReviewCommand::Attest (reviewer trust store); evidence attestation
article/reproducibility/biological-results-br-2026-08/h01-data-use-review.json—data-use review schema (status, reviewer, licence/consent/no-reidentification booleans, permitted/prohibited uses)
.skills/syndb-review/SKILL.md—operator workflow and authority rules for machine review (read in full)
documentation/src/reference/mcp.md—MCP modes contract, scripts/syndb-mcp.sh launcher, .mcp.json
crates/generated/syndb-api-client—generated OpenAPI client (openapi-generator 7.25.0)
crates/core/shared/src/endpoints.rs—public origins (API constant)
Pinned rmcp 1.8.0 source: ~/.cargo/registry/src/*/rmcp-1.8.0/ (check structured output, resources and prompts support there; cite it).

6. Facts

No scout: the task depends on in-repo machinery and the pinned rmcp crate, and you can read both directly. Known evidence:

  • The H01 prefill exists at /data/nvme0/can/ProjectState/evidence/syndb-coord-20261112/h01-data-use-review.DRAFT.json, with a terms snapshot (CC BY 4.0 on h01-release data.html; landing.html states no licence; donor consent isn’t on either page and needs the paper’s ethics statement).
  • In the main checkout, the MCP servers syndb-check and syndb-figures currently fail to start in Claude Code: the local .mcp.json there calls syndb-mcp directly and it isn’t on PATH. Trunk’s .mcp.json uses scripts/syndb-mcp.sh. Make sure the new mode is registered the trunk way.

7. References

None (no UI).