Bindery

Markdown book authoring toolkit: VS Code extension + Obsidian plugin for typography formatting and multi-format export, paired with an MCP server for full-text search and AI assistant integration.

Origin

This project started as a personal writing tool, born out of frustration with the copy-paste loop that most AI-assisted writing ends up as.

It started with Word and ChatGPT: writing a chapter, copying it into the browser, getting feedback, pasting it back. Versioning was an issue and keeping the ChatGPT project up to date with recent .docx files was a lot of work. Moving to VS Code and Markdown files seemed like the natural next step: plain text, version control, and the ability to plug in an MCP server so an agent like Codex could read the book directly.

In practice though, I still fell back to copy-pasting for feedback and only really used the tooling for typography formatting. Most VS Code extensions are built for coding: short iterations where the code is the truth, rather than the longer-running, chat-based sessions you get in web tools. That frustration is what pushed the VS Code extension into existence. At minimum, the formatting and exporting should just work without any ceremony.

The bigger shift came with Claude Cowork, which combines the session memory of a long-running agent with direct file access. That made the MCP server genuinely useful: the agent could navigate chapters, search for context, and keep track of the story across a session without being handed everything manually. The extension and MCP server now support both workflows: VS Code agents (Copilot, Codex, Claude for VS Code) and standalone Claude Desktop / Cowork. And a Obsidian plugin with the same functionality as the VS Code extension for users that don't work with a more development minded VS Code.

Components

vscode-ext/ — VS Code Extension

The Bindery extension provides:

• Typography formatting — curly quotes, em-dashes, ellipses, smart apostrophes (on save or on demand)
• Chapter merge & export — Markdown, DOCX, EPUB, PDF output via Pandoc + LibreOffice, with auto-detection of tool paths
• Dialect & translation management — extensible substitution rules for dialect exports (e.g. US→UK), plus cross-language glossaries in .bindery/translations.json
• Multi-language support — configurable per-language chapter labelling and folder structure, with dialect derivatives
• Opinionated workspace setup — .bindery/settings.json plus Arc, Notes, Characters, SESSION, PREFERENCES, and memory scaffolding
• MCP integration — registers Bindery tools for GitHub Copilot Chat and writes .vscode/mcp.json for Claude / Codex

Install from the VS Code Marketplace or:

cd vscode-ext
npm install
npm run compile
npx @vscode/vsce package

See vscode-ext/README.md for full documentation.

mcp-ts/ — MCP Server (Node.js / TypeScript)

A Model Context Protocol server that exposes your book project to AI assistants. Pure Node.js.

• BM25 full-text search — fast lexical search across all chapters and notes via MiniSearch
• Optional semantic search — set BINDERY_OLLAMA_URL for semantic reranking, or enable a full semantic index for precomputed embedding search
• Version tracking — bindery_get_review_text returns a structured git diff plus any regions wrapped in <!-- Bindery: Review start --> ... <!-- Bindery: Review stop --> markers (so committed work-in-progress can still be reviewed). bindery_git_snapshot saves progress as a git commit. Git is auto-initialized during workspace setup if available
• Translation & dialect management — glossary entries and dialect substitution rules in .bindery/translations.json, queryable and updatable by agents
• Opinionated authoring scaffold — bindery_init_workspace creates SESSION.md, PREFERENCES.md, Arc/index.md, Arc/Overall.md, Arc/Acts/, Notes/Inbox.md, Notes/Characters/index.md, structured note folders, and .bindery/memories/global.md
• Story note management — agents can list, read, create, and append notes under the configured notes folder while bindery_get_notes remains compatible with older recursive note layouts
• Session memory — persistent .bindery/memories/ files for cross-session decisions, with append, list, and compact operations
• Session focus — bindery_session_focus_* tools maintain the ephemeral working-state file SESSION.md (current focus, next actions, open questions, handoff); durable preferences live in the user-owned PREFERENCES.md
• Inbox triage — bindery_inbox_process enumerates loose items in Notes/Inbox.md and proposes destinations (read-only); bindery_inbox_resolve clears items after they are routed and confirmed — rough/pasted material goes to the Inbox, not memory
• Structured arc & character management — agents can create/update arc files and character profiles using structured tools that keep indexes in sync
• Host command parity — VS Code and Obsidian expose command-palette actions for notes, characters, arcs, memory, and session focus, backed by the same structured tool functions agents use
• Multi-book support — configure one or more books via --book Name=path CLI args or BINDERY_BOOKS env var; every tool call specifies which book to use by name (agents never see raw paths)
• Container/mount aware — agents in sandboxed environments (e.g. Cowork) can call bindery_identify_book with their working directory to discover their book name, even when mount paths differ from the configured paths

