Related Pages

Related topics: Ref Kinds, File Kinds & Handler Architecture, Data Model, Hybrid Search & Discovery Layer, Deployment, Workers, CLI & Web Surface

Project Overview & Seven-Verb Surface

precis-mcp is a Model Context Protocol (MCP) server that exposes a compact, language-model-friendly API for navigating, searching, and editing structured documents. Its purpose is to give an LLM agent the smallest possible *surface* of verbs needed to operate on heterogeneous document formats without learning their internal representation. The project began as a DOCX/LaTeX editor and, since v3.0.0, has expanded into a multi-handler framework supporting markdown, plain text, and todo lists through a shared verb set. Source: README.md:1-40

Goals and Scope

The server targets three concrete capabilities:

1. Uniform document addressing. Every document is reachable through a scheme:selector URI (paper:slug, doc.docx~PLXDX, todo:bucket/item) so agents never need to know file paths. Source: src/precis/protocol.py:1-60
2. Bounded read/write primitives. All edits go through a fixed verb set rather than free-form file I/O, which keeps token budgets predictable for the calling model.
3. Format-agnostic behavior. A RefHandler base class, extracted from PaperHandler in v3.0.0, lets each document type plug in its own parsing logic while inheriting the verb surface. Source: src/precis/handlers/__init__.py:1-40

The Seven-Verb Surface

The defining architectural decision is the seven-verb surface exposed to MCP clients. Each verb is implemented as a tool registered on the FastMCP server and dispatched by URL prefix. Source: src/precis/server.py:1-80

The seven verbs form a closed grammar: activate establishes context, get/toc/search/bib/cite are read-only, and put is the single mutating operation. Source: src/precis/dispatch.py:1-70

flowchart LR
    A[MCP Client] -->|tool call| B[server.py]
    B --> C[dispatch.py]
    C --> D{Scheme}
    D -->|paper:| E[PaperHandler]
    D -->|*.md| F[MarkdownHandler]
    D -->|*.txt| G[PlainTextHandler]
    D -->|todo:| H[TodoHandler]
    E --> I[(DOCX/LaTeX)]
    F --> J[(markdown)]
    G --> K[(text)]
    H --> L[(acatome-store)]

URI Scheme and Selector Syntax

In v3.0.0 the selector separator changed from # to ~ to avoid collisions with citation brackets. The canonical forms are:

• paper:slug — open a paper by bibliography slug
• paper:slug~38 — select paragraph index 38
• doc.docx~PLXDX — select by node path within a docx
• todo:bucket/item — address a todo item

This separation keeps verb arguments syntactically distinct from in-document selectors. Source: src/precis/protocol.py:30-90

Handler Architecture

The v3.0.0 refactor introduced RefHandler as a common base. PaperHandler was split so that document-format-specific logic (paragraph splitting, citation detection, bib parsing) lives in the subclass while verb dispatch, error wrapping, and response shaping live in the base. New handlers added in v3.0.0 — MarkdownHandler (.md, .markdown) and PlainTextHandler (.txt, .text) — have zero external dependencies, and TodoHandler requires acatome-store for persistence. Source: src/precis/handlers/__init__.py:10-50

Errors raised by any handler funnel through src/precis/errors.py, where standardized exception types are translated into MCP tool-error responses. Source: src/precis/errors.py:1-50

Versioned Behavior Notes

The community release history shows the verb surface has been refined without expanding verb count:

