rtfm-mcp 0.8.0__tar.gz

rtfm_mcp-0.8.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.db
+.venv/
+dist/
+build/
+# never commit a real corpus home if RTFM_HOME is pointed into the tree
+/.rtfm/
+# dev process scaffolding (implementation plans, specs) — not published
+docs/superpowers/

rtfm_mcp-0.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Canlin Zhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rtfm_mcp-0.8.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: rtfm-mcp
+Version: 0.8.0
+Summary: Read The Full Manual — local document-corpus search MCP server.
+Project-URL: Homepage, https://github.com/canlin-zhang/rtfm
+Project-URL: Repository, https://github.com/canlin-zhang/rtfm
+Project-URL: Issues, https://github.com/canlin-zhang/rtfm/issues
+Author: Canlin Zhang
+License-Expression: MIT
+License-File: LICENSE
+Keywords: documentation,mcp,pdf,search
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]<2,>=1.28.1
+Requires-Dist: pymupdf
+Requires-Dist: pypdf
+Description-Content-Type: text/markdown
+
+# rtfm
+
+> **rtfm** — Read the ~~F-~~ **Full** Manual.
+
+A local MCP server and Claude Code plugin that makes large, can't-read-by-hand technical
+documentation searchable — PDF spec sets, documentation repositories (and, later, public
+doc sites) — and answers questions strictly from that material, with grounded citations.
+The server is also published as the `rtfm-mcp` Python package.
+
+The eternal advice "read the manual" falls apart when the manual is a 400-page protocol
+spec or a vendor doc-set no human can hold in their head. `rtfm` ingests the **full** manual
+so the answer is one cited query away.
+
+## Limitations
+
+`rtfm` indexes the **extractable text** a document already carries. It does not OCR images
+and does not execute JavaScript, so image-only/scanned PDFs and image-only or JS-rendered
+web pages are out of scope — they index as empty. (See [ADR 0005](https://github.com/canlin-zhang/rtfm/blob/main/docs/adr/0005-text-extraction-only-no-ocr.md).)
+
+## Install
+
+### Claude Code
+
+```bash
+# in Claude Code:
+/plugin marketplace add canlin-zhang/rtfm
+/plugin install rtfm
+```
+
+### Any MCP client (PyPI)
+
+The server is also published as `rtfm-mcp`:
+
+```bash
+uvx --from rtfm-mcp rtfm-server      # or: pipx install rtfm-mcp && rtfm-server
+```
+
+Point the client's MCP configuration at that command:
+
+```json
+{
+  "mcpServers": {
+    "rtfm": {
+      "command": "uvx",
+      "args": ["--from", "rtfm-mcp", "rtfm-server"]
+    }
+  }
+}
+```
+
+**Prerequisites:** `python3` on PATH is the only hard requirement for the plugin. It
+uses `uv` when available and otherwise builds a private venv under `~/.rtfm/venv` on
+first run. The PyPI path needs `uv` (for `uvx`) or `pipx`.
+*Optional:* install `poppler-utils` (`pdftotext`) for best-quality PDF extraction.
+
+## Two ways to use it
+
+**Quick-and-dirty (the `default` drop-dir).** Drop PDFs or Markdown/text into `~/.rtfm/default`
+and just `search` — the default dir re-indexes itself on search, so dropped files show up with
+no extra step. Keep it small; it's a scratch space.
+
+**Organized corpus (pointed-to folders).** For a large, structured doc set (e.g. a vendor's
+documentation tree), add a `dir` source in `~/.rtfm/manifest.toml` pointing at the folder, then
+build it once:
+
+```
+reindex("vendor-docs")
+```
+
+Searches are instant afterward. `dir` sources auto-reindex inline when the delta is small
+(`RTFM_AUTO_REINDEX_MAX`, default 10); a larger delta returns a warning telling you to run
+`reindex` once. `git_repo` sources are the exception to the budget: a stale or never-indexed
+source always auto-reindexes inline on search — no budget gate, warns loudly on failure —
+including the initial clone for managed sources, so the first search over a fresh corpus can
+take a while. Byte-identical files that repeat across version subfolders are extracted once;
+`find_duplicates` lists every path a given content lives at.
+
+## Use
+
+Drop PDFs / `.md` / `.mdx` / `.rst` / `.txt` into `~/.rtfm/default/`, then ask Claude to search them, or
+add more sources by editing `~/.rtfm/manifest.toml` (see `manifest.example.toml`).
+
+Or invoke the bundled **`read-the-manual`** skill (`/read-the-manual`) to have a question
+answered strictly from the corpus — verbatim quotes with page/line citations, no
+model-knowledge fallback.
+
+## Status
+
+Early but working. Today rtfm gives you zero-config search over a default drop-folder: PDF,
+Markdown, reStructuredText, and text files are indexed into one content-addressed full-text
+index with page/line citations, exposed through the `search` / `read` / `reindex` /
+`find_duplicates` / `list_sources` / `health_check` tools and the `read-the-manual` skill, with
+a uv-or-venv launcher and Claude Code plugin packaging. HTML with anchor citations, git-backed
+repo sources with auto-refresh, file-curation tools, and OCR are planned — see the
+[roadmap](https://github.com/canlin-zhang/rtfm/blob/main/docs/ROADMAP.md).
+
+Architecture decisions live in [docs/adr/](https://github.com/canlin-zhang/rtfm/tree/main/docs/adr/); domain language in
+[CONTEXT.md](https://github.com/canlin-zhang/rtfm/blob/main/CONTEXT.md).
+
+## License
+
+MIT © Canlin Zhang

rtfm_mcp-0.8.0/README.md

@@ -0,0 +1,102 @@
+# rtfm
+
+> **rtfm** — Read the ~~F-~~ **Full** Manual.
+
+A local MCP server and Claude Code plugin that makes large, can't-read-by-hand technical
+documentation searchable — PDF spec sets, documentation repositories (and, later, public
+doc sites) — and answers questions strictly from that material, with grounded citations.
+The server is also published as the `rtfm-mcp` Python package.
+
+The eternal advice "read the manual" falls apart when the manual is a 400-page protocol
+spec or a vendor doc-set no human can hold in their head. `rtfm` ingests the **full** manual
+so the answer is one cited query away.
+
+## Limitations
+
+`rtfm` indexes the **extractable text** a document already carries. It does not OCR images
+and does not execute JavaScript, so image-only/scanned PDFs and image-only or JS-rendered
+web pages are out of scope — they index as empty. (See [ADR 0005](https://github.com/canlin-zhang/rtfm/blob/main/docs/adr/0005-text-extraction-only-no-ocr.md).)
+
+## Install
+
+### Claude Code
+
+```bash
+# in Claude Code:
+/plugin marketplace add canlin-zhang/rtfm
+/plugin install rtfm
+```
+
+### Any MCP client (PyPI)
+
+The server is also published as `rtfm-mcp`:
+
+```bash
+uvx --from rtfm-mcp rtfm-server      # or: pipx install rtfm-mcp && rtfm-server
+```
+
+Point the client's MCP configuration at that command:
+
+```json
+{
+  "mcpServers": {
+    "rtfm": {
+      "command": "uvx",
+      "args": ["--from", "rtfm-mcp", "rtfm-server"]
+    }
+  }
+}
+```
+
+**Prerequisites:** `python3` on PATH is the only hard requirement for the plugin. It
+uses `uv` when available and otherwise builds a private venv under `~/.rtfm/venv` on
+first run. The PyPI path needs `uv` (for `uvx`) or `pipx`.
+*Optional:* install `poppler-utils` (`pdftotext`) for best-quality PDF extraction.
+
+## Two ways to use it
+
+**Quick-and-dirty (the `default` drop-dir).** Drop PDFs or Markdown/text into `~/.rtfm/default`
+and just `search` — the default dir re-indexes itself on search, so dropped files show up with
+no extra step. Keep it small; it's a scratch space.
+
+**Organized corpus (pointed-to folders).** For a large, structured doc set (e.g. a vendor's
+documentation tree), add a `dir` source in `~/.rtfm/manifest.toml` pointing at the folder, then
+build it once:
+
+```
+reindex("vendor-docs")
+```
+
+Searches are instant afterward. `dir` sources auto-reindex inline when the delta is small
+(`RTFM_AUTO_REINDEX_MAX`, default 10); a larger delta returns a warning telling you to run
+`reindex` once. `git_repo` sources are the exception to the budget: a stale or never-indexed
+source always auto-reindexes inline on search — no budget gate, warns loudly on failure —
+including the initial clone for managed sources, so the first search over a fresh corpus can
+take a while. Byte-identical files that repeat across version subfolders are extracted once;
+`find_duplicates` lists every path a given content lives at.
+
+## Use
+
+Drop PDFs / `.md` / `.mdx` / `.rst` / `.txt` into `~/.rtfm/default/`, then ask Claude to search them, or
+add more sources by editing `~/.rtfm/manifest.toml` (see `manifest.example.toml`).
+
+Or invoke the bundled **`read-the-manual`** skill (`/read-the-manual`) to have a question
+answered strictly from the corpus — verbatim quotes with page/line citations, no
+model-knowledge fallback.
+
+## Status
+
+Early but working. Today rtfm gives you zero-config search over a default drop-folder: PDF,
+Markdown, reStructuredText, and text files are indexed into one content-addressed full-text
+index with page/line citations, exposed through the `search` / `read` / `reindex` /
+`find_duplicates` / `list_sources` / `health_check` tools and the `read-the-manual` skill, with
+a uv-or-venv launcher and Claude Code plugin packaging. HTML with anchor citations, git-backed
+repo sources with auto-refresh, file-curation tools, and OCR are planned — see the
+[roadmap](https://github.com/canlin-zhang/rtfm/blob/main/docs/ROADMAP.md).
+
+Architecture decisions live in [docs/adr/](https://github.com/canlin-zhang/rtfm/tree/main/docs/adr/); domain language in
+[CONTEXT.md](https://github.com/canlin-zhang/rtfm/blob/main/CONTEXT.md).
+
+## License
+
+MIT © Canlin Zhang

rtfm_mcp-0.8.0/manifest.example.toml

@@ -0,0 +1,86 @@
+# rtfm source manifest. Copy to ~/.rtfm/manifest.toml and edit.
+# Each [[source]] is one place rtfm indexes, in place.
+#
+# search keeps sources current automatically: when a dir source has only a few new/changed
+# files (RTFM_AUTO_REINDEX_MAX, default 10) it is reindexed inline, so dropping or editing a
+# handful of files just works. A larger batch is NOT auto-indexed — that would block the query
+# on extraction — so search warns and you run `reindex("<name>")` once. git_repo sources are
+# different: a stale or never-indexed git_repo auto-reindexes inline on search (no budget
+# gate, warns loudly on failure), including the initial clone for managed sources. Two modes
+# follow from this:
+#
+#   1. The "default" drop-dir — quick-and-dirty scratch. Drop a few files in, search finds them.
+#      Created for you automatically; keep it small.
+#   2. Pointed-to folders — an organized corpus you manage. Run `reindex("<name>")` once after
+#      first adding a large set; thereafter small changes auto-reindex on search. Read-only by default.
+#
+# Every source declares its scope. Two keys are optional and one is required.
+#
+#   paths          Directory prefixes to index. Unset means the whole tree. A "!" entry
+#                  excludes a prefix, and exclusion wins:
+#                      paths = ["docs", "!docs/versions"]
+#                  Every prefix is relative to the source root; a leading "/" is optional
+#                  and ignored (the same convention .gitignore uses for an anchored path).
+#                  Prefixes only — no globs. A literal "docs/**" directory does not exist,
+#                  so a glob character (*, ?, [) is refused at load time, loudly, rather
+#                  than silently indexing nothing while looking correct.
+#
+#   ext_allowlist  Index ONLY these file types.        ) exactly one of these
+#   ext_blocklist  Index everything EXCEPT these,      ) two is required
+#                  on top of rtfm's own list of known binary and asset types.
+#
+# Declaring both is refused; declaring neither is refused. rtfm does not guess what to
+# index, because a guess is how a hidden default comes back through a side door.
+#
+# Which to pick: an allowlist decides what you GET, so growing it later means every source
+# pinned to the old list silently misses the new type. A blocklist decides what you DON'T
+# get, and everything on it is something nobody wants indexed, so growing it later removes
+# garbage and never content. Prefer a blocklist unless you know exactly what you want.
+
+[[source]]
+name          = "default"            # the zero-config drop-dir; the only mutable source by default
+type          = "dir"
+path          = "~/.rtfm/default"
+mutable       = true
+ext_blocklist = []          # index everything except rtfm's known binary and asset types
+
+# Example: point at a large, organized doc set. Run reindex("vendor-docs") once after adding it;
+# searches are instant thereafter. Byte-identical files across version subfolders are stored once.
+# [[source]]
+# name          = "vendor-docs"
+# type          = "dir"
+# path          = "/path/to/vendor/Documentation"
+# mutable       = false
+# ext_blocklist = []
+
+# Example: a git-tracked doc repo — linked mode (user provides the clone). Read-only:
+# rtfm verifies the remote URL and a clean tree, then indexes the checkout as-is —
+# it never fetches or resets the user's clone.
+# [[source]]
+# name          = "specs"
+# type          = "git_repo"
+# url           = "https://example.com/org/specs.git"
+# ref           = "main"
+# path          = "/path/to/specs"
+# ext_allowlist = [".md"]   # exactly one of ext_allowlist/ext_blocklist is required
+
+# Example: a git-tracked doc repo — managed mode (rtfm clones to ~/.rtfm/repos/<name>/
+# and fetches + resets on every reindex).
+# [[source]]
+# name          = "docs-managed"
+# type          = "git_repo"
+# url           = "https://example.com/org/specs.git"
+# ref           = "v2.1-stable"
+# ext_allowlist = [".md"]
+
+# Example: a rules repo where the documentation lives in Starlark doc= strings, not
+# in a docs/ folder rtfm could scope with `paths` alone (issue #24). ext_allowlist picks
+# out the file types that actually carry prose, and `paths` narrows further, skipping
+# the repo's test fixtures.
+# [[source]]
+# name          = "rules_cc"
+# type          = "git_repo"
+# url           = "https://github.com/bazelbuild/rules_cc.git"
+# ref           = "main"
+# ext_allowlist = [".bzl", ".md"]
+# paths         = ["cc", "!tests"]

rtfm_mcp-0.8.0/pyproject.toml

@@ -0,0 +1,63 @@
+# Package manifest for the published core (`rtfm-mcp` on PyPI). The runtime
+# dependency source of truth remains the PEP-723 `# /// script` block in
+# rtfm_server.py (ADR 0009); [project].dependencies mirrors it, and
+# scripts/check_version_consistency.py fails on drift. The dev group and tool
+# config below exist only for working on the repo.
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rtfm-mcp"
+version = "0.8.0"
+description = "Read The Full Manual — local document-corpus search MCP server."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Canlin Zhang" }]
+keywords = ["mcp", "documentation", "search", "pdf"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+dependencies = [
+    "mcp[cli]>=1.28.1,<2",
+    "pymupdf",
+    "pypdf",
+]
+
+[project.urls]
+Homepage = "https://github.com/canlin-zhang/rtfm"
+Repository = "https://github.com/canlin-zhang/rtfm"
+Issues = "https://github.com/canlin-zhang/rtfm/issues"
+
+[project.scripts]
+rtfm-server = "rtfm_server:main"
+
+[tool.hatch.build.targets.wheel]
+# The server is deliberately one importable module, not a package (AGENTS.md).
+only-include = ["rtfm_server.py"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "rtfm_server.py",
+    "manifest.example.toml",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[dependency-groups]
+dev = ["pytest"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]   # pycodestyle, pyflakes, isort, pyupgrade, bugbear