See mcpb/README.md for the full tool reference and usage examples.

obsidian-plugin/ — Obsidian Plugin

The Bindery Obsidian plugin provides the same feature set as the VS Code extension for Obsidian vault users:

• Typography formatting — curly quotes, em-dashes, ellipses, smart apostrophes (on save or on demand)
• Chapter merge & export — Markdown, DOCX, EPUB, PDF output via Pandoc + LibreOffice
• Dialect & translation management — extensible substitution rules and glossaries
• Multi-language support — configurable per-language chapter labelling
• Opinionated workspace setup — .bindery/settings.json plus Arc, Notes, Characters, SESSION, PREFERENCES, and memory scaffolding
• AI instruction generation — Generate CLAUDE.md, copilot-instructions.md, .cursor/rules, AGENTS.md
• Review markers — Mark regions for agent feedback
• Opinionated authoring commands — command-palette actions for notes, characters, arcs, memory, and session focus
• MCP snippet generator — Copy JSON for Claude Desktop integration

Build and install:

cd obsidian-plugin
npm install
npm run compile
npm run bundle
# out/main.js is ready for manual Obsidian installation

Then in Obsidian: Settings → Community plugins (if not restricted) → Install from folder or manual install from out/main.js.

mcpb/ — Claude Desktop Extension

Release assets now include two MCP package formats:

• bindery-<version>.mcpb for Claude Desktop / Cowork
• bindery-mcp-server-<version>.zip as a standalone MCP package for clients that support command + args + env setup (for example ChatGPT Work or LM Studio)

Download the latest release from Releases — no build step needed.

Quick Start

VS Code (Copilot / Claude / Codex)

1. Install the Bindery extension from the Marketplace
2. Open your book folder in VS Code
3. Run Bindery: Initialize Workspace to create .bindery/settings.json, .bindery/translations.json, the generated .bindery/README.md capability reference, and the opinionated Arc / Notes / Characters / SESSION / PREFERENCES / memory scaffold
4. Run Bindery: Register MCP Server to create .vscode/mcp.json (primarily for Claude/Codex discovery; not needed for GitHub Copilot Chat because the extension registers the tools automatically)
5. Tools are now available in GitHub Copilot Chat, Claude for VS Code, and Codex

Claude Desktop / Cowork

1. Download bindery-mcp-*.mcpb from the latest release
2. Open Claude Desktop → Settings → Extensions → Install from file
3. Fill in the Books field with semicolon-separated Name=path pairs: ScaryBook=C:\Users\My\Projects\ScaryBook;MyNovel=D:\Writing\MyNovel
4. Optionally set the Ollama URL if you want semantic reranking
5. Optionally enable the semantic index and choose a default search mode if you want full_semantic search with rebuild warnings when the embedding index becomes stale.
   • Note: full embedding can be a heavy operation, depending on your hardware, when running a local Ollama instance.
6. Tools are now available — the agent calls bindery_list_books to discover book names

Standalone MCP Clients (ChatGPT Work, LM Studio, etc.)

1. Download bindery-mcp-server-*.zip from the latest release
2. Unzip it to a stable folder
3. In your MCP client, add an MCP server with:

• eg. in ChatGPT Work -> Settings -> Plug-ins -> MCPs tab
• Command: node
• Args: absolute path to server/index.js from the unzipped folder

4. Set environment variables:

• BINDERY_BOOKS (required): semicolon-separated Name=path pairs
• BINDERY_OLLAMA_URL (optional): Ollama endpoint for semantic features
• BINDERY_ENABLE_SEMANTIC_INDEX (optional): true to enable full semantic index builds
• BINDERY_DEFAULT_SEARCH_MODE (optional): lexical, semantic_rerank, or full_semantic
• BINDERY_MCP_LOCATION (optional): stable folder used by bindery_download_latest_mcp to download and unpack the latest standalone MCP ZIP (tool never edits client settings)

