docshelf-mcp turns a folder of PDFs and Markdown files into a structured, AI-friendly document collection with index-based navigation and on-demand section fetching via GitHub raw URLs.
Initialize a document shelf (docshelf_init_shelf): Bootstrap a new shelf directory with the required layout (docs/, INDEX.md, .docshelf.json, .gitignore), pre-create category folders, and configure a GitHub remote for raw URL generation. Safe to re-run on an existing shelf to update metadata.
Add a document (docshelf_add_document): Add a PDF or Markdown file to a category, automatically converting PDFs to Markdown (via pymupdf4llm or marker-pdf), splitting large documents by headings into per-section files, and regenerating INDEX.md.
Rebuild the index (docshelf_rebuild_index): Regenerate INDEX.md from the current on-disk shelf state — useful after manual edits to documents or shelf metadata.
Search the shelf (docshelf_search): Plain-text, case-insensitive search across all Markdown files, returning matched file paths, snippets, and raw GitHub URLs for direct fetching.
List documents (docshelf_list_documents): List all documents grouped by category, with an optional filter to show only a specific category.
Standalone PDF conversion (docshelf_convert_pdf): Convert a PDF to Markdown without adding it to any shelf, optionally splitting the result by headings.
Enables hosting a docshelf repository on GitHub, with INDEX.md containing raw.githubusercontent.com URLs for AI agents to fetch individual document sections on demand.
Put your manuals on a shelf, hand the AI the index.
📖 Docs & landing page: https://ignatenkofi.github.io/docshelf-mcp/
_ _ _ __
__| | ___ ___ ___| |__ ___| |/ _|
/ _` |/ _ \ / __/ __| '_ \ / _ \ | |_
| (_| | (_) | (__\__ \ | | | __/ | _|
\__,_|\___/ \___|___/_| |_|\___|_|_|
MCP server for AI-friendly doc shelvesAn MCP server that turns a folder of PDFs and Markdown into a chat-project-friendly document collection: AI agents see a single INDEX.md and pull individual sections by raw GitHub URL on demand — instead of choking on a 4 MB datasheet.
You have 30 hardware manuals, or 200 cooking recipes, or a stack of research PDFs.
You want Claude / ChatGPT / whatever to be able to answer questions across them — but:
❌ You can't dump 80 MB of PDFs into a chat project. It won't fit, and you'd burn the context window even if it did.
❌ You can manually copy-paste the relevant pages, but only after you remember which manual mentioned the thing you need.
❌ Long files mean retrieval is wasteful — the model loads the whole RouterOS guide just to answer a question about VLANs.
docshelf-mcp solves it like this:
You drop a PDF onto the shelf.
The shelf converts it to Markdown, splits big files chapter-by-chapter, and regenerates a navigation INDEX.md.
You commit and push to a public GitHub repo.
Add only INDEX.md to your Claude project. When the model needs a section, it fetches it via raw.githubusercontent.com.
Result: a 5 KB index pointing at a 50 MB collection. The model reads exactly the chapter it needs.
Related MCP server: Obsidian MCP Server
From PyPI (once the first tagged release is published):
# uv (recommended)
uv pip install docshelf-mcp
# or plain pip
pip install docshelf-mcpOr straight from main (always-latest, no PyPI required):
pip install "git+https://github.com/ignatenkofi/docshelf-mcp"That gives you Markdown shelves. Input formats beyond Markdown are extras — pick the ones you ingest:
pip install "docshelf-mcp[pdf]" # PDF via pymupdf4llm (the default engine)
pip install "docshelf-mcp[formats]" # PDF + DOCX + HTML + EPUB; or [docx] / [html] / [epub]The pdf extra pulls the PyMuPDF chain (~260 MB installed); a consumer that
only reads and writes Markdown does not need it, which is why it is not core.
Optional high-quality PDF engine (pulls ~2 GB of PyTorch — only if you need it):
pip install "docshelf-mcp[high-quality]"Drop this into the Custom Instructions of any Claude project that consumes
a docshelf-style INDEX.md:
This project uses the docshelf pattern.
INDEX.mdis the entry point. When answering: read INDEX → fetch ONLY the needed section file via its GitHub raw URL (use WebFetch / fetch / curl). Don't load full source files into context. For large manuals split into chapters, follow INDEX → chapter SUBINDEX → section file.
Medium (~150 words) and full (~400 words) versions, plus how-to snippets for
Claude Code, Claude Desktop, and the Anthropic API, live in
docs/PROJECT_PROMPT.md.
from docshelf_mcp import Shelf
shelf = Shelf("~/Documents/my-homelab-docs").init(
name="My HomeLab Docs",
remote="https://github.com/me/my-homelab-docs",
default_categories=["routers", "switches", "psu", "motherboards"],
)
shelf.add_document(
"~/Downloads/MIKROTIK_RouterOS.pdf",
category="routers",
title="Mikrotik RouterOS — full manual",
description="Official RouterOS reference, split by chapter.",
)
# → docs/routers/mikrotik-routeros-full-manual.md + docs/routers/.../001-..md, 002-..md, ...
# → INDEX.md is regenerated automatically.Then in the shelf directory: git add . && git commit -m "docs: add RouterOS" && git push.
In your Claude project, attach only INDEX.md. Done.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):
{
"mcpServers": {
"docshelf": {
"command": "docshelf-mcp",
"env": {
"DOCSHELF_ROOT": "/Users/me/Documents/my-homelab-docs"
}
}
}
}Restart Claude Desktop. You now have eleven new tools available:
Tool | What it does |
| Bootstrap a new shelf directory. |
| Add a file (MD/PDF/DOCX/HTML/EPUB). Converts, splits, re-indexes. |
| Add every supported file (MD/PDF/DOCX/HTML/EPUB) in a folder in one call. Re-indexes once. |
| Read a document/section's content over MCP (works on private shelves). |
| Remove a document, its sections, and metadata. Re-indexes. |
| Retitle / recategorize a document (moves file, sections, meta) — no re-conversion. |
| Regenerate |
| Check shelf integrity; optionally auto-fix safe drift. |
| Plain-text search across the shelf, with raw URLs. |
| List documents by category. |
| Standalone PDF → Markdown (no shelf). |
The shelf files are also exposed as read-only MCP resources, so a client can browse and attach them natively — see MCP Resources below.
claude mcp add docshelf -- docshelf-mcp
# Optional: pin a default shelf for this server
printf 'Path to your docshelf shelf: '; read -r shelf
shelf=${shelf/#\~/$HOME} # read does not expand a typed ~
shelf=$(cd "$shelf" && pwd) || exit 1 # absolute, and fails loudly if absent
claude mcp add docshelf --env DOCSHELF_ROOT="$shelf" -- docshelf-mcp# Sanity check — should print the server version then wait on stdin
docshelf-mcpAlongside the tools, every shelf file is exposed as a read-only MCP resource, so an MCP client (Claude Desktop, Claude Code, …) can browse and attach shelf content natively — no tool call required.
Scheme: docshelf:///<relative-path>, e.g. docshelf:///INDEX.md or docshelf:///docs/routers/mikrotik/003-firewall.md.
What's exposed: INDEX.md plus every document and every split section under docs/ — one resource each. A split document exposes both its whole-file parent and its individual section files.
Size cap: a resource read is capped at 1 MB (1,000,000 bytes). A larger file is truncated at a UTF-8 character boundary and ends with a notice pointing at the docshelf_read_document tool, which pages the rest.
Freshness: content is read from disk on every access, and the resource set is re-synced when the server starts and after each mutating tool call (add_document, add_directory, remove_document, rename_document, rebuild_index, init_shelf) — so newly added files appear and removed ones drop out. Reads are confined to the shelf root.
Resources are only registered for an initialized shelf (one that has a .docshelf.json); a non-shelf DOCSHELF_ROOT simply exposes none.
my-shelf/
├── .docshelf.json ← shelf metadata: name, remote, category order
├── INDEX.md ← auto-generated navigation (your chat-project file)
├── .gitignore
└── docs/
├── routers/
│ ├── .meta.json ← per-document title/description overrides
│ ├── mikrotik-routeros.md (full document, lightly cleaned)
│ └── mikrotik-routeros/ (auto-split sections)
│ ├── SUBINDEX.md (per-document navigation page)
│ ├── 001-overview.md
│ ├── 002-bridging.md
│ └── 003-firewall.md
└── switches/
└── cudy-gs1010pe.mdEverything in docs/ is committed; everything is fetchable via raw URL once you push to GitHub.
A document is split when both conditions hold:
UTF-8 size > 50 KB (configurable via .docshelf.json:split_threshold_bytes).
The document has at least two ## (H2) headings.
The splitter:
Cleans PDF-extraction noise (collapses runaway blank lines, demotes CLI dumps mistaken for H1s).
Slices on H2 boundaries.
Names files NNN-<slug>.md so they sort naturally and survive title changes.
Wipes the previous split directory before regenerating — fully idempotent.
Writes a SUBINDEX.md navigation page into the split directory (title,
description, per-section links) — regenerated on every rebuild_index.
In INDEX.md, split documents with up to 10 sections list every section
inline; bigger splits get a single link to their SUBINDEX.md so the index
stays small. Control this via .docshelf.json:
"index_style": "auto" | "inline" | "subindex" and
"subindex_threshold_sections": 10.
If you want to keep a document whole, pass split=False.
See the examples/ directory for three concrete use cases:
examples/homelab/ — original use case, hardware manuals for a home lab.
examples/recipes/ — a cookbook with one recipe per file.
examples/research-papers/ — academic PDFs with abstracts in .meta.json.
Each example shows the directory layout and the INDEX.md you'd end up with.
The default engine (pymupdf4llm, installed by the pdf extra) is fast and good enough for ~95% of technical documents. For papers with complex tables, math, or scanned content, install the marker-pdf backend:
pip install "docshelf-mcp[high-quality]"Then pass quality="high":
shelf.add_document("paper.pdf", category="research", title="...", quality="high")⚠️ marker-pdf pulls in PyTorch (~2 GB) and is significantly slower (10–60 s per document on CPU). The library import is deferred — if you don't use quality="high", the dependency is never loaded.
Why GitHub raw URLs and not embeddings / RAG? Because it's dead simple, costs nothing to host, and the AI is already good at chasing links. You can layer embedding search on top later if you want — the on-disk shape is a normal git repo.
Does this work with private repos?
Partly. The raw-URL trick needs a public repo — raw.githubusercontent.com won't serve private ones without auth. But docshelf_search and docshelf_read_document both work over MCP on private (or purely local, non-git) shelves: the model searches, then reads the exact section's content directly from the server, no raw URL required. You only lose the ability to hand a bare INDEX.md to a chat project and have it fetch by URL — with the MCP server attached, the full flow works either way. Make the doc repo public if you want the URL-fetch path too.
Do I have to use GitHub?
No. Set provider in .docshelf.json (or at init_shelf): github (default), gitlab, gitea, custom, or none. The github provider also covers GitHub Enterprise Server: a self-hosted github.<company>.com remote gets the GHES raw form (https://<host>/<owner>/<repo>/raw/<branch>/<path>) automatically. custom takes a url_template with {owner}, {repo}, {branch}, {path} placeholders, so you can point at S3, Cloudflare R2, GitLab/Gitea raw, a GHES deployment on a fully custom domain, or any static host — the generated URLs are correct everywhere, no post-processing. none renders relative links in INDEX.md, which stay navigable offline / in a local checkout.
Does it edit the source PDFs?
No. PDFs are converted on add_document and the source is left in place. The shelf only writes inside its own directory.
What about non-English documents?
Slugify is Unicode-aware (NFKD-normalized, with \w under re.UNICODE). Cyrillic / CJK titles slug down to ASCII-ish forms; the body Markdown is preserved as-is.
Can I use it without MCP?
Yes — from docshelf_mcp import Shelf and use the class directly. See docs/USAGE.md.
Public GitHub only for the raw-URL trick (or whatever public static host you wire up).
Single repo per shelf. If you outgrow one repo, run multiple shelves and attach multiple INDEX.mds.
Heuristic splitting. The PDF→Markdown extract isn't always clean enough to split cleanly. For pathological cases (some 4+ MB datasheets), keep the file whole and rely on docshelf_search.
No automatic git commit. Tools regenerate INDEX.md on disk, but the caller (you, or an agent) is responsible for git add / commit / push. This is intentional — staying out of git's way keeps the tool safe to call from agents.
Measured on two real shelves (24 hardware manuals; a full novel split by chapter): answering a question the docshelf way costs ~3.7K tokens vs 1.2M to dump the collection — 99.7% fewer — and the biggest manual (RouterOS, ~1.05M tokens) doesn't even fit in a 200K context window, while a section fetch always does.
📊 Full write-up with the numbers, chart, and a reproducible benchmark:
docs/demo.md (run benchmarks/token_savings.py on your own shelf).
For a deeper dive, see docs/ARCHITECTURE.md — module layout, data flow, design rationale.
memshelf-mcp — the sibling project: the same index-and-fetch pattern applied to an AI agent's own working memory. Conversation episodes get offloaded to a private shelf with LLM-written digests; the agent keeps only INDEX.md in context and recalls sections on demand. Born as RFC-0001 in this repo; uses docshelf as its storage/index layer.
Bug reports and PRs welcome. To set up a dev env:
git clone https://github.com/ignatenkofi/docshelf-mcp
cd docshelf-mcp
uv pip install -e ".[dev]"
ruff check src tests
pytest -vMIT — see LICENSE.
docshelf-mcp started life as a 350-line Python script (homelab-encyclopedia.py) that managed a single homelab manuals repo. The split / index / clean logic is the same code, generalised to work for any category-organised document collection.
Add every matching file in a directory, rebuilding INDEX.md once.
Scans source_dir (non-recursively) for patterns — every supported
input type by default (Markdown, PDF, DOCX, HTML, EPUB) — adds each under
category with a title derived from its filename, and regenerates
INDEX.md a single time. A corrupt or unreadable file is reported in
failed without aborting the batch.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds key behaviors: non-recursive scan, single INDEX rebuild, default patterns, error reporting without aborting. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a bullet-like list. It is front-loaded with the main purpose, and every sentence contributes necessary context. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers scanning scope, default patterns, INDEX behavior, error handling, and parameter defaults. An output schema exists, so return values are not needed. The description fully contextualizes usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for each parameter (e.g., split, quality, patterns). The description adds minimal extra meaning, like default patterns and non-recursive scanning, but mostly restates what the schema covers. Baseline is 3 due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'add', the resource 'every matching file in a directory', and the side-effect 'rebuilding INDEX.md once'. It distinguishes from siblings like docshelf_add_document by focusing on a directory scan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool scans a directory non-recursively for matching patterns, which tells when to use it. It implicitly contrasts with single-file siblings, but lacks explicit when-not or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a PDF or Markdown file to the shelf and refresh INDEX.md.
.pdf is converted to Markdown (pymupdf4llm by default; pass
quality='high' to use marker-pdf).
Documents larger than 50 KB with multiple H2 headings are split into
one file per section (turn this off with split=False).
If a different title/category slugifies onto a path an existing
document already occupies, the call errors instead of overwriting it —
pass overwrite=true to replace it. Re-adding the same title updates
in place. The response reports overwritten.
The response warnings include suspicious section headings and an
empty-conversion warning when the source yields little or no text
(e.g. a scanned / image-only PDF — consider quality='high' / OCR).
INDEX.md is regenerated automatically. The caller still owns the git commit / push step.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behaviors such as PDF-to-Markdown conversion, automatic splitting of large documents, slug collision handling with overwrite flag, regeneration of INDEX.md, and warnings for suspicious sections. This goes well beyond the annotations (idempotentHint, destructiveHint) by explaining exactly what happens under various conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a lead sentence and bullet points. It is informative but somewhat lengthy; however, every sentence adds value. The information could be condensed without loss, but it is not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple parameters, conversion, splitting, collision handling), the description covers most important aspects: conversion options, splitting criteria, overwrite behavior, warnings, and INDEX.md regeneration. However, it only mentions 'PDF or Markdown file' at the start, while the input schema supports additional formats (DOCX, HTML, EPUB) – this omission could mislead users.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema's property descriptions. For example, it explains the effect of split (based on size and H2 headings), the quality options with 'fast' and 'high' alternatives, and the overwrite behavior with error vs replacement. It also clarifies the slug parameter's purpose and the file formats supported (though schema lists more).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Add a PDF or Markdown file to the shelf and refresh INDEX.md' which clearly states the action (add) and resource (shelf). It distinguishes from sibling tools like docshelf_add_directory by focusing on a single file, and from docshelf_remove_document by the operation type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides details on parameters (split, overwrite, quality) but does not explicitly guide when to use this tool versus alternatives like docshelf_add_directory or docshelf_rename_document. It implicitly states use for adding a single file, but lacks explicit exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Standalone PDF → Markdown conversion (no shelf, no INDEX update).
Use when you want the converted file but don't yet want to commit it to a shelf. Optionally splits the result by H2.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations by clarifying that this is standalone and does not update a shelf or the INDEX. It also mentions optional H2 splitting. Annotations already provide idempotent/destructive hints, so the bar is lower; the description covers the main side-effect boundary well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, purposeful sentences. The main action and exclusions are front-loaded, followed by usage guidance and the optional split behavior. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a conversion tool with a rich schema and output schema, the description is largely complete: it states purpose, scope, and when to use it. It could slightly improve by naming the sibling to use when committing to a shelf is desired, but the schema covers invocation details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The nested input schema fully documents all parameters: pdf_path, out_dir, split, and quality, including defaults, enums, and output filename behavior. The tool description adds no parameter-level detail, but the schema already carries that weight, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Standalone PDF → Markdown conversion'. It immediately scopes the tool by stating '(no shelf, no INDEX update)', which clearly distinguishes it from shelf-management siblings without needing to inspect them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use when you want the converted file but don't yet want to commit it to a shelf' gives an explicit condition for use. It implies the alternative is a shelf-committing operation, but it does not name a specific sibling tool, so the routing is clear but slightly less direct than it could be.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the shelf for drift and optionally apply the safe fixes.
Reports stale .meta.json entries, orphaned split directories, split
sections out of sync with their parent, a stale INDEX.md, duplicate
titles, and empty categories. Read-only by default; pass fix=true to
prune stale meta entries, delete orphaned split dirs, and rebuild the
index (other findings stay report-only). Findings are sorted for stable
diffing.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is read-only by default, that fix=true applies only safe fixes (prune, delete, rebuild), and that other findings remain report-only. This aligns with annotations (idempotentHint=true, destructiveHint=false) and adds valuable context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose, list of findings, and separated behavior for read-only vs fix mode. It is concise but could be slightly more compact; still efficient at about 100 words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers what the tool checks (six categories) and the fix behavior. It also mentions sorting for stable diffing, adding useful context without needing to describe return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema has 0% description coverage, the description explains the 'fix' parameter's effect and implicitly mentions 'shelf_path'. It adds meaning beyond the schema by detailing which fixes are applied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks the shelf for drift and optionally applies safe fixes, listing specific findings (stale meta, orphaned splits, etc.). It distinguishes from sibling tools like rebuild_index by covering both diagnosis and selective fixes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (read-only by default, pass fix=true to apply) but does not explicitly state when to use this tool over siblings like docshelf_rebuild_index. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bootstrap a new document shelf at shelf_path.
Creates the directory layout (docs/, INDEX.md, .docshelf.json,
.gitignore), pre-creates any default_categories, and stores the
github_remote so generated INDEX entries link to raw GitHub URLs.
Idempotent — safe to call on an existing shelf to update metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds behavioral detail: creates directory layout, pre-creates categories, stores remote URL, and notes that it never overwrites an existing manifest. This sufficiently explains its behavior beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences covering purpose, actions, and idempotency. It front-loads the key action. No extraneous information, though it could be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (initialization with multiple files and options) and the presence of an output schema (not shown but noted), the description adequately lists created artifacts and guarantees idempotency. It covers key edge cases (existing shelf, manifest non-overwrite) but omits details like permission handling or error states, which are acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already contains detailed descriptions for all properties of InitShelfInput, such as name, branch, provider, etc. The tool description adds minimal parameter context (e.g., mentions default_categories and github_remote). Given the schema coverage is stated as 0% (likely a misrepresentation), but the descriptions in the schema are thorough, the description adds some but not significant value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Bootstrap a new document shelf at `shelf_path`' with specific actions (creates directory layout, INDEX.md, .docshelf.json, .gitignore). It unambiguously distinguishes from sibling tools like docshelf_add_document by focusing on initializing the shelf itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is used to set up a shelf and is idempotent ('safe to call on an existing shelf to update metadata'). However, it does not explicitly state when not to use it or mention alternatives among siblings, though the specialized purpose makes it obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List documents grouped by category.
Pass a category to filter; omit it to list everything.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, idempotent, and non-destructive nature. The description adds the grouping-by-category behavior and the 'list everything' default. However, it does not disclose pagination, ordering, or what 'grouped' looks like in the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with no wasted words. The filter behavior is stated in a single clear sentence after the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with an output schema, the description covers the main filtering behavior. But the omission of shelf_path and lack of any note about result grouping details make the definition incomplete for an agent that needs to call it correctly in all cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description usefully explains the category parameter's behavior, which helps given low schema coverage. However, shelf_path appears in the schema with no description and is never addressed in the tool description, leaving a potentially important scoping parameter unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('documents') and adds distinctive grouping behavior ('grouped by category'). It does not explicitly differentiate itself from siblings like docshelf_search, so it stops short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: pass a category to filter, omit it to list everything. This is clear and actionable, though it does not mention alternatives or exclusions relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a document or section file from inside the shelf's docs/.
Returns the file content directly over MCP — useful for private or
purely-local shelves where the raw.githubusercontent.com fetch
trick doesn't apply. Pass a relative_path from search /
list_documents. Large files are truncated to max_bytes (default
100 KB) with truncated: true; page with the returned next_offset
(slices snap to UTF-8 character boundaries, so it may differ from
offset + max_bytes — using it avoids splitting a multibyte character)
or read the individual split sections. Paths that escape docs/ are
rejected.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false (safe read-only). The description adds crucial behavioral details: truncation via max_bytes with truncated flag, paging using next_offset (with UTF-8 boundary explanation), and rejection of paths escaping docs/. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with the core purpose, adding use-case context, then detailing parameters and behavior. It is slightly long (8 lines) but every sentence adds value. There is no wasted text, and the front-loading is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers essential aspects: purpose, when to use, parameter guidance, security (path rejection), and paging behavior. Since an output schema exists (context signal), the description does not need to detail return values. The coverage is thorough given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has descriptions for offset and max_bytes, but shelf_path lacks a description. The description adds significant value by explaining the paging mechanism, how next_offset works, and the role of max_bytes. This goes beyond the schema's information, but shelf_path remains undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read a document or section file from inside the shelf's docs/.' This is a specific verb-resource combination that uniquely identifies the tool's purpose. It is immediately distinguished from sibling tools like docshelf_add_document (write) and docshelf_remove_document (delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool: 'useful for private or purely-local shelves where the raw.githubusercontent.com fetch trick doesn't apply.' It also instructs to pass a relative_path from search/list_documents. However, it does not explicitly state when not to use this tool versus alternatives, though the use-case context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Regenerate INDEX.md from the current on-disk shelf state.
Useful after manual edits to docs/ or .docshelf.json.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true and destructiveHint=false, indicating safe reuse. The description adds context by noting it regenerates from on-disk state, which is consistent with annotations. It does not contradict annotations and provides useful behavioral insight beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences. The first sentence states the action and target, and the second provides a use case. No unnecessary words or repetition; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool and the presence of an output schema, the description adequately covers purpose and usage. It could optionally mention that INDEX.md is overwritten, but the idempotent and non-destructive annotations imply this is safe. The description is complete enough for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already contains a description for 'shelf_path' ('Path to the shelf root directory.'), which fully explains the parameter. The tool description does not add any extra meaning to this parameter. Since schema coverage is 0% (description does not mention parameters), but the schema itself is descriptive, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool regenerates INDEX.md from the current on-disk shelf state. The verb 'Regenerate' and the resource 'INDEX.md' are specific and unambiguous. It distinguishes itself from siblings like docshelf_add_document and docshelf_search by focusing on index reconstruction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Useful after manual edits to docs/ or .docshelf.json', providing a clear scenario for when to use the tool. It does not explicitly state when not to use it, but the implied context is sufficient given the tool's specific purpose. No alternative is needed as it's the only index rebuild tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a document — its file, split sections, and metadata entry.
Accepts the filename, the slug, or the human title used at add time.
INDEX.md is regenerated automatically. Pass dry_run=true to see
what would be deleted without touching anything. The caller still owns
the git commit / push step.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true. The description adds significant context: removes file, split sections, metadata entry, regenerates INDEX.md, and offers dry_run for safe preview. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise: three sentences with front-loaded purpose, no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature and the presence of an output schema (not shown), the description covers effects, dry-run, and post-step responsibilities. It is complete for safe agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions already cover all parameters thoroughly (e.g., document accepts filename/slug/title, dry_run effect). The description repeats some of this but adds no new meaning beyond the schema, resulting in baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Remove' and the resource 'document', including what is removed (file, split sections, metadata). It distinguishes from siblings like add, rename, rebuild by the specific action and side effects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains acceptable inputs (filename, slug, title) and mentions dry_run for preview. It also notes that the caller must commit/push. However, it does not provide explicit when-to-use vs alternatives, but context is clear for a removal tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retitle, recategorize, or re-describe a document — no re-conversion.
Moves the document .md, its split-section directory, and its
.meta.json entry (changing the slug when the title changes, or the
directory when the category changes), then regenerates INDEX.md. Give at
least one of new_title / new_category / new_description. Refuses
to clobber an existing target. Pass dry_run=true to preview. The caller
still owns the git commit / push step.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, and the description adds detailed behavioral context: it moves files, changes slugs, regenerates INDEX.md, and refuses to overwrite existing targets. This goes beyond the annotations to give a clear picture of side effects and safety mechanisms.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, with a clear summary in the first sentence. Each additional sentence provides necessary details like required parameters, conflict handling, dry-run, and ownership of git step. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructiveHint annotation and presence of an output schema, the description fully covers the tool's behavior, constraints, and prerequisites. It explains side effects, dry-run capability, and the caller's responsibility for git commits, making it complete for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has detailed descriptions for each parameter. The tool description adds value by explaining the relationship between new_title and slug changes, and new_category and directory moves, but this is more behavioral than semantic. Given high schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb and resource: 'Retitle, recategorize, or re-describe a document — no re-conversion.' It explicitly states the tool's primary purpose and distinguishes it from siblings like docshelf_add_document (adding) and docshelf_remove_document (removing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent which parameters are at least one required ('Give at least one of new_title / new_category / new_description'), explains behavior on conflict ('Refuses to clobber'), and provides a dry-run option. It also mentions post-invocation steps. However, it does not explicitly list when not to use this tool or compare it to alternatives like docshelf_read_document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plain-text search across every Markdown file in the shelf.
Tokens are space-split; each must appear (case-insensitive) for a hit
to count. If no file contains all tokens, the search falls back to
any-token matching and the response reports match_mode: "any".
Heading/title matches are ranked above body-only matches, and for a
split document the section files are returned rather than the
whole-file parent. Results include the relative path, a
word-boundary-trimmed snippet, and — if a remote is configured — the
fetch URL so the model can pull the matching file directly.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly, idempotent, and non-destructive annotations, the description discloses case-insensitive token matching, all-token vs. any-token fallback with match_mode, heading-priority ranking, section-file behavior for split documents, and the remote fetch URL. These are substantive behavioral details that materially affect how an agent interprets results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, and every subsequent sentence contributes operational detail. It is thorough without being bloated or repetitive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with an output schema and strong annotations, the description covers scope, matching, fallback, ranking, split-document behavior, and result fields. The sole notable gap is the lack of explanation for the optional shelf_path parameter, which prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the shelf_path parameter at all and does not mention max_results. Since schema description coverage is reported as 0%, the description was expected to compensate for parameter-level meaning, but it only covers query semantics and result shape, leaving the optional parameters ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Plain-text search across every Markdown file in the shelf.' It clearly distinguishes this tool from sibling read, list, and write tools, and the detailed matching semantics make its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended use clear: keyword search over the whole shelf, with explicit fallback and ranking behavior. It does not explicitly name alternatives or state when to prefer docshelf_read_document, but the search-versus-read distinction is strongly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.4.1docshelf_convert_pdfdocshelf_list_documentsdocshelf_searchv0.3.0docshelf_add_directorydocshelf_add_document4 fields changedInput schema / $defs / AddDocumentInput / properties / overwriteAdded value: +{
+ "default": false,
+ "description": "Replace an existing document when a different title/category slugifies onto the same file path. Off by default so a slug collision can't silently destroy an earlier document — the call errors instead. Re-adding the same title is always an in-place update and needs no flag.",
+ "title": "Overwrite",
+ "type": "boolean"
+}Input schema / $defs / AddDocumentInput / properties / slugAdded value: +{
+ "anyOf": [
+ {
+ "maxLength": 200,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Optional filename stem, decoupling the on-disk file from the display title. When set, the document is written to docs/<category>/<slug>.md (the slug is slugified for filesystem safety) while 'title' stays the INDEX/heading text untouched — e.g. a Cyrillic title at a latin, date-prefixed path like '2026-07-22-m1-build-sprint'. Defaults to deriving the filename from the title.",
+ "title": "Slug"
+}Input schema / $defs / AddDocumentInput / properties / source_path / descriptionPrevious value: -"Absolute path to the source .pdf or .md file on disk."New value: +"Absolute path to the source file. Supported: .md, .pdf, .docx, .html/.htm, .epub (DOCX/HTML/EPUB need the matching extra, e.g. pip install 'docshelf-mcp[formats]')."Input schema / $defs / AddDocumentInput / properties / title / descriptionPrevious value: -"Human-readable document title. Used as the INDEX entry and (slugified) as the filename."New value: +"Human-readable document title. Used as the INDEX entry and (slugified) as the filename unless 'slug' is given."docshelf_convert_pdfdocshelf_doctordocshelf_init_shelf3 fields changedInput schema / $defs / InitShelfInput / properties / manifestAdded value: +{
+ "default": false,
+ "description": "Also scaffold a shelf.yml manifest (shelf-spec v0: spec_version 0.1, mode single, profile document) next to .docshelf.json, making the shelf conformant to openshelf's shelf-spec. Off by default; a shelf without one stays valid. Never overwrites an existing manifest.",
+ "title": "Manifest",
+ "type": "boolean"
+}Input schema / $defs / InitShelfInput / properties / providerAdded value: +{
+ "default": "github",
+ "description": "URL provider for generated links: 'github' (default), 'gitlab', 'gitea', 'custom' (uses url_template), or 'none' (relative links for offline/local shelves).",
+ "enum": [
+ "github",
+ "gitlab",
+ "gitea",
+ "custom",
+ "none"
+ ],
+ "title": "Provider",
+ "type": "string"
+}Input schema / $defs / InitShelfInput / properties / url_templateAdded value: +{
+ "default": "",
+ "description": "For provider='custom': URL template with {owner}, {repo}, {branch}, {path} placeholders. Covers S3, R2, or any static host.",
+ "maxLength": 500,
+ "title": "Url Template",
+ "type": "string"
+}docshelf_list_documentsdocshelf_read_documentdocshelf_remove_documentdocshelf_rename_documentdocshelf_searchv0.2.0docshelf_add_documentdocshelf_convert_pdfdocshelf_init_shelfdocshelf_list_documentsdocshelf_rebuild_indexdocshelf_searchEach tool targets a distinct operation: init, add single, add batch, read, remove, rename, rebuild index, doctor check, search, list, and standalone conversion. While add_document and convert_pdf both handle PDF conversion, the former commits to the shelf while the latter does not, making their purposes clearly separable. No two tools appear to overlap in function.
All tools follow a consistent `docshelf_<verb>_<noun>` snake_case pattern, with clear, descriptive verbs like add, remove, rename, search, list, convert. The only slightly unusual verb is 'doctor', but it is intuitive for a health-check tool. The prefix is uniformly applied across all 11 tools, creating a strong, predictable convention.
11 tools is well within the ideal 3–15 range for a domain-specific server. Each tool serves a distinct need in the document shelf lifecycle, from initialization and document ingestion to search, maintenance, and standalone conversion. No tool feels superfluous, and the surface is neither too sparse nor overloaded.
The tool set covers the full lifecycle of a document shelf: create (init), add documents (both single and batch), read, remove, rename (update metadata), list, search, and rebuild the index. Additionally, a 'doctor' tool addresses drift repair and a standalone PDF converter supports pre-shelf workflows. There are no obvious gaps or dead ends for the stated purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
DocBase MCP server for AI agents
Shared knowledge base for AI agents. Semantic search across agents, no setup required — just a URL.
Self-hosted AI prompt library: prompts, collections, tags, teams, chains. 29 MCP tools for agents.
65+ AI tools as MCP: research, write, code, scrape, translate, RAG, agent memory, workflows
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ignatenkofi/docshelf-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
