一、项目概述

precis-mcp 是一个面向模型上下文协议（Model Context Protocol, MCP）的服务器，专注于为长文档（论文 DOCX、LaTeX、Markdown、TXT、Todo 等）提供精确定位读写能力。其核心思路是把"打开整篇文档→翻页查找段落"的过程抽象成由 URI 选择器定位的小粒度操作，使 LLM 可以在不消耗大量上下文窗口的前提下，对文档中的特定段落、章节、参考文献条目进行导航与编辑。

资料来源：README.md:1-30

服务器在 v3.0.0 中引入了 RefHandler 基类，将论文、Markdown、纯文本等不同文档格式统一抽象为"参考资源（Reference Resource）"模型，并新增了 MarkdownHandler、PlainTextHandler、TodoHandler 三种零依赖或近零依赖的处理器。资料来源：docs/user-facing/seven-verb-surface-migration.md:1-25

二、安装与启动

通过 pyproject.toml 可知项目以标准 PEP 621 方式打包，Python ≥ 3.10，安装方式支持两种主流工具链：

# 方式一：uv（推荐）
uv tool install precis-mcp

# 方式二：pip
pip install precis-mcp

资料来源：pyproject.toml:1-40

启动后，进程会以 stdio MCP 服务器的形式注册七个工具动词。客户端（如 Claude Desktop、MCP Inspector）只需在配置中指定命令 precis-mcp 即可建立连接。资料来源：src/precis/server.py:1-60

激活文档是所有后续动词的前置动作：调用 activate(path_or_uri) 后，服务器会在内部缓存一份可寻址资源树，后续 get/toc/put 都基于这个活动资源工作。

三、七个核心动词

precis-mcp 暴露给 MCP 客户端的固定动词集合共七个，是整个产品形态的"用户面"。

资料来源：src/precis/server.py:60-180、src/precis/dispatch.py:1-80

URI 选择器在 v3.0.0 中由 # 改为 ~，例如 paper:slug~38、doc.docx~PLXDX，避免与 HTML 锚点以及 Markdown 标题语法产生歧义。资料来源：docs/user-facing/seven-verb-surface-migration.md:30-55

四、处理器分层与扩展点

服务器内部把"解析 URI → 路由到具体处理器 → 调用底层动词"分成三层：

flowchart LR
  A[MCP Client] --> B[server.py<br/>七个动词入口]
  B --> C[dispatch.py<br/>URI 解析]
  C --> D{Handler<br/>选择}
  D -->|docx/latex| E[PaperHandler]
  D -->|.md| F[MarkdownHandler]
  D -->|.txt| G[PlainTextHandler]
  D -->|todo:| H[TodoHandler]
  E --> I[RefHandler 基类]
  F --> I
  G --> I
  H --> I

RefHandler 作为基类承载 activate/get/put/search/toc 等通用行为；子类只需实现与文件格式相关的读写与段落分组逻辑（如 group_paragraphs()）。这种结构使得新增格式只需继承 RefHandler 即可复用大部分动词语义。资料来源：src/precis/handlers/ref.py:1-50

put 动词在 v2.2.1 中修复了多段落批量插入时把 ## Heading\n\nBody 合并到同一段落的缺陷，新增 _insert_chunks_after() 辅助函数以保证顺序插入。资料来源：src/precis/handlers/paper.py:120-180

TodoHandler 依赖外部 acatome-store 包，提供有限状态机式的待办管理能力，因此属于可选扩展。资料来源：src/precis/handlers/todo.py:1-40

概述

precis-mcp 是一个面向 LLM 客户端的 MCP（Model Context Protocol）服务器，其核心抽象由 Handler（处理器） 与 Kinds（资源种类） 共同构成。每一个可被读取、检索或修改的资源——无论是 DOCX 论文、LaTeX 草稿、Markdown 文件、纯文本文档，还是 Todo 状态机——都由一个专门的 Handler 负责处理；每个 Handler 会声明它所代表的 kind（资源种类）、可识别的 URI scheme 以及支持的文件扩展名。这种"按类型路由"的架构使新增文件格式时无需改动调度层，只需继承 RefHandler 基类即可被自动纳入。系统通过统一的 URI 语法把"哪一类文件"与"文件中哪一段"两件事合并表达，从而让 LLM 工具调用既简洁又精确。