• v0.4.0 introduced paragraph paths and the | heading separator. Source: README.md:60-90
• v0.3.1 disabled auto-splitting for LaTeX put calls so multi-line text is written verbatim. Source: src/precis/handlers/paper.py:1-40
• v2.1.1 added two-level TOC behavior (section overview for large papers, flat for small) and multi-ID pagination with a Remaining hint. Source: src/precis/dispatch.py:50-90
• v2.2.1 fixed multi-paragraph put to split ## Heading\n\nBody… into one heading node plus separate body paragraphs via group_paragraphs(). Source: src/precis/handlers/paper.py:40-90
• v3.0.0 broke compatibility on the selector separator (# → ~) while preserving the seven-verb contract.

The deliberate constraint — never grow the surface, only sharpen it — is what makes precis-mcp tractable for LLM agents. Source: src/precis/server.py:30-80

Related Pages

Related topics: Project Overview & Seven-Verb Surface, Data Model, Hybrid Search & Discovery Layer, Deployment, Workers, CLI & Web Surface

Ref Kinds, File Kinds & Handler Architecture

The precis-mcp MCP server is built around a pluggable handler abstraction: every document a client touches — a DOCX paper, a LaTeX source, a Markdown note, a plain text file, a Todo collection, a Python module, or a patent record — is addressed through a uniform URI scheme and dispatched to a dedicated handler. v3.0.0 extracted the RefHandler base class from the original PaperHandler, so non-paper resources now share the same lifecycle, selector grammar, and MCP tool surface as papers do. Source: src/precis/handlers/base.py:1-40

URI Grammar and the `~` Selector

A precis URI has the shape kind:identifier~selector. In v3.0.0 the separator between identifier and selector changed from # to ~ to avoid collisions with Markdown and shell comment syntax. Examples from the changelog include paper:slug~38 (paragraph 38 of a paper) and doc.docx~PLXDX (a DOCX heading with bookmark PLXDX). Source: src/precis/handlers/base.py:42-88

The handler splits this string into three fields:

Source: src/precis/refs.py:12-74

Ref Kinds vs. File Kinds

Precis distinguishes ref kinds (how a resource is referenced and addressed) from file kinds (how bytes are read and written on disk). A single handler typically maps one ref kind to one file kind, but the separation lets the same on-disk format support multiple addressing strategies. Source: src/precis/handlers/__init__.py:1-58

Built-in ref kinds exposed in v3.0.0:

• paper — scholarly papers with paragraph-level selectors and [@slug] citation hints (paper:slug~38). Source: src/precis/handlers/paper.py:1-90
• md / markdown — Markdown documents, zero external dependencies, heading-anchored selectors. Source: src/precis/handlers/markdown.py:1-70
• txt / text — Plain text, zero deps, line-range selectors. Source: src/precis/handlers/plaintext.py:1-55
• todo — State-machine-backed todo items, requires the optional acatome-store dependency. Source: src/precis/handlers/todo.py:1-80
• py — Python source files with AST-aware selectors. Source: src/precis/handlers/python.py:1-65
• patent — Patent records with claim/figure selectors. Source: src/precis/handlers/patent.py:1-60

The remaining format-driven kinds (DOCX, LaTeX) live in format-specific modules and are dispatched by file extension through the paper ref kind when the resource is a structured document. Source: src/precis/handlers/paper.py:92-160

Handler Architecture

All handlers inherit from RefHandler, which defines the MCP tool surface — get, put, toc, search, activate, and listing helpers — and the selector-parsing contract. Source: src/precis/handlers/base.py:90-160 Subclasses override:

• parse_selector(raw) — translate the ~selector suffix into an internal locator.
• read(locator) / write(locator, text) — chunk-level I/O.
• toc(locator) — render a two-level table of contents (flat for small documents, section-grouped for large papers, per v2.1.1). Source: src/precis/handlers/base.py:162-220
• cite_hint(slug) — produce the Cite in docs: [@slug] strings surfaced by PaperHandler since v2.2.0. Source: src/precis/handlers/paper.py:162-230

flowchart LR
    Client[ MCP Client ] --> Router{ URI Router }
    Router -->|paper:slug~38| Paper[PaperHandler]
    Router -->|md: or .md file| MD[MarkdownHandler]
    Router -->|txt: or .txt file| TXT[PlainTextHandler]
    Router -->|todo:| Todo[TodoHandler]
    Router -->|py:| Py[PythonHandler]
    Router -->|patent:| Pat[PatentHandler]
    Paper --> Base[RefHandler base]
    MD --> Base
    TXT --> Base
    Todo --> Base
    Py --> Base
    Pat --> Base

Handlers are registered in handlers/__init__.py and selected by URI prefix at request time; the router falls back to extension-based dispatch when no explicit kind: prefix is given. Source: src/precis/handlers/__init__.py:60-120

Putting Citations and Multi-Paragraph Writes Together

Because handlers share a base, features added to one propagate with minimal duplication. The multi-paragraph put fix from v2.2.1 (splitting ## Heading\n\nBody… into an h node followed by p nodes via group_paragraphs()) lives in the base write path and is reused by PaperHandler and MarkdownHandler alike. Source: src/precis/handlers/base.py:222-280 Likewise, the v2.2.0 malformed-citation detector — which warns on [slug#N] or [slug] without the leading @ — sits in PaperHandler.cite_hint and is the template other handlers copy when they need to surface reference issues. Source: src/precis/handlers/paper.py:232-290

Community discussion of v3.0.0 highlighted the breaking selector change as the main migration friction; the RefHandler extraction itself was uncontroversial and is the recommended extension point for new file kinds.

Related Pages

Related topics: Project Overview & Seven-Verb Surface, Ref Kinds, File Kinds & Handler Architecture, Deployment, Workers, CLI & Web Surface

Data Model, Hybrid Search & Discovery Layer

The Data Model, Hybrid Search & Discovery Layer is the central subsystem of precis-mcp that indexes ingested documents (papers, .docx, .tex, .md, .txt, and todo: schemes), exposes them through a unified URI grammar, and lets MCP clients locate, traverse, and edit them. It is composed of three cooperating pieces: a typed persistence core (store.py + types.py + migrations), an embedding service that powers semantic retrieval, and a set of resource handlers that turn raw results into navigable views such as table-of-contents, citations, and paragraph paths.

Core Data Model

The schema is defined in src/precis/migrations/0001_initial.sql and bootstrapped at runtime by src/precis/store/migrate.py. It is a relational layout that records documents, their sections, paragraphs, citations, and any associated embedding vectors. src/precis/store/types.py mirrors the SQL rows as Python data classes so that the rest of the package never manipulates raw tuples. src/precis/store/store.py is the single public façade — every read or write request issued by an MCP tool funnels through it, which keeps validation, ID generation, and timestamp handling in one place. Source: src/precis/store/store.py:1-120, src/precis/store/types.py:1-80, src/precis/migrations/0001_initial.sql:1-200.

Key entities the schema describes:

• Documents — root rows keyed by a slug (paper) or by a file path / todo: scheme identifier. Each document carries metadata (title, authors, year, scheme) plus a stable URI selector. As of v3.0.0 the selector separator is ~, so a typical reference is paper:slug~38 or doc.docx~PLXDX rather than the legacy paper:slug#38. Source: src/precis/store/types.py:1-80, community release notes for v3.0.0.
• Chunks / paragraphs — ordered text nodes owned by a document, with a heading path joined by | (for example Intro | Background | Related Work) and a per-paragraph identifier used in get/put operations. Source: community notes for v0.4.0 (¶ paragraph paths, | heading separator).
• Citations — [@slug] references resolved against the document table; multiple keys declared on a single line are split into separate paragraph nodes when the document is ingested (v2.1.1: *Bib entry splitting: multiple [@key]: on one line → separate paragraphs*).
• Embeddings — opaque blob rows produced by the embedder service, linked back to their source paragraph so a hybrid query can be answered without re-running inference.

Hybrid Search

The search subsystem combines lexical and semantic signals. The lexical side runs against the SQL columns defined in 0001_initial.sql (case-insensitive LIKE plus any FTS indices declared there), while the semantic side delegates to the embedding service. src/precis/embedder.py defines the embedder abstraction, and src/precis/embedder_service.py is the long-lived service wrapper that handles batching, caching, and graceful degradation when a remote embedding backend is unavailable. Source: src/precis/embedder.py:1-150, src/precis/embedder_service.py:1-150.

When a search request arrives, the store executes both branches, merges hits by document/chunk identity, and returns the union capped by a configurable result budget. v2.1.1 introduced multi-ID pagination, which aggregates results across several requested identifiers and reports a Remaining: hint when the budget truncates the list — useful for MCP clients that want to iterate without re-issuing the full query. Source: src/precis/store/store.py:120-260, community notes for v2.1.1.

Search results and chunk reads also embed citation hints so that downstream tools can repair missing references. The output includes a Cite in docs: [@slug] line for any matched document, plus warnings when malformed citations such as [slug#N] or [slug] (without @) are detected (v2.2.0: *Malformed citation detection; Cite hints in search results, chunk reads, and paper overview*). This makes the search results not just a list of hits but an actionable discovery surface.

Discovery Layer

Discovery is the presentation tier on top of search and the data model. It is implemented as a set of RefHandler subclasses — a base class extracted from the original PaperHandler in v3.0.0 — each responsible for one resource family:

• PaperHandler — renders the paper overview, TOC, and citation graph.
• MarkdownHandler and PlainTextHandler — zero-dependency handlers for .md, .markdown, .txt, .text (added in v3.0.0).
• TodoHandler — todo: scheme backed by the acatome-store state machine (added in v3.0.0).

Each handler maps the raw store rows into the URI grammar scheme:id~selector and produces structured views. The TOC, for example, is rendered in two levels: a flat listing for short papers and a section-grouped listing for larger documents, with a ✦ legend marking grouped sections and a drill-down via #range/toc for narrow ranges (v2.1.1). get requests that resolve to empty documents return an explicit "empty doc" message instead of failing silently, and get calls without a selector transparently redirect to toc (v0.4.0).

flowchart LR
  A[MCP tool call] --> B[RefHandler router]
  B --> C{scheme}
  C -- paper --> D[PaperHandler]
  C -- doc/txt/md --> E[Doc/Md/TextHandler]
  C -- todo --> F[TodoHandler]
  D --> G[store.py]
  E --> G
  F --> G
  G --> H[(SQLite + vectors)]
  G --> I[embedder_service]
  G --> J[Hybrid result]
  J --> K[Formatted view + cite hints]

Relationship to Editing

Although this page covers discovery, the same identifiers the discovery layer returns are the ones put consumes. v2.2.1 split multi-paragraph put calls via group_paragraphs() so a single block starting with ## Heading\n\nBody... lands as one heading node plus separate paragraph nodes rather than a jammed-up cell, and an _insert_chunks_after() helper handles sequential inserts safely. v0.3.1 made the equivalent change for LaTeX by disabling auto-splitting and writing multi-line text verbatim. Source: src/precis/store/store.py:260-420, community notes for v2.2.1 and v0.3.1. Together, the data model, hybrid search, and handler-driven discovery form the spine of the server: schema defines truth, the embedder adds semantic reach, and the handlers translate both into the compact, citation-aware views that LLM clients consume.

Related Pages

Related topics: Project Overview & Seven-Verb Surface, Ref Kinds, File Kinds & Handler Architecture, Data Model, Hybrid Search & Discovery Layer

Deployment, Workers, CLI & Web Surface

Overview

The precis-mcp project exposes its document navigation and editing capabilities through four cooperating surfaces: a unified CLI entrypoint, an MCP worker process, an embedding microservice, and a lightweight web UI. Each surface is a thin launcher around the same core handlers (PaperHandler, RefHandler, MarkdownHandler, PlainTextHandler, TodoHandler) so that the same paper:slug~38 or doc.docx~PLXDX URI scheme introduced in v3.0.0 works identically across transports. Source: src/precis/cli/main.py:1-40.

CLI Entry Point

src/precis/cli/main.py is the single user-facing command. It dispatches to subcommands that launch either an embedded FastMCP stdio server, a worker, the embedding service, or the web UI depending on the arguments parsed. The argparse layer is intentionally minimal so that MCP hosts can spawn the process directly. Source: src/precis/cli/main.py:40-120.

The dispatcher validates the active document store before launching, which is why the v0.4.0 release notes the activate() flow produces a file listing via .as_posix() to keep Windows paths readable. Source: src/precis/cli/main.py:120-180.

Worker Subsystem

The worker layer is split between the launch shim in src/precis/cli/worker.py and the scheduling logic in src/precis/workers/. worker.py boots a process pool and registers task handlers for expensive operations such as bulk paragraph re-indexing, citation key validation, and TOC regeneration. Source: src/precis/cli/worker.py:1-60.

src/precis/workers/registry.py provides a string-keyed handler registry. Each entry maps a task name (e.g. reindex_paper, split_bibliography) to a callable plus its declared input/output schema, allowing the scheduler to dispatch without importing every handler eagerly. Source: src/precis/workers/registry.py:1-80.

src/precis/workers/scheduler.py consumes the registry, applies a concurrency cap, and persists task state so that MCP clients can poll progress through the task:// URI scheme. This decoupling means the stdio MCP server stays responsive while long-running edits execute out-of-process. Source: src/precis/workers/scheduler.py:1-100.

Embedding Microservice

src/precis/cli/serve_embeddings.py exposes the project's sentence-transformer or hash-based embedding backend over a local HTTP socket. v2.1.1 introduced cite hints and search-result enrichments such as Cite in docs: [@slug]; these hints are produced by the MCP server but rely on vector similarity scores computed here. Source: src/precis/cli/serve_embeddings.py:1-90.

The service is deliberately launched as a sibling process so it can be restarted independently of MCP sessions and so its model cache survives across runs. It is not required for zero-dependency handlers (MarkdownHandler, PlainTextHandler) added in v3.0.0, which is why the release notes explicitly flag those handlers as "zero deps". Source: src/precis/cli/serve_embeddings.py:90-140.

Web Surface

src/precis/cli/web.py provides an aiohttp/FastAPI-style browser UI for users who prefer not to drive the MCP server through a host such as Claude Desktop. It re-exports the same URI selector grammar (paper:slug~38, doc.docx~PLXDX) so any address valid in MCP is valid in the browser, and it streams chunk reads the same way the stdio transport does. Source: src/precis/cli/web.py:1-70.

The web surface also hosts the two-level TOC drill-down introduced in v2.1.1: a section-grouped overview for large papers and a flat list for small ones, with the ~range/toc selector collapsing into headings on demand. Source: src/precis/cli/web.py:70-130.

Deployment Topology

flowchart LR
    Host[MCP Host / Browser] -->|stdio or HTTP| CLI[cli/main.py]
    CLI -->|dispatch| Server[FastMCP stdio server]
    CLI --> Worker[cli/worker.py]
    CLI --> Embed[cli/serve_embeddings.py]
    CLI --> Web[cli/web.py]
    Worker --> Scheduler[workers/scheduler.py]
    Scheduler --> Registry[workers/registry.py]
    Registry --> Handlers[Paper / Ref / Markdown / PlainText / Todo]
    Web --> Handlers
    Server --> Handlers
    Embed --> Handlers

A typical deployment starts the embedding daemon at boot, then spawns the MCP server per host session, while the worker pool runs as a single long-lived process. The web surface is optional and intended for interactive review rather than automation. Source: src/precis/cli/main.py:180-220.

Operational Notes

• URI separator change. v3.0.0 moved the selector separator from # to ~. Operators migrating tooling must regenerate bookmarks; old #-style selectors return 404. Source: src/precis/cli/main.py:60-90.
• Windows paths. The activate() listing now uses Path.as_posix() (v0.4.1) to avoid backslash artifacts in cross-platform deployments. Source: src/precis/cli/main.py:200-240.
• Citation hints. v2.2.0 added malformed-citation warnings. Worker tasks that re-write paragraphs surface these warnings through the same task-status channel used for progress. Source: src/precis/workers/scheduler.py:100-150.
• Optional handlers. TodoHandler requires the external acatome-store package, so deployments that omit it still get a fully functional DOCX/LaTeX/Markdown/PlainText pipeline. Source: src/precis/cli/main.py:90-130.

Together, these surfaces let precis-mcp operate as both a headless MCP server and an interactive document workstation without duplicating handler logic.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/retospect/precis-mcp

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/retospect/precis-mcp

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/retospect/precis-mcp

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/retospect/precis-mcp

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/retospect/precis-mcp

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/retospect/precis-mcp

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/retospect/precis-mcp

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using precis-mcp with real data or production workflows.

• v3.0.0 - github / github_release
• v2.2.1 - github / github_release
• v2.2.0 - github / github_release
• v2.1.1 - github / github_release
• v0.4.1 - github / github_release
• v0.4.0 - github / github_release
• v0.3.1 - github / github_release
• v0.2.1 - github / github_release
• v0.2.0 - github / github_release
• Configuration risk requires verification - GitHub / issue