convez.ai
MCP ServerBusca & PesquisaAvançado
retospect

Precis MCP

retospect/precis-mcp

API unificada de 7 verbos para ler, escrever e buscar papers, docs, código e estado

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que fornece uma API uniforme de sete verbos para agentes LLM acessarem papers, documentos, código, estado pessoal, patentes e chamadas de ferramentas em cache. Otimizado para modelos pequenos (7B) com busca híbrida em PostgreSQL + pgvector.

Instalação

$npx convez-ai retospect/precis-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
11
Forks
2
Acompanhando
2
Saúde
57%
Último commit
há 1 dia
Versão
v8.35.1
Issues abertas
1
Contribuidores
3

Casos de uso

  • Agentes IA consultarem múltiplas fontes (papers, docs, web) com interface única
  • Gestão de conhecimento pessoal com busca híbrida e cache de ferramentas externas
  • Automação de pesquisa e síntese de informações em modelos pequenos

Veredito

Ferramenta robusta e bem arquitetada para agentes LLM que precisam de acesso uniforme a múltiplas fontes de conteúdo. Excelente para pipelines de pesquisa e conhecimento pessoal, mas requer setup PostgreSQL/pgvector e é mais orientada a construtores experientes.

README

A tradução para o português deste README ainda está na fila.

precis-mcp

check PyPI Python License

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. v8.13.0 — see CHANGELOG.md for the live story. v5.2.6 on PyPI is the last v1-line release.

README is stale beyond this banner. Things the architecture section + verb table below still capture correctly: seven-verb surface, kind= dispatch, pgvector hybrid search, content kinds vs tool kinds. Things you should treat the ref-kinds list as a sample of, not a catalogue:

  • The todo tree (Slices 1–5). kind='todo' is now a hierarchical task graph with parent_id, level gradient (strategic|tactical|recurring|subtask), PRIO column on refs, meta.auto_check wait-for-condition leaves, meta.schedule recurring spawn (Watches umbrella), and review tiers (nursery SQL-only hourly, structural 6h opus, deep_review weekly opus).
  • kind='job' as child of kind='todo'. Slice 5: every new job requires parent_id pointing at a todo. The dispatch worker is the canonical path from meta.executor on a todo to a queued job.
  • Worker consolidation. Two long-running worker daemons (precis worker --profile=system everywhere, --profile=agent on gateway) handle every pass between them; per-pass LaunchDaemons are retired.

The skill catalogue under src/precis/data/skills/precis-*-help.md is authoritative for the LLM-facing surface. Start at precis-toolpath-help ("I want to X — what do I call?") and precis-overview (the kinds + skill index).

What it does

One tool surface — seven verbs discriminated by a single kind= argument — over three categories of content:

  • Ref kinds (content addressed by slug or integer id): paper, skill, oracle, conv, markdown, plaintext, python, todo, memory, gripe, flashcard, citation (verified claim → source quote).
  • Tool kinds (stateless or cache-backed; pass q= or id=, get text back): calc, math (Wolfram), youtube, web (fetch + search + bookmark), websearch / perplexity-reasoning / perplexity-research (Perplexity Sonar tiers), patent (EPO OPS).
  • Discovery kind: 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). Run get(kind='skill', id='precis-help') against a live server for the live enumeration of kinds currently wired (it's a synthesised skill that introspects the registry); pair with get(kind='skill', id='precis-overview') for the design-rationale tour.

Seven verbs

VerbUse when
getYou know the name (slug, id, file path) — or you're calling a tool.
searchYou're looking for content by topic or phrase. Hybrid lexical (tsvector) + semantic (pgvector) with RRF fusion.
putCreate a new ref. Optionally tag and link on creation.
editRewrite a region of a file-kind ref by content anchors (find-replace, append, insert, replace).
deleteSoft-delete a numeric ref, or delete a region from a file kind by selector.
tagAdd and/or remove tags. Three namespaces: closed (STATUS:done), flag (pinned), open (topic-foo).
linkAdd 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):

ExtraEnablesHeavy?
paperpaper kind (sentence-transformers bge-m3 + acatome-extract)yes (~2 GB model on first load)
calccalc kind (sympy)no
externalmath (Wolfram), youtube, web, Perplexity triono
patentpatent kind (EPO Open Patent Services)no
webprecis web browser UI (FastAPI + Jinja + HTMX)no
docx(queued — not yet wired)—
tex(queued — not yet wired)—
plot(queued — not yet wired)—
allAll of the above.yes

A bare pip install precis-mcp gives you the state kinds (todo, memory, gripe, flashcard, conv, oracle, skill, random) and the markdown / plaintext / python file kinds. 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

VarPurpose
PRECIS_DATABASE_URLPostgres DSN (required for all ref kinds).
PRECIS_EMBEDDER"mock" (dev/tests), "bge-m3" (in-process), or "remote" (HTTP client to precis serve-embeddings).
PRECIS_EMBEDDER_URLRequired for remote: ordered, comma-separated base URL(s), e.g. http://127.0.0.1:8181. First healthy endpoint wins; rest are fallback.
PRECIS_ROOTSingle 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_ROOTSalias:/path,alias2:/path2 — exposed Python repos.
PRECIS_PYTHON_ALLOW_EXEC=1Gate for python runtrace (spawns subprocess).
EPO_OPS_CLIENT_KEY + _SECRET + PRECIS_PATENT_RAW_ROOTEnables patent kind.
WOLFRAM_APP_IDEnables math kind.
PERPLEXITY_API_KEYEnables websearch / perplexity-reasoning / perplexity-research.
PRECIS_CORPUS_DIRCorpus 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_LEVELDEBUG / INFO / WARNING / ERROR.

