precis-mcp

A Model Context Protocol server that gives language-model agents a small, uniform API for reading, writing, and searching across papers, documents, personal state, code, and cached tool calls. Small-model-friendly (7B-class agents are the design target); stores content in PostgreSQL with pgvector.

Status. Actively developed on the v8 line. There is no CHANGELOG — git log is the change story. The kinds catalogue below is a living set: the authoritative, build-specific enumeration is always get(kind='skill', id='precis-help') against a running server (it introspects the live registry), paired with get(kind='skill', id='precis-overview') for the guided tour. Agents should start at precis-toolpath-help ("I want to X — what do I call?").

What it does

One tool surface — seven verbs discriminated by a single kind= argument — over three categories of content. Ref kinds are addressed by slug or integer id (output hands you a compact <2-char><id> handle, e.g. pa5 a paper, me42 a memory); tool kinds take q= or id= and hand back text.

• Reading & reference — paper (ingested research PDF), patent (EPO OPS record), cfp (call-for-proposal / spec doc), oracle (curated wisdom entry), conv (past conversation), pres (slide deck), skill (agent how-to — you're reading one).
• Files under PRECIS_ROOT / code — markdown, plaintext, tex, and python (symbol- and callgraph-aware repo navigator).
• Authored artifacts — draft (chunk-native document that exports to LaTeX/PDF/Word; ADR 0033), cad (parametric solid-model design probed analytically, not meshed; ADR 0041), structure (atomistic cell + bond graph for DFT/molecular work; ADR 0043), pcb (netlist + placement graph → BOM/CPL/DSN + Freerouting; ADR 0042), folder (organizational container for the above; ADR 0045).
• Personal state & knowledge — todo (hierarchical task tree), memory, gripe, anki (spaced-repetition cloze cards → AnkiWeb), citation (verified claim → source quote), finding (chain-of-evidence over a citation chase), job (offline LLM run, child of a todo).
• Identity, comms & audit — orcid (researcher-identity hub; ADR 0039), cron (push-notification scheduler; ADR 0030), message (proactive outbound), alert (machine-detected ops condition), agentlog (per-run attribution trail), provenance (derivation audit).
• Tool kinds (stateless or cache-backed) — calc (local SymPy), math (Wolfram), youtube (transcript), web (fetch + extract), wikipedia (on-demand article), websearch / perplexity-reasoning / perplexity-research (Perplexity Sonar tiers).
• Discovery — random: pick a random indexed block to stumble into content when you don't know what to ask for.

The active set depends on which optional extras and env vars are configured (see Install) — a kind whose dependency or env var is missing simply drops off the surface. This list is a snapshot; get(kind='skill', id='precis-help') enumerates the kinds wired in your build, and get(kind='skill', id='precis-overview') gives the design-rationale tour with an example handle per kind.

Seven verbs

Address by id= for names, q= for content. No URI selector strings for ids; region selectors inside files use the compact slug~SELECTOR shape (e.g. notes--meeting~L42-58).

Install

pip install 'precis-mcp[all]'

Extras (each enables its kinds; omit any you don't want):

A bare pip install precis-mcp gives you the state kinds (todo, memory, gripe, anki, conv, oracle, skill, random) and the markdown / plaintext / python file kinds. (The tex file kind also rides on PRECIS_ROOT, but its .tex parsing pulls in the [tex] extra's lxml.) Optional deps surface as InitError at boot: the kind silently drops off the tool surface with a WARNING, the server stays up.

Database

precis-mcp requires PostgreSQL with the pgvector extension. The CLI precis migrate applies the forward-only numbered SQL migrations in src/precis/migrations/. See 0001_initial.sql for the schema.

createdb precis
psql precis -c 'CREATE EXTENSION pgvector;'

export PRECIS_DATABASE_URL=postgresql://localhost/precis
export PRECIS_EMBEDDER=bge-m3   # or "mock" for tests
precis migrate

Run

precis serve speaks MCP over stdio. Wire it into your agent's MCP config:

{
  "mcpServers": {
    "precis": {
      "command": "precis",
      "args": ["serve"],
      "env": {
        "PRECIS_DATABASE_URL": "postgresql://localhost/precis",
        "PRECIS_EMBEDDER": "bge-m3",
        "PRECIS_ROOT": "/absolute/path/to/notes",
        "PRECIS_PYTHON_ROOTS": "myrepo:/absolute/path/to/myrepo"
      }
    }
  }
}

Environment variables

This table is the getting-started subset. precis reads ~150 PRECIS_* variables in all — feature toggles, autonomy modes, budgets, model ids, compute-routing, paths, and secrets. For the exhaustive catalog — every var, its code default, the value deployed to each cluster service, and an assessment of whether that state is right — see docs/reference/config-variables.md. The policy for adding a var (the three-tier scheme) is docs/conventions/env-vars.md.

Design highlights

• Seven verbs, one kind=. The whole surface is get/search/put/edit/delete/tag/link. No per-kind bespoke tools. See docs/user-facing/seven-verb-surface-migration.md.
• Content-anchored edits. edit(find=..., before=..., after=...) resolves by literal content match; unique/first/all/nth policy; fuzzy nearest-line hint on not-found. Pure resolver in precis.utils.edit_resolve; ships for markdown, plaintext, and python. See docs/user-facing/edit-protocol-spec.md.
• Hybrid search. Lexical tsvector + semantic pgvector (bge-m3) with Reciprocal Rank Fusion. Block-level; paper chunks, markdown paragraphs, Perplexity answers, web pages all searchable.
• Per-chunk discovery layer (F20). Every body chunk gets KeyBERT keywords stored on chunks.keywords TEXT[] (GIN-indexed canonical forms) + chunks.keywords_meta JSONB (versioned short/long pairs with bge-m3 cosine scores), populated by the chunk_keywords worker. The paper TOC view (view='toc') DP-clusters those keyword arrays at request time (src/precis/utils/toc_db.py) — superseding the dropped ref_segments / ref_segment_sentences precompute. The citation kind closes the loop: an agent's writing-thread workflow can persist verified claim → source quote records (see precis-citation-help).
• Progressive disclosure. Seven verbs and a kind= argument is the whole visible surface. Behind it sits a fan-out of ~25 per-kind help skills, dozens of read views, an anchored edit protocol, args-dict view payloads, and a tag/link vocabulary — none of which the agent has to know up front. Every response can emit a next= breadcrumb, every error names the skill that explains it, and get(kind='skill', id='precis-<kind>-help') unfolds the manual for whichever capability the agent just bumped into. Think exploding pocket knife: the tool grows blades as you reach for them, instead of advertising 20 unfamiliar buttons in tools/list. (UX literature calls this pattern progressive disclosure.)
• The todo tree. kind='todo' is a hierarchical task graph — a level gradient (strategic → tactical → subtask, plus recurring), a PRIO sort key, meta.auto_check wait-for-condition leaves, and meta.schedule recurring spawn (the Watches umbrella). It is the unified substrate for intent, execution, and review; kind='job' (an offline LLM run) always hangs off a todo via parent_id, and the dispatch worker is the canonical path from a todo's meta.executor to a queued job. See precis-tasks-help.
• Two-profile worker. Every background pass runs under one of two long-running daemons: precis worker --profile=system (embeddings, keywords, dispatch, sweepers — safe to run on every node) and --profile=agent (the LLM-heavy review/planner rotation, each pass self-gated by env + a load-average ceiling). Per-pass daemons are retired.
• HintBus. Any layer can emit deduplicated, novelty-decayed tips that are rendered after the verb's main output. Keeps slim models from drowning in self-inflicted reminders.
• Slim exception surface. BadInput / NotFound / Gone / Unsupported / Upstream / RateLimited / Internal, each carrying a single copy-pasteable next= "breaking hint".
• psycopg 3 sync, raw SQL. No SQLAlchemy, no Alembic, no async below FastMCP — stdio's serial workload doesn't buy anything from async.
• In-tree handlers, entry-point plugins. Core kinds are hand-ordered in precis.dispatch.boot(). Third-party kinds can register themselves via the precis.handlers entry-point group without forking — see docs/user-facing/plugin-authoring.md.

Extending

Write a plugin handler in 3 steps — see the one-pager at docs/user-facing/plugin-authoring.md and the canonical tiny example in src/precis/handlers/calc.py.

# your plugin's pyproject.toml
[project]
dependencies = ["precis-mcp>=8.0.0"]

[project.entry-points."precis.handlers"]
wikipedia = "precis_wikipedia:WikipediaHandler"

Plugin failures are logged and skipped — one bad plugin cannot brick the server.

CLI

# Serving
precis serve                       # Start the MCP stdio server.
precis serve-embeddings            # HTTP embedding service (server side of
                                   #   PRECIS_EMBEDDER=remote; /healthz /readyz
                                   #   /model /embed /metrics).
precis web [--host H --port P]      # Browser UI: Tasks / Papers / Console /
                                   #   Conversations / Status tabs (needs the
                                   #   [web] extra; binds 127.0.0.1:9100, no
                                   #   auth — reach it over Tailscale).

# Background processing
precis worker [--profile system|agent]
                                   # Drive the background passes. 'system'
                                   #   (default) = embeddings/keywords/dispatch/
                                   #   sweepers; 'agent' = the LLM-heavy review
                                   #   + planner rotation. --only X --once for
                                   #   ad-hoc backfills.
precis watch [PATH]                # Watch an inbox dir and ingest dropped PDFs
                                   #   (papers / books / presentations routing).
precis add <pdf|url>               # Ingest one paper on the spot.

# Database
precis migrate                     # Run pending forward-only SQL migrations.
precis db ...                      # Schema utilities (dump-schema, …).
precis schema-doc                  # Generate the Mermaid ER diagram
                                   #   (docs/design/schema.md) from a DSN.

# Interactive & inspection
precis repl                        # Interactive verb console (tab-complete).
precis draft ...                   # Manage / export draft-kind documents.
precis stats | logs | stubs | verify
                                   # Corpus stats, event logs, stub triage,
                                   #   integrity checks.
precis cron | heartbeat            # Scheduler tick / liveness ping.

# One-shot jobs
precis jobs ingest[-md|-oracles] ...   # Pre-warm files under PRECIS_ROOT.
precis jobs import-perplexity ...      # Bulk-import Perplexity web-UI answers.
precis jobs {watch,list,run}-patent-watches / sweep-patent-fulltext
                                       # Saved CQL patent watches (patent kind).
precis jobs check-provenance / sync-retraction-watch
                                       # Provenance + retraction audits.

Run any subcommand with --help for the full option list.

Utility scripts

The scripts/ dir holds workspace-side utilities that run against a precis store but live outside the published CLI surface. See scripts/README.md for full coverage; the high-traffic ones:

• paper-monitor-ingest-dir — drop-and-go PDF ingest watcher.
• perplexity-monitor-ingest-dir — bulk-import Perplexity markdown exports.
• find-citing-papers — sweep S2 for new papers citing the precis corpus, with bge-m3 cosine rerank and several noise- reduction filters; reports land in a paper-ingest/ review dir.
• enrich-paper-identifiers / retrofit-acatome-external-ids — backfill DOI / arXiv ids on legacy refs.

Roadmap

• book, rmk file handlers. (tex and docx shipped.)
• web bookmark mode + Wayback enrichment (gripe:3681 phase 2 + 4 — see OPEN-ITEMS.md).
• voice kind — STT/TTS bound to transcript refs (see docs/user-facing/voice-kind-spec.md).
• SDK extraction (precis-core) once the plugin API has settled.

Documentation

• AGENTS.md — start here to contribute or change code. The canonical guide: conventions, workflow, definition-of-done, ingest guarantees.
• docs/mission.md — the mission, the pitch narrative, and the current corpus facts (positioning, not architecture — the single source for decks and talks).
• docs/README.md — the documentation landing index (directory-by-directory map).
• docs/architecture.md — the system manual: a narrative overview tying the surface, kinds, storage, todo-tree, and workers together.
• docs/design/schema.md — the generated DB schema diagram (Mermaid ER, produced from the live database — can't drift).
• docs/decisions/README.md — the ADR index (one record per decision; supersession graph). The individual ADRs live in docs/decisions/.
• docs/reference/config-variables.md — the full PRECIS_* config catalog: every var, its default, the value deployed to each cluster service, and a correctness assessment.
• docs/user-facing/plugin-authoring.md — write a third-party handler.
• docs/user-facing/seven-verb-surface-migration.md — verb surface design rationale.
• docs/user-facing/edit-protocol-spec.md — anchored edits across file kinds.
• docs/user-facing/file-kinds-unified-addressing.md — the slug~SELECTOR address grammar.
• docs/user-facing/python-kind-spec.md — python navigator design.
• docs/user-facing/patent-kind-spec.md — EPO OPS integration.
• docs/user-facing/paper_ingest.md — .acatome bundle ingest path.
• docs/design/storage-v2.md — full schema + discovery-layer design.
• docs/decisions/0026-precis-web-surface.md — the precis web browser UI (Tasks / Papers / Conversations / Console / Status).
• docs/decisions/0029-multi-root-corpus-pdf.md — why PRECIS_CORPUS_DIR accepts a list of roots.
• src/precis/data/skills/precis-citation-help.md — citation kind + verifier-workflow agent surface.
• src/precis/data/skills/precis-toc-help.md — TOC machinery (segments, sentences, matryoshka keywords).
• Git history (git log) — what shipped in each phase (no CHANGELOG file).

Contributing

The repo lives at retospect/precis-mcp. Issues and PRs welcome. Development workflow:

uv sync --all-extras --group dev
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run mypy src tests

Run the full test suite in the dev container, which bakes every optional extra and wires the test database:

scripts/dev pytest                       # full suite, all extras
scripts/dev bash -lc "ruff check . && ruff format --check . && mypy src tests && pytest"

A host uv run pytest only sees the torch-free base install, so the full run there fails with spurious missing-extra errors (sympy, marker, lxml, …) — use it for targeted subsets only.

All tooling goes through uv run (host) or scripts/dev (container) — see AGENTS.md for the full workflow and definition-of-done.

License

GPL-3.0-or-later. See the full text at gnu.org/licenses/gpl-3.0.html.