资料来源：src/precis/handlers/__init__.py:1-80

Handler 架构

RefHandler 抽象基类

v3.0.0 将原本内嵌于 PaperHandler 的通用能力抽离为 RefHandler 抽象基类，作为所有类型处理器的统一父类。子类通过覆盖钩子方法（can_handle、activate、get、put 等）定义各自对 URI 的解析、激活、读取与写入语义；调度层只依赖基类契约，从而实现 Handler 之间的多态替换。

classDiagram
    class RefHandler {
        <<abstract>>
        +kind: str
        +scheme: str
        +extensions: list
        +can_handle(uri) bool
        +activate(uri) Any
        +get(uri, ...) str
        +put(uri, text) str
    }
    RefHandler <|-- PaperHandler
    RefHandler <|-- PatentHandler
    RefHandler <|-- DraftHandler
    RefHandler <|-- MarkdownHandler
    RefHandler <|-- PlainTextHandler
    RefHandler <|-- TodoHandler

资料来源：src/precis/handlers/__init__.py:20-140、src/precis/handlers/paper.py:1-60

已注册的 Handler 与 Kind

资料来源：src/precis/handlers/__init__.py:40-120、src/precis/handlers/markdown.py:1-50、src/precis/handlers/plaintext.py:1-50、src/precis/handlers/draft.py:1-50

文件类型寻址（Addressing）

URI 形式

precis-mcp 的 URI 形如 <scheme>:<selector> 或 <file>:<selector>，两部分各自承担：

• scheme —— 决定由哪个 Handler 处理，等价于"哪一类文件"；
• selector —— 在该文件内部定位位置（段落、节点、章节等），等价于"文件中哪一段"。

v3.0.0 破坏性变更：选择器分隔符

v3.0.0 把选择器分隔符从 # 改为 ~，以避免与 Markdown 标题锚点、URL fragment 冲突。升级时需对历史调用做全局替换。

资料来源：src/precis/handlers/__init__.py:60-160

典型寻址示例

• paper:slug~38：定位某篇论文（按 slug 索引）的第 38 个段落；
• doc.docx~PLXDX：定位本地 DOCX 文件中段落 ID 为 PLXDX 的节点；
• draft:foo.tex~H2-3：定位 LaTeX 草稿第二个二级标题后的内容；
• todo:：进入 TodoHandler 状态机入口，无显式 selector；
• README.md~L20-40：MarkdownHandler 按行号切片。

资料来源：src/precis/handlers/paper.py:30-120、src/precis/handlers/draft.py:30-90、src/precis/handlers/markdown.py:30-80

段落路径与标题分隔符

v0.4.0 起引入 ¶ 段落路径与 | 标题分隔符作为内部路径表达，用于在 get/put 结果中以紧凑形式呈现层级。LaTeX 文档则自 v0.3.1 起改为"原始文件读写"模式，跳过自动段落切分，多行文本按字面写入。

资料来源：src/precis/handlers/draft.py:1-60

演进摘要

• v0.2.0：初始 PyPI 发布，仅支持 DOCX 与 LaTeX 两种 kind；
• v0.3.1：LaTeX 走原始读写分支，避免多行内容被误切；
• v0.4.0：引入 ¶ 段落路径与 | 标题分隔符；
• v3.0.0：抽象出 RefHandler 基类，新增 Markdown、PlainText、Todo 三个零依赖或外部存储依赖的 Handler，并把选择器分隔符从 # 改为 ~。

资料来源：src/precis/handlers/__init__.py:1-60、src/precis/handlers/plaintext.py:1-40

升级提示：迁移至 v3.0.0 时请先做 URI 替换（# → ~），再按需扩展自定义 Handler，只需实现 RefHandler 的钩子方法即可被调度层识别。

概述

precis-mcp 是一个面向 DOCX、LaTeX、Markdown、纯文本以及待办事项的 MCP (Model Context Protocol) 服务，其核心能力是让大语言模型通过统一的 URI 选择器（如 paper:slug~38、doc.docx~PLXDX）对结构化文档进行读取、检索与就地编辑。为了支撑这些跨格式的读写操作，系统需要一个稳定、可迁移、并在后台异步维护索引的存储层。本页聚焦于 src/precis/store/ 子包、SQL 迁移目录以及 src/precis/embedder.py 中负责数据持久化、模式演进与后台向量化的关键模块。资料来源：src/precis/store/store.py:1-40