5. Save and reconnect the MCP server

Update behavior

• bindery_health checks the latest GitHub release and reports installed vs latest version in its JSON response.
• bindery_health also reports can_auto_download_release and mcp_download_location based on BINDERY_MCP_LOCATION.
• When outdated, agents should tell the user: installed version, latest version, and the release URL.
• bindery_download_latest_mcp is only for standalone ZIP-based MCP clients (for example ChatGPT Work or LM Studio), and only when BINDERY_MCP_LOCATION is configured.
• Claude Desktop/Cowork should use the .mcpb installer flow, not the ZIP updater tool.

Architecture Overview

The following flow shows how Bindery's writing environments connect to agents, MCP, and skills at a high level.

flowchart TD
  U([User])

    subgraph IWE[Writing Environment]
      VS[VS Code + Bindery Extension]
      OB[Obsidian + Bindery Plugin]
      AG[In-editor Agent]
    end

    subgraph AT[Bindery Agent Tools]
      MCP[Bindery MCP Server]
      SK[Bindery Skills]
    end

    CL["Claude Desktop (Cowork)"]    
    WB[Book Workspace Files]

    U --> IWE
    U --> CL

    IWE --> WB

    VS --> AG
    OB --> AG

    AG --> AT
    CL --> AT

    MCP --> WB

Formatting & Export only (no MCP)

The VS Code extension and Obsidian plugin both work standalone — no server setup needed for typography formatting and export.

Project Structure

├── bindery-core/        Shared templates & types (TS)
│   ├── src/
│   │   └── templates/   AI instruction templates (claude, copilot, cursor, agents, skills)
│   └── package.json
├── bindery-merge/       Shared merge logic (TS)
│   ├── src/
│   │   ├── merge.ts     Chapter discovery, merge, export via Pandoc/LibreOffice
│   │   └── tool-locate.ts   Cross-platform tool path resolution
│   └── package.json
├── vscode-ext/          VS Code extension (TS)
│   ├── src/
│   ├── package.json
│   └── README.md
├── obsidian-plugin/     Obsidian plugin (TS)
│   ├── src/
│   ├── package.json
│   └── README.md
├── mcp-ts/              MCP server (Node.js / TS)
│   ├── src/
│   └── package.json
├── mcpb/                Claude Desktop extension
│   ├── manifest.json
│   └── server/          (CI-populated)
└── LICENSE

Shared logic in bindery-core and bindery-merge ensures both vscode-ext and obsidian-plugin implement identical functionality.

Prerequisites

• One writing environment:
  • VS Code 1.85+
  • Obsidian Desktop with Community Plugins enabled
• Git (recommended) — needed for version tracking, bindery_get_review_text, and bindery_git_snapshot. Auto-initialized during workspace setup.
  • Install via package manager or from https://git-scm.com
• Pandoc (optional) — needed for DOCX/EPUB/PDF export.
  • Install via package manager or from https://pandoc.org/installing.html
• LibreOffice (optional) — needed for PDF export only.
  • Install via package manager or from https://www.libreoffice.org
• Ollama (optional) — needed for semantic reranking and search.
  • Install via package manager or from https://ollama.com/

Pandoc / LibreOffice auto-detection

On all platforms the extension resolves tool paths in this order:

1. Explicit bindery.pandocPath / bindery.libreOfficePath user setting (if set and the file exists)
2. Command on PATH (where.exe on Windows, which elsewhere)
3. Well-known install locations:
   • Windows: %LOCALAPPDATA%\Pandoc\pandoc.exe, %ProgramFiles%\Pandoc\pandoc.exe, %ProgramFiles%\LibreOffice\program\soffice.exe
   • macOS: /opt/homebrew/bin/pandoc, /usr/local/bin/pandoc, /Applications/LibreOffice.app/Contents/MacOS/soffice
   • Linux: /usr/bin/pandoc, /usr/bin/libreoffice

You usually do not need to configure anything — install Pandoc/LibreOffice normally and exports will work. Use the bindery_health MCP tool to see what was detected and whether a newer Bindery release is available.

