librian 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# librian-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Find and read the right section of a markdown docs folder without loading whole files.
+librian gives AI agents a file list, per-file outlines with line ranges, section reads and section-level search, over MCP.
+It keeps no saved index: every call reflects the files on disk at that moment, so it stays correct while several agents edit the same docs.
+
+Status: early release. Tool inputs and output formats may still change before 1.0.
+
+Requires Node.js 22.13 or newer.
+
+## Why
+
+A large docs folder costs tokens twice: reading a whole file to find one section, and grepping lines that come back truncated.
+librian answers with small, structured pieces instead: titles first, then only the section you ask for.
+
+## Get started
+
+```
+npx -y librian@latest        # or: npm i -g librian, then run `librian`
+```
+
+This opens the librian menu. Then:
+
+1. **Runtime → Install**: installs librian into `~/.librian/runtime`.
+2. **Add docs folder**: give it a name and the path of a docs folder (see below). Repeat for more folders.
+3. **AI services**: switch on Claude Code and/or Codex, then **Apply**. librian shows the commands it will run and asks before running them.
+4. Open a new session in Claude Code or Codex. Sessions that are already open keep what they started with.
+
+To update, open `librian` → **Runtime → Check for updates**. To undo a registration, switch the service off in **AI services** and **Apply**.
+
+## The menu
+
+Run `librian` in a terminal. Without a terminal (a pipe or a script) it prints the usage instead.
+
+### Docs folders
+
+The main screen lists your docs folders; each one is an entry with a name and a path, like a connection in a database tool.
+Choose an entry to **Edit**, **Check** (file count, total size, largest files) or **Remove** it. Removing an entry never touches the folder itself.
+
+An entry has:
+
+| Field | Meaning |
+| --- | --- |
+| Name | 1 to 24 characters: a lowercase letter, then lowercase letters, digits or `_`. Defaults to the folder name (`akms.docs` becomes `akms_docs`). It prefixes the tool names. |
+| Docs folder | Absolute path of the folder that holds the markdown files. |
+| Exclude | Folder names (`evidence`) or root-relative paths (`ks/archive`) to skip. Folders starting with `.` and `node_modules` are always skipped. |
+| Max bytes | Response size limit in UTF-8 bytes. Default 16000, minimum 4000. |
+
+Symbolic links and junctions are not followed. librian only reads your docs; it never writes to them.
+
+Adding, editing or removing an entry takes effect in new sessions only.
+
+### AI services
+
+Registers librian as one MCP server named `librian` in **Claude Code** and **Codex**, for all your projects (user scope).
+It runs `claude mcp add --scope user …` and `codex mcp add …` for you, and `… mcp remove …` to unregister.
+Before running anything it shows the exact commands; unregistering asks with **No** as the default.
+After registering it starts the server once and reports how many tools it offers (it does not call any tool).
+
+A service whose command (`claude`, `codex`) is not on your `PATH` shows `command not found` and cannot be switched on.
+If `librian` is already registered there with a different command, Apply replaces it and says so in the preview.
+
+### Runtime
+
+librian installs itself with `npm install --prefix ~/.librian/runtime librian`, so the registered server does not depend on `npx` or a download at session start.
+**Install**, **Check for updates** (asks npm only when you choose it) and **Update to X** do what they say; **Uninstall** removes the runtime folder and offers to unregister the services first.
+Docs entries are kept.
+
+### Where things live
+
+| Path | Content |
+| --- | --- |
+| `~/.librian/catalog.json` | Your entries and which services are registered. No secrets. |
+| `~/.librian/runtime/` | The installed package. |
+
+Set `LIBRIAN_HOME` to use another folder. When it is not the default, the registered command carries it along.
+
+## What the AI sees
+
+One server, four tools per docs folder, prefixed with the entry name: for an entry `akms` the tools are `akms__list`, `akms__outline`, `akms__read` and `akms__search`.
+Each tool description names its folder, and the server instructions list the folders with their file counts. A folder that is missing on disk offers no tools and is marked `unavailable`.
+
+| Tool | Input | Returns |
+| --- | --- | --- |
+| `list` | `prefix?` | Files with size and document title, grouped by folder. `prefix` is a root-relative path start: `ks/ci` matches `ks/ci/…` and `ks/ci-notes.md`, `ks/ci/` matches the folder only. |
+| `outline` | `ref` | Headings of a file or of one section, each with its line range and size. |
+| `read` | `ref` | The text of a whole file, one section or a line range. |
+| `search` | `query`, `prefix?`, `limit?`, `offset?` | Blocks that contain every word of the query, each with its `path:start-end`, ancestor headings, size, number of hits and a one-line excerpt. |
+
+A typical session: `search` or `list` to find the file, `outline` to see its headings, `read` one section.
+
+### References
+
+`outline` and `read` take a reference string, relative to the folder of the tool you call:
+
+| Reference | Points to |
+| --- | --- |
+| `path` | The whole file |
+| `path#heading` | The section under that heading. Give the heading text (`guide/setup.md#3.3 Pipes`) or its GitHub anchor (`guide/setup.md#33-pipes`). |
+| `path:start-end` | A line range |
+| `path:line` | The block containing that line |
+
+`outline` accepts `path` and `path#heading` only.
+When you pass a reference to another agent or write it into a document, prefer `path#heading`: line ranges move when the file is edited.
+
+### Search
+
+- Words are separated by spaces; wrap a phrase in double quotes to keep it as one word. Matching ignores case.
+- A word made only of letters, digits and `_` matches at the start of a word (`uat` matches `UAT` and `uat_token`, not `evaluate`). Other words, such as Korean, match anywhere.
+- Every word must appear in the same block, a heading plus the text up to the next heading. Ancestor headings count, so a block under `## Release rail` matches `release deploy` even if only `deploy` is in its text.
+- Results are ordered by words found in headings, then hits, then path and line.
+
+### Limits and continuing
+
+Each response stays within the entry's byte limit (16000 by default, roughly 4–5 thousand tokens of Korean text).
+When something is bigger, the response says how to get the rest:
+
+- `read` of a large file returns its outline; `read` of a large section with subsections returns the section's own text plus the subsection outline.
+- `read` of a large section without subsections returns the first page and ends with `Continue: path:next-end`. Pass that reference to `read` to get the next page.
+- `search` and `list` end with `More: offset=N` or a hint to narrow with `prefix`.
+
+## Advanced: one folder, registered by hand
+
+`librian serve --root <folder>` serves a single folder with unprefixed tools (`list`, `outline`, `read`, `search`), without the menu or the catalog:
+
+```
+claude mcp add librian-docs -- npx -y librian serve --root ./docs
+```
+
+On native Windows, if a client cannot start `npx` directly, wrap it: `claude mcp add librian-docs -- cmd /c npx -y librian serve --root ./docs`.
+
+Codex (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.librian-docs]
+command = "npx"
+args = ["-y", "librian", "serve", "--root", "/path/to/docs"]
+```
+
+```
+librian serve --root <folder> [--exclude <name>]... [--max-bytes <n>]
+librian serve --catalog
+librian --help | --version
+```
+
+`--root`, `--exclude` and `--max-bytes` mean what the entry fields above mean; `--root` exits with code 2 if the folder does not exist.
+`serve --catalog` is what the registered services run: it reads `catalog.json` once at start.
+
+## Contributing
+
+To run a checkout of this repository instead of the published package, build it (`npm run build`) and use **Runtime → Use a local checkout** in the menu.
+
+## License
+
+AGPL-3.0-or-later. See [LICENSE](LICENSE) and [NOTICE](NOTICE).