存储架构

存储层主要由 store.py、pool.py 以及 migrations/baseline/schema.sql 共同构成，采用「连接池 + 嵌入式关系数据库」的模式。pool.py 提供线程/协程安全的连接获取与归还逻辑，避免 MCP 在并发工具调用下反复打开数据库句柄；store.py 则在连接池之上封装了论文、文档、章节、段落、引用键 (slug) 等领域对象的高层 API。资料来源：src/precis/store/pool.py:1-60 资料来源：src/precis/store/store.py:40-120

baseline 模式 (schema.sql) 定义了最基础的表结构，包括文档主表、段落表、章节表、引用键表以及用于全文检索的索引字段；0001_initial.sql 则记录首次迁移的 DDL 变更。两者的分离使得「干净安装」与「升级安装」共享同一份领域模型。资料来源：src/precis/migrations/baseline/schema.sql:1-80 资料来源：src/precis/migrations/0001_initial.sql:1-40

下表概括了核心数据表与其用途：

资料来源：src/precis/migrations/baseline/schema.sql:30-140 资料来源：src/precis/store/store.py:120-200

迁移机制

src/precis/store/migrate.py 负责模式演进。它在启动时检测当前 schema 版本，与 migrations/ 目录中的有序脚本比对，并按顺序应用尚未执行的迁移。迁移脚本以纯 SQL 形式存放，便于审计与回滚；每一次成功的迁移都会写入版本表，从而支持断点续迁。资料来源：src/precis/store/migrate.py:1-100

迁移的设计与项目历史密切相关：v2.x 系列多次涉及引用提示、两级 TOC、段落路径等行为变更，因此新增字段（如 cite_hint、heading_path）通常以幂等 ALTER 形式追加，而非重建表。这种演进方式保障了用户在升级到 v3.0.0 时，原有 paper:slug#N 的引用可以通过自动化迁移平滑切换到 ~ 分隔符。资料来源：src/precis/store/migrate.py:100-180

后台 Worker 与 Embedder

src/precis/embedder.py 提供了与后台向量化相关的抽象：它定义了 embedder 接口（如 embed(text) -> list[float]），并暴露供 store 层在段落入库或更新后触发的钩子。MCP 工具调用 (put、activate) 通常先同步落库，再将段落文本推入后台队列，由 worker 异步生成嵌入向量并写回检索表，从而让 search、toc 等读取路径在响应时只查询已构建好的索引。资料来源：src/precis/embedder.py:1-120

后台 Worker 的存在也解释了在 v2.2.1 中出现的多段落 put 修复：插入多块文本时，store.py 会先按 group_paragraphs() 拆分为独立的 h/p 节点，再分块提交，再交由 embedder 逐块向量化，保证 TOC 与搜索结果在并发写入后仍然一致。资料来源：src/precis/store/store.py:200-260

此外，TodoHandler (v3.0.0 新增) 与可选的 acatome-store 后端通过统一的 store 接口接入，因此迁移模块与连接池同样需要兼容待办事项的 schema，体现了存储层在多 handler 复用方面的中心地位。资料来源：src/precis/store/store.py:260-320 资料来源：src/precis/store/migrate.py:180-240

precis-mcp 是一个 MCP（Model Context Protocol）服务器，用于导航与编辑 DOCX、LaTeX、Markdown、纯文本以及 Todo 类文档。其工程化能力体现在三个维度：通过 Ansible Playbook 实现跨主机的标准化部署、通过 RefHandler 基类与新格式 Handler 实现可插拔的协议扩展、以及通过 worker/watch/heartbeat/embedder 角色实现日常运维自动化。

部署架构

部署由 deploy/site.yml 入口与若干 Playbook 协同完成。site.yml 是 Ansible 的总入口，按顺序拉起不同角色的主机；各角色（worker、watch、heartbeat、embedder）通过独立的 Playbook 进行声明式编排。 资料来源：deploy/site.yml:1-30