Known limitations

• Git must be on PATH (or at a standard install location) for bindery_get_review_text and bindery_git_snapshot. If git isn't found, these tools fail with a clear error; all other tools still work.
• Pandoc is required for DOCX, EPUB, and PDF export. Markdown-only export has no external dependencies.
• LibreOffice is required only for PDF export. Bindery generates PDFs by producing a DOCX via Pandoc and then converting with LibreOffice headless.
• Semantic search requires an optional Ollama instance. Without it, lexical BM25 search still works offline. Configure with BINDERY_OLLAMA_URL; optional tuning via BINDERY_OLLAMA_TIMEOUT_MS (default 15000) and BINDERY_OLLAMA_RETRIES (default 1).
• Large books with semantic indexing can take several minutes to embed on first build. Rebuilds are incremental when chapter content is unchanged.
• Chapter numbering: the tools sort chapters by filename but accept non-contiguous numbers. bindery_get_overview now flags gaps (e.g. chapters 1, 3 with no 2) as a warning.
• Search index format: bumped automatically when the on-disk format changes. Older indexes are silently ignored and rebuilt on next use — no manual action required.

Privacy

Bindery stays within your workspace, only if the optional Ollama URL is filled for the MCP server will texts be sent to Ollama for embedding / semantic search. The full privacy policy can be viewed at https://evdboom.nl/projects/bindery/privacy

License

MIT — see LICENSE.

Contributing — template source of truth

Host Parity Reminder

vscode-ext/ and obsidian-plugin/ are two equal implementations of the same Bindery authoring toolkit. Both support:

• Typography formatting (curly quotes, em-dashes, ellipses)
• Chapter merge & export (MD, DOCX, EPUB, PDF via Pandoc + LibreOffice)
• Dialect & translation management — extensible substitution rules and glossaries
• Multi-language support — configurable chapter labels and folder structures
• Workspace initialization — .bindery/settings.json, .bindery/translations.json, generated .bindery/README.md, and the opinionated Arc / Notes / Characters / SESSION / PREFERENCES / memory scaffold
• AI instruction generation — CLAUDE.md, copilot-instructions.md, .cursor/rules, AGENTS.md
• Review markers — wrap text in <!-- Bindery: Review start/stop --> for agent feedback
• MCP config snippet — JSON for Claude Desktop / Cowork integration
• Workspace management — add languages, dialects, and translation entries

Both plugins share all core logic via @bindery/merge (chapter discovery, merge execution, tool path resolution) to minimize duplication and ensure consistent behavior. Shared templates in @bindery/core/src/templates/ feed both VS Code and Obsidian workflows.

Unless a change is intentionally host-specific, functional additions to one should be mirrored in the other in the same PR or a clearly linked follow-up PR.

The AI instruction file templates are maintained in one place only:

bindery-core/src/templates/*.ts   ← SINGLE SOURCE OF TRUTH (one file per template)

mcp-ts/src/templates.ts is a thin re-export shim to keep existing imports stable. Consumers should continue importing from their local package entrypoint, but template edits belong in the matching file under bindery-core/src/templates/.

Syncing locally

After changing files under bindery-core/src/templates/, rebuild and test the workspace:

npm run build --workspace=bindery-core
npm test --workspace=bindery-core
npm test --workspace=mcp-ts
npm test --workspace=vscode-ext
npm test --workspace=obsidian-plugin

Running tests

# Shared packages
cd bindery-core && npm test
cd bindery-merge && npm test

# MCP server
cd mcp-ts && npm test

# VS Code extension
cd vscode-ext && npm test

# Obsidian plugin
cd obsidian-plugin && npm test

What CI does

The CI workflow (.github/workflows/ci.yml) runs on every push and pull request:

1. Builds and tests bindery-core, mcp-ts, vscode-ext, and obsidian-plugin (Ubuntu, Windows, macOS).
2. Runs the tool parity guard (scripts/check-tool-parity.mjs) and command parity guard (scripts/check-command-parity.mjs) on the coverage job.
3. Enforces coverage thresholds (statements 80%, branches 65%, functions 90%, lines 80%) across packages.