# https://github.com/retospect/precis-mcp Project Manual

Generated at: 2026-07-19 09:35:49 UTC

## Table of Contents

- [Project Overview & Seven-Verb Surface](#page-overview)
- [Ref Kinds, File Kinds & Handler Architecture](#page-kinds)
- [Data Model, Hybrid Search & Discovery Layer](#page-data)
- [Deployment, Workers, CLI & Web Surface](#page-ops)

<a id='page-overview'></a>

## Project Overview & Seven-Verb Surface

### Related Pages

Related topics: [Ref Kinds, File Kinds & Handler Architecture](#page-kinds), [Data Model, Hybrid Search & Discovery Layer](#page-data), [Deployment, Workers, CLI & Web Surface](#page-ops)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/retospect/precis-mcp/blob/main/README.md)
- [src/precis/server.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/server.py)
- [src/precis/dispatch.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/dispatch.py)
- [src/precis/handlers/__init__.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/__init__.py)
- [src/precis/protocol.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/protocol.py)
- [src/precis/errors.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/errors.py)
- [src/precis/handlers/paper.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/paper.py)
</details>

# 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]()

| # | Verb | Purpose |
|---|------|---------|
| 1 | `activate` | Load a document URI into the working session and list available files |
| 2 | `get` | Read a chunk, paragraph, or section by selector |
| 3 | `toc` | Return a table of contents (one- or two-level) |
| 4 | `search` | Full-text or structural search across the active document |
| 5 | `put` | Replace or insert paragraphs at a target selector |
| 6 | `bib` | Read or update bibliography entries |
| 7 | `cite` | Resolve and validate `[@key]` citations, returning cite hints |

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]()

```mermaid
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]()

---

<a id='page-kinds'></a>

## Ref Kinds, File Kinds & Handler Architecture

### Related Pages

Related topics: [Project Overview & Seven-Verb Surface](#page-overview), [Data Model, Hybrid Search & Discovery Layer](#page-data), [Deployment, Workers, CLI & Web Surface](#page-ops)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/precis/handlers/__init__.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/__init__.py)
- [src/precis/handlers/base.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/base.py)
- [src/precis/handlers/paper.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/paper.py)
- [src/precis/handlers/markdown.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/markdown.py)
- [src/precis/handlers/plaintext.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/plaintext.py)
- [src/precis/handlers/todo.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/todo.py)
- [src/precis/handlers/python.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/python.py)
- [src/precis/handlers/patent.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/patent.py)
- [src/precis/refs.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/refs.py)
</details>

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

| Field      | Meaning                                                    |
|------------|------------------------------------------------------------|
| `kind`     | Dispatch key — `paper`, `md`, `txt`, `todo`, `py`, `patent`, or a bare filename extension. |
| `identifier` | Slug, filename, or schema-specific handle.               |
| `selector` | Optional position/fragment, parsed per-kind (paragraph index, heading bookmark, line range, state, etc.). |

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]()

```mermaid
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.

---

<a id='page-data'></a>

## Data Model, Hybrid Search & Discovery Layer

### Related Pages

Related topics: [Project Overview & Seven-Verb Surface](#page-overview), [Ref Kinds, File Kinds & Handler Architecture](#page-kinds), [Deployment, Workers, CLI & Web Surface](#page-ops)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/precis/store/store.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/store/store.py)
- [src/precis/store/types.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/store/types.py)
- [src/precis/store/migrate.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/store/migrate.py)
- [src/precis/migrations/0001_initial.sql](https://github.com/retospect/precis-mcp/blob/main/src/precis/migrations/0001_initial.sql)
- [src/precis/embedder.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/embedder.py)
- [src/precis/embedder_service.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/embedder_service.py)
</details>

# 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).

```mermaid
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.

---

<a id='page-ops'></a>

## Deployment, Workers, CLI & Web Surface

### Related Pages

Related topics: [Project Overview & Seven-Verb Surface](#page-overview), [Ref Kinds, File Kinds & Handler Architecture](#page-kinds), [Data Model, Hybrid Search & Discovery Layer](#page-data)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/precis/cli/main.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/cli/main.py)
- [src/precis/cli/web.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/cli/web.py)
- [src/precis/cli/worker.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/cli/worker.py)
- [src/precis/cli/serve_embeddings.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/cli/serve_embeddings.py)
- [src/precis/workers/registry.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/workers/registry.py)
- [src/precis/workers/scheduler.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/workers/scheduler.py)
</details>

# 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]().

| Subcommand | Purpose | Backed by |
|------------|---------|-----------|
| (default) | stdio MCP server for MCP hosts | `FastMCP` over stdio |
| `worker`   | background job runner | `precis.cli.worker` |
| `embed`    | long-running embedding daemon | `precis.cli.serve_embeddings` |
| `web`      | browser surface for humans | `precis.cli.web` |

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

```mermaid
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.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: retospect/precis-mcp

Summary: 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
- Evidence strength: source_linked
- 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.
- Evidence: capability.host_targets | https://github.com/retospect/precis-mcp

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/retospect/precis-mcp

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/retospect/precis-mcp

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/retospect/precis-mcp

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/retospect/precis-mcp

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/retospect/precis-mcp

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/retospect/precis-mcp

<!-- canonical_name: retospect/precis-mcp; human_manual_source: deepwiki_human_wiki -->