flowchart LR
  Site[site.yml] --> Worker[20-precis-worker.yml]
  Site --> Embed[19a-precis-embedder.yml]
  Site --> Watch[28-precis-watch.yml]
  Site --> HB[40-precis-heartbeat.yml]
  Worker --> Tasks[roles/precis_worker/tasks/main.yml]
  Embed --> Tasks
  Watch --> Tasks
  HB --> Tasks

• Worker 角色 (20-precis-worker.yml)：负责安装 precis-mcp 主体服务进程，监听 MCP 客户端连接。 资料来源：deploy/playbooks/20-precis-worker.yml:1-40
• Embedder 角色 (19a-precis-embedder.yml)：在 worker 之前编排，提供向量索引/嵌入相关的可选依赖（早期版本中使用以构建检索能力）。 资料来源：deploy/playbooks/19a-precis-embedder.yml:1-30
• Watch 角色 (28-precis-watch.yml)：监控文档目录变更并触发索引或缓存刷新。 资料来源：deploy/playbooks/28-precis-watch.yml:1-30
• Heartbeat 角色 (40-precis-heartbeat.yml)：周期性向监控端发送心跳，用于健康检查。 资料来源：deploy/playbooks/40-precis-heartbeat.yml:1-25

precis_worker 角色通过 tasks/main.yml 抽象具体安装步骤（包安装、虚拟环境、systemd unit、配置模板渲染），保证各 Playbook 可复用同一执行逻辑。 资料来源：deploy/roles/precis_worker/tasks/main.yml:1-50

插件（Handler）开发

v3.0.0 的重大架构变更之一是将 PaperHandler 中与"引用/URI 选择器"相关的核心逻辑抽取为 RefHandler 基类，使新格式 Handler 不必重复实现。 资料来源：src/precis/handlers/ref_handler.py:1-60

注册新 Handler 的典型路径：

1. 继承基类：新格式（如 Markdown、PlainText）Handler 继承 RefHandler，仅覆写与读写相关的最小接口。MarkdownHandler（.md、.markdown）与 PlainTextHandler（.txt、.text）均为零依赖实现，仅使用标准库。 资料来源：src/precis/handlers/markdown_handler.py:1-30 src/precis/handlers/plaintext_handler.py:1-30
2. 声明 Scheme：Todo 类内容走 todo: scheme，由 TodoHandler 借助 acatome-store 实现状态机语义（pending/in-progress/done），因此需要额外依赖。 资料来源：src/precis/handlers/todo_handler.py:1-40
3. URI 选择器：v3.0.0 将分隔符由 # 改为 ~，例如 paper:slug~38 或 doc.docx~PLXDX，避免与 Markdown 标题锚点冲突。 资料来源：README.md:1-80

Web UI

precis-mcp 主要面向 MCP 客户端（如编辑器、Agent 工具），并未自带独立的 Web 控制台。客户端通过 MCP 协议直接调用 get/toc/put/search 等工具完成导航与编辑。若需 Web 形式的人机界面，通常由前端调用 MCP Server 暴露的 JSON-RPC 端点自行实现——这是该项目刻意保持的"瘦客户端"边界。 资料来源：README.md:80-140

运维与可观测性

日常运维由 watch/heartbeat 两类角色支撑：

• Watch：监听文档目录变更并触发下游 Handler 刷新，降低 MCP 客户端冷启动时的解析延迟。 资料来源：deploy/playbooks/28-precis-watch.yml:10-25
• Heartbeat：周期性上报存活状态，便于在多实例部署中识别僵尸进程。 资料来源：deploy/playbooks/40-precis-heartbeat.yml:10-20

此外，引用系统通过 [@slug] 形式的稳定 slug 标识条目，运维在迁移/重命名文档时可借助 put() 的 slug 字段保持引用连续性。 资料来源：README.md:140-200

Pitfall Log / 踩坑日志

项目：retospect/precis-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/retospect/precis-mcp | host_targets=mcp_host, claude, cursor

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/retospect/precis-mcp | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/retospect/precis-mcp | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/retospect/precis-mcp | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/retospect/precis-mcp | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/retospect/precis-mcp | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/retospect/precis-mcp | release_recency=unknown