retospect/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, with a web
interface (see how it works).
See it
A two-minute tour, section by section, lives right here in the repo at
**guide/README.md**. A narrated version (audio) lives at
**retospect.github.io/precis-mcp**
once Pages is enabled. Video: coming.
**Set it up:** single machine —
docs/setup-single-machine.md ·
cluster (multi-host, ansible) — deploy/README.md.
> **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 — **eight 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
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 (analytic-SDF solid modeling —
designs are probed, not meshed; unit-required DSL), se
(structural-envelope designs: blocks/ports/joints with DRC,
stability + prestress analysis, a fastener engine, STL/3MF/STEP
export), nm (molecular-machine designs on the same block
surface — envelopes bound to atomistic structures, mechanics
ceilings), 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 todo 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.
Eight 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, … |
| more | Fetch the next page of a truncated response (more(cursor='…') — every truncation footer hands you the cursor). |