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), cad (parametric solid-model design probed analytically, not meshed), structure (atomistic cell + bond graph for DFT/molecular work), pcb (netlist + placement graph → BOM/CPL/DSN + Freerouting), and folder (organizational container for the above).
• 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), cron (push-notification scheduler), 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

| Verb | Use when | |----------|-----------------------------------------------------| | get | You know the name (slug, id, file path) — or you're calling a tool. | | search | You're looking for content by topic or phrase. Hybrid lexical (tsvector) + semantic (pgvector) with RRF fusion. | | put | Create a new ref. Optionally tag and link on creation. | | edit | Rewrite a region of a file-kind ref by content anchors (find-replace, append, insert, replace). | | delete | Soft-delete a numeric ref, or delete a region from a file kind by selector. | | tag | Add and/or remove tags. Three namespaces: closed (STATUS:done), flag (pinned), open (topic-foo). | | link | Add or remove a cross-link to another ref. Vocabulary: related-to, blocks, contradicts, cites, derived-from, supports, … |

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):

| Extra | Enables | Heavy? | |--------------|----------------------------------------------------|--------| | embed | In-process bge-m3 embedder (sentence-transformers + torch) — needed for search unless you point at a remote embedder | yes (~2 GB model on first load) | | paper | paper ingest — Marker PDF → chunks + CrossRef/S2 metadata | yes (pulls torch via Marker) | | calc | calc kind (sympy) | no | | external | math (Wolfram), youtube, web, Perplexity trio, news | no | | patent | patent kind (EPO Open Patent Services) | no | | web | precis web browser UI (FastAPI + Jinja + HTMX) | no | | tex | tex kind — .tex files under PRECIS_ROOT | no | | docx | DOCX file handler | no | | plot | Declarative matplotlib plot renderer | no | | cad-export | cad STL/3MF export (manifold3d CSG kernel) | no | | cad-step | cad exact STEP export (OpenCASCADE B-rep) | yes (~200 MB OCCT libs) | | pcb | pcb footprint resolution (LCSC → KiCad) | no | | dft | structure CIF I/O + symmetry (ASE + spglib) | no | | dft-ml | structure ML-potential relax (ASE + MACE-torch) | yes (pulls torch) | | edgar | edgar kind — SEC EDGAR filings (httpx) | no | | chem | route kind — retrosynthesis tool-pack (RDKit) | no | | mermaid | mermaid diagram kind — pure-Python mermaidx (no Node/Chromium) | no | | tts | Audio export — local TTS for voice drafts + the morning brief (Kokoro) | yes (host-specific) | | asa | asa-bot Discord bridge (discord.py) | no | | all | embed + paper + docx + tex + calc + plot + external + patent + edgar + web + cad-export + mermaid. Excludes the heavier / specialized cad-step, dft, dft-ml, pcb, chem, tts, asa tiers — install those explicitly. | yes |

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

| Var | Purpose | |-------------------------------|--------------------------------------------------| | PRECIS_DATABASE_URL | Postgres DSN (required for all ref kinds). | | PRECIS_OWNER | Canonical username for the human running this instance — the author stamped on a web "ask a follow-up" and the user:<owner> addressee of an ask-user pause. Defaults to owner. | | PRECIS_EMBEDDER | "mock" (dev/tests), "bge-m3" (in-process), or "remote" (HTTP client to precis serve-embeddings). | | PRECIS_EMBEDDER_URL | Required for remote: ordered, comma-separated base URL(s), e.g. http://127.0.0.1:8181. First healthy endpoint wins; rest are fallback. | | PRECIS_ROOT | Single root dir for markdown / plaintext / tex kinds. The trio is hidden when unset; every read/write is normalised against this path (Path.resolve() + relative_to). | | PRECIS_PYTHON_ROOTS | alias:/path,alias2:/path2 — exposed Python repos. | | PRECIS_PYTHON_ALLOW_EXEC=1 | Gate for python runtrace (spawns subprocess). | | EPO_OPS_CLIENT_KEY + _SECRET + PRECIS_PATENT_RAW_ROOT | Enables patent kind. | | ORCID_CLIENT_ID + _SECRET | Enables the orcid researcher-identity kind. | | WOLFRAM_APP_ID | Enables math kind. | | PERPLEXITY_API_KEY | Enables websearch / perplexity-reasoning / perplexity-research. | | PRECIS_CORPUS_DIR | Corpus root(s) for the precis web paper viewer. An os.pathsep-separated list is allowed (e.g. /opt/a/corpus:/opt/b/corpus); the web tries each <root>/<letter>/<cite_key>.pdf in order and serves the first that exists. Point it at the same path the ingest watcher writes to. | | LOG_LEVEL | DEBUG / INFO / WARNING / ERROR. |

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.
• 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.
• 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