Design highlights

  • Seven verbs, one kind=. The whole surface is get/search/put/edit/delete/tag/link. No per-kind bespoke tools. See docs/user-facing/seven-verb-surface-migration.md.
  • 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. See docs/user-facing/edit-protocol-spec.md.
  • Hybrid search. Lexical tsvector + semantic pgvector (bge-m3) with Reciprocal Rank Fusion. Block-level; paper chunks, markdown paragraphs, Perplexity answers, web pages all searchable.
  • Persistent discovery layer. Papers get pre-computed per-segment matryoshka-ordered keywords (distinctiveness-penalty scored against sibling segments) and per-sentence bge-m3 embeddings. The TOC view serves from ref_segments directly — no per-request DP/KeyBERT recompute. Search hits carry indented excerpt @ ~N: "..." sub-lines, picked by pgvector cosine rerank against the query embedding, so result rows are actionable for triage without a second fetch. The citation kind closes the loop: an agent's writing-thread workflow can persist verified claim → source quote records (see precis-citation-help).
  • Progressive disclosure. Seven verbs and a kind= argument is the whole visible surface. Behind it sits a fan-out of ~25 per-kind help skills, dozens of read views, an anchored edit protocol, args-dict view payloads, and a tag/link vocabulary — none of which the agent has to know up front. Every response can emit a next= breadcrumb, every error names the skill that explains it, and get(kind='skill', id='precis-<kind>-help') unfolds the manual for whichever capability the agent just bumped into. Think exploding pocket knife: the tool grows blades as you reach for them, instead of advertising 20 unfamiliar buttons in tools/list. (UX literature calls this pattern progressive disclosure.)
  • HintBus. Any layer can emit deduplicated, novelty-decayed tips that are rendered after the verb's main output. Keeps slim models from drowning in self-inflicted reminders.
  • Slim exception surface. BadInput / NotFound / Gone / Unsupported / Upstream / RateLimited / Internal, each carrying a single copy-pasteable next= "breaking hint".
  • psycopg 3 sync, raw SQL. No SQLAlchemy, no Alembic, no async below FastMCP — stdio's serial workload doesn't buy anything from async.
  • In-tree handlers, entry-point plugins. Core kinds are hand-ordered in precis.dispatch.boot(). Third-party kinds can register themselves via the precis.handlers entry-point group without forking — see docs/user-facing/plugin-authoring.md.

Extending

Write a plugin handler in 3 steps — see the one-pager at docs/user-facing/plugin-authoring.md and the canonical tiny example in src/precis/handlers/calc.py.

# your plugin's pyproject.toml
[project]
dependencies = ["precis-mcp>=8.0.0"]

[project.entry-points."precis.handlers"]
wikipedia = "precis_wikipedia:WikipediaHandler"

Plugin failures are logged and skipped — one bad plugin cannot brick the server.

CLI

precis serve                       # Start the MCP stdio server.
precis web [--host H --port P]      # Browser UI: Tasks / Papers / Console /
                                   #   Conversations / Status tabs (needs the
                                   #   [web] extra; binds 127.0.0.1:9100, no
                                   #   auth — reach it over Tailscale). Papers
                                   #   carry DOI/arXiv verify links; PDFs serve
                                   #   from PRECIS_CORPUS_DIR (multi-root);
                                   #   conversations render as a transcript.
precis serve-embeddings            # Run the HTTP embedding service (the
                                   #   server side of PRECIS_EMBEDDER=remote;
                                   #   /healthz /readyz /model /embed /metrics).
precis worker                      # Drive the derived-artifact queue.
precis migrate                     # Run pending SQL migrations.
precis jobs ingest [root]          # Pre-warm .md / .txt / .tex under PRECIS_ROOT
                                   #   (mtime-gated; compose into launchers:
                                   #    `precis jobs ingest && precis serve`).
precis jobs ingest-bundle[s] ...   # Ingest .acatome paper bundles.
precis jobs ingest-oracles ...     # Seed the oracle kind from YAML wisdom files.
precis jobs dedupe-papers          # Collapse duplicate paper refs.
precis jobs import-perplexity ...  # Bulk-import Perplexity web-UI answers.
precis jobs watch-patents / run-patent-watches / sweep-patent-fulltext
                                   # Saved CQL patent watches (patent kind).

Run any subcommand with --help for detailed options.

Utility scripts

The scripts/ dir holds workspace-side utilities that run against a precis store but live outside the published CLI surface. See scripts/README.md for full coverage; the high-traffic ones:

  • paper-monitor-ingest-dir — drop-and-go PDF ingest watcher.
  • perplexity-monitor-ingest-dir — bulk-import Perplexity markdown exports.
  • find-citing-papers — sweep S2 for new papers citing the precis corpus, with bge-m3 cosine rerank and several noise- reduction filters; reports land in paper-ingest/.
  • enrich-paper-identifiers / retrofit-acatome-external-ids — backfill DOI / arXiv ids on legacy refs.

Roadmap

  • docx, tex, book, rmk file handlers (Phase 6b/c).
  • web bookmark mode + Wayback enrichment (gripe:3681 phase 2 + 4 — see OPEN-ITEMS.md).
  • voice kind — STT/TTS bound to transcript refs (see docs/user-facing/voice-kind-spec.md).
  • SDK extraction (precis-core) once the plugin API has settled.

Documentation

Contributing

The repo lives at retospect/precis-mcp. Issues and PRs welcome. Development workflow:

uv venv && source .venv/bin/activate
uv pip install -e '.[all]' --group dev
pytest -q
ruff check . && ruff format --check .
mypy src tests

License

GPL-3.0-or-later. See the full text at gnu.org/licenses/gpl-3.0.html.

Ver o original no GitHub

Bom para

Relacionados