@twelvetake/scrivener-mcp 1.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TwelveTake Studios LLC
+
+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.

package/README.md

@@ -0,0 +1,543 @@
+# Scrivener MCP Server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that lets AI assistants read, write, and organize [Scrivener](https://www.literatureandlatte.com/scrivener/overview) projects. Works with Claude, ChatGPT, Gemini, and other MCP-compatible AI tools.
+
+## Features
+
+- **Read & Write** - Full access to manuscript content, notes, and synopses
+- **Organize** - Create, move, rename, and delete documents and folders
+- **Search** - Find content across your entire project with context
+- **Compile** - Export your manuscript to PDF directly from AI
+- **Continuity Tools** - Check character/setting consistency across your manuscript
+
+Perfect for writers who want AI assistance with drafting, revision, outlining, or project organization.
+
+## Requirements
+
+- Node.js 18 or higher
+- Scrivener 3 (macOS or Windows)
+- An MCP-compatible AI client (Claude Desktop, ChatGPT Desktop, Cursor, etc.)
+
+## Installation
+
+### Option 1: npm (Recommended)
+
+```bash
+npm install -g @twelvetake/scrivener-mcp
+```
+
+Then add to your MCP client's configuration. For Claude Desktop (`claude_desktop_config.json`):
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "scrivener": {
+      "command": "scrivener-mcp"
+    }
+  }
+}
+```
+
+### Option 2: From Source
+
+1. Clone and build:
+   ```bash
+   git clone https://github.com/TwelveTake-Studios/scrivener-mcp.git
+   cd scrivener-mcp
+   npm install
+   npm run build
+   ```
+
+2. Add to your Claude Desktop configuration:
+   ```json
+   {
+     "mcpServers": {
+       "scrivener": {
+         "command": "node",
+         "args": ["/full/path/to/scrivener-mcp/dist/index.js"]
+       }
+     }
+   }
+   ```
+
+3. Restart Claude Desktop
+
+## Quick Start
+
+Once installed, try these commands with your AI assistant:
+
+```
+Open my Scrivener project at /path/to/mynovel.scriv
+```
+
+```
+Show me the structure of my manuscript
+```
+
+```
+Read Chapter 3
+```
+
+```
+Create a new scene called "The Confrontation" in Chapter 5
+```
+
+```
+Compile everything up to Chapter 7 into a PDF
+```
+
+```
+Find all mentions of "Sarah" and check if her descriptions are consistent
+```
+
+---
+
+## Available Tools (22 total)
+
+### Project Management
+
+| Tool | Description |
+|------|-------------|
+| `open_project` | Open a Scrivener project (.scriv folder) |
+| `get_structure` | Get the hierarchical structure of the project binder |
+
+### Document Operations
+
+| Tool | Description |
+|------|-------------|
+| `read_document` | Read content from a document (optionally includes synopsis) |
+| `write_document` | Write/replace content in a document |
+| `append_to_document` | Append content to end of document without replacing |
+| `create_document` | Create new documents or folders |
+| `delete_document` | Move documents to trash |
+| `move_document` | Reorganize items in the binder |
+| `rename_document` | Rename documents |
+| `batch_read` | Read multiple documents at once (more efficient) |
+
+### Synopsis & Notes
+
+| Tool | Description |
+|------|-------------|
+| `read_synopsis` | Read the synopsis (index card text) |
+| `write_synopsis` | Write/update the synopsis |
+| `read_notes` | Read inspector notes for a document |
+| `write_notes` | Write/update inspector notes |
+
+### Search
+
+| Tool | Description |
+|------|-------------|
+| `search_content` | Search across all documents |
+| `search_with_context` | Search with surrounding paragraphs for context |
+
+### Compile & Export
+
+| Tool | Description |
+|------|-------------|
+| `get_compile_order` | Preview what will be compiled |
+| `compile_manuscript` | Export manuscript to PDF |
+| `set_include_in_compile` | Toggle document's "Include in Compile" setting |
+| `word_count` | Get word count for document or entire manuscript |
+
+### Continuity Checking
+
+| Tool | Description |
+|------|-------------|
+| `find_all_mentions` | Find all sentences mentioning a term |
+| `compare_descriptions` | Find descriptive sentences to check consistency |
+
+---
+
+## Tool Reference
+
+### open_project
+
+Open a Scrivener project to work with.
+
+**Parameters:**
+- `path` (required): Path to the .scriv project folder
+
+**Example:**
+```
+Open my project at D:/Writing/MyNovel.scriv
+```
+
+---
+
+### get_structure
+
+View the binder hierarchy of your project.
+
+**Parameters:**
+- `folderId` (optional): Get structure for specific folder only
+- `maxDepth` (optional): Maximum depth to traverse
+
+**Example:**
+```
+Show me the structure of my manuscript
+Show me only what's in Chapter 3
+```
+
+---
+
+### read_document
+
+Read the content of a document.
+
+**Parameters:**
+- `documentId` (required): UUID of the document
+- `includeSynopsis` (optional): If true, returns both content and synopsis
+
+**Example:**
+```
+Read the content of "Chapter 1 - The Beginning"
+Read Chapter 3 with its synopsis
+```
+
+---
+
+### write_document
+
+Replace the content of a document.
+
+**Parameters:**
+- `documentId` (required): UUID of the document
+- `content` (required): New content to write
+
+**Example:**
+```
+Replace the content of Scene 2 with the revised version
+```
+
+---
+
+### append_to_document
+
+Add content to the end of a document without replacing existing content.
+
+**Parameters:**
+- `documentId` (required): UUID of the document
+- `content` (required): Content to append
+- `separator` (optional): Separator between existing and new content (default: two newlines)
+
+**Example:**
+```
+Append this new paragraph to Chapter 5
+Add these notes to the end of the scene
+```
+
+---
+
+### create_document
+
+Create a new document or folder.
+
+**Parameters:**
+- `title` (required): Title of the new document
+- `parentId` (optional): UUID of parent folder (defaults to Draft/Manuscript)
+- `documentType` (optional): "Text" or "Folder" (default: "Text")
+- `content` (optional): Initial content
+
+**Example:**
+```
+Create a new chapter called "The Escape"
+Create a folder called "Act Two" and add three scenes to it
+```
+
+---
+
+### delete_document
+
+Move a document to the trash.
+
+**Parameters:**
+- `documentId` (required): UUID of the document to delete
+
+**Example:**
+```
+Delete the scene called "Old Draft"
+```
+
+---
+
+### move_document
+
+Move a document to a different folder.
+
+**Parameters:**
+- `documentId` (required): UUID of the document to move
+- `targetFolderId` (required): UUID of the target folder
+- `position` (optional): Position in target folder
+
+**Example:**
+```
+Move "The Discovery" scene to Chapter 4
+```
+
+---
+
+### rename_document
+
+Rename a document.
+
+**Parameters:**
+- `documentId` (required): UUID of the document
+- `newTitle` (required): New title
+
+**Example:**
+```
+Rename "Untitled Scene" to "The Confrontation"
+```
+
+---
+
+### batch_read
+
+Read multiple documents at once. More efficient than multiple read_document calls.
+
+**Parameters:**
+- `documentIds` (required): Array of document UUIDs to read
+
+**Example:**
+```
+Read all the scenes in Chapter 2
+```
+
+---
+
+### read_synopsis / write_synopsis
+
+Read or write the synopsis (index card text) for a document.
+
+**Parameters:**
+- `documentId` (required): UUID of the document
+- `synopsis` (required for write): Synopsis text
+
+**Example:**
+```
+Show me the synopsis for Chapter 3
+Update the synopsis for "The Chase" to summarize the new version
+```
+
+---
+
+### read_notes / write_notes
+
+Read or write inspector notes for a document.
+
+**Parameters:**
+- `documentId` (required): UUID of the document
+- `notes` (required for write): Notes content
+
+**Example:**
+```
+Show me my notes for Scene 5
+Add a note to Chapter 2 about the timeline
+```
+
+---
+
+### search_content
+
+Search for content across all documents.
+
+**Parameters:**
+- `query` (required): Search query
+
+**Example:**
+```
+Search for mentions of "the artifact"
+Find all scenes that reference the castle
+```
+
+---
+
+### search_with_context
+
+Search with surrounding paragraphs for better context.
+
+**Parameters:**
+- `query` (required): Search term
+- `contextParagraphs` (optional): Paragraphs before/after to include (default: 2)
+
+**Example:**
+```
+Search for "the ritual" with 3 paragraphs of context
+```
+
+---
+
+### get_compile_order
+
+Preview what documents will be compiled and in what order.
+
+**Parameters:**
+- `stopAtTitle` (optional): Stop at document with this title (partial match)
+
+**Example:**
+```
+Show me the compile order
+What would be compiled up to Chapter 5?
+```
+
+---
+
+### compile_manuscript
+
+Compile the manuscript to a PDF file.
+
+**Parameters:**
+- `outputPath` (required): Full path for the output PDF
+- `title` (optional): Book title for cover page and PDF metadata (default: project filename)
+- `author` (optional): Author name for cover page and PDF metadata
+- `stopAtTitle` (optional): Stop at document with this title
+- `includeTitle` (optional): Include document titles as headers (default: true)
+- `fontSize` (optional): Font size in points (default: 12)
+- `lineSpacing` (optional): Line spacing multiplier (default: 1.5)
+
+**Example:**
+```
+Compile my full manuscript to D:/Writing/MyNovel.pdf
+Compile with title "Keystone: Aftermath" by Dave Cilluffo
+Compile everything up to Chapter 7 to D:/Writing/Draft.pdf
+Compile with 14pt font and double spacing
+```
+
+---
+
+### set_include_in_compile
+
+Toggle whether a document should be included when compiling.
+
+**Parameters:**
+- `documentId` (required): UUID of the document
+- `include` (required): true to include, false to exclude
+
+**Example:**
+```
+Exclude the "Notes" document from compile
+Include "Deleted Scene" back in the compile
+```
+
+---
+
+### word_count
+
+Get word count for a specific document or the entire manuscript.
+
+**Parameters:**
+- `documentId` (optional): UUID of document (omit for entire manuscript)
+
+**Example:**
+```
+How many words are in my manuscript?
+What's the word count for Chapter 3?
+```
+
+---
+
+### find_all_mentions
+
+Find all sentences mentioning a term. Great for character/setting consistency checks.
+
+**Parameters:**
+- `term` (required): Term to search for (e.g., character name)
+
+**Example:**
+```
+Find all mentions of "Sarah"
+Show me every sentence that mentions "the lighthouse"
+```
+
+---
+
+### compare_descriptions
+
+Find descriptive sentences for a term (sentences with "was", "had", "looked", etc.). Helps identify inconsistent descriptions.
+
+**Parameters:**
+- `term` (required): Term to find descriptions for
+
+**Example:**
+```
+Find all descriptions of Sarah
+Check how I've described the mansion throughout the book
+Are my descriptions of Marcus consistent?
+```
+
+---
+
+## Important Notes
+
+- **Close Scrivener first** before using this server to avoid conflicts
+- The server modifies the `.scrivx` binder file and RTF content files directly
+- Always keep backups of important projects
+- Only documents marked "Include in Compile" are included in PDF export
+- This is an unofficial tool and is not affiliated with Literature & Latte
+
+## How It Works
+
+Scrivener projects (`.scriv` folders) contain:
+- A `.scrivx` XML file that defines the binder structure
+- Individual RTF files for each document's content
+- Synopsis and notes stored as plain text and RTF files
+
+This server parses and modifies these files directly, allowing AI assistants to interact with your project programmatically.
+
+## Support This Project
+
+If you find this useful, consider supporting development:
+
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?style=flat&logo=buy-me-a-coffee)](https://buymeacoffee.com/twelvetake)
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-support-ff5e5b?style=flat&logo=ko-fi)](https://ko-fi.com/twelvetake)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+## Changelog
+
+### v1.3.2
+- **Added title/author to compile** - `compile_manuscript` now accepts `title` and `author` parameters for cover page and PDF metadata
+
+### v1.3.1
+- **Fixed PDF compile formatting** - Paragraphs now have proper spacing instead of running together
+- **Added text formatting to PDF** - Bold, italic, and bold-italic are now rendered in compiled PDFs
+- **Improved chapter titles** - Larger font (18pt), bold, with better spacing
+
+### v1.3.0
+- **Added utility tools**: `word_count`, `append_to_document`, `set_include_in_compile`, `read_notes`, `write_notes`, `batch_read`
+- **Added continuity tools**: `search_with_context`, `find_all_mentions`, `compare_descriptions`
+- 22 tools total
+
+### v1.2.0
+- **Added compile features**: `get_compile_order`, `compile_manuscript` (PDF export via pdfkit)
+- Compile supports partial export with `stopAtTitle` parameter
+- Added synopsis tools: `read_synopsis`, `write_synopsis`
+
+### v1.1.3
+- **Fixed empty paragraph handling** - Empty lines no longer cause extra spacing in compiled output
+
+### v1.1.2
+- **Fixed RTF paragraph formatting** - Resolved issue where `\par\par` patterns caused section breaks in Scrivener compile
+
+### v1.0.1
+- **Fixed DraftFolder detection** - `create_document` now finds the manuscript root by type (`DraftFolder`) instead of requiring title to be "Draft" or "Manuscript"
+- **Fixed empty search query** - `search_content` with empty query now returns empty array
+- **Fixed empty rename validation** - `rename_document` rejects empty titles
+
+### v1.0.0
+- Initial release with 11 core tools
+- Custom RTF parser with formatting preservation
+- Support for bold, italic, em-dash, en-dash
+
+## Credits
+
+Developed by Dave Cilluffo / [TwelveTake Studios](https://twelvetake.com)
+
+Scrivener is a registered trademark of [Literature & Latte Ltd](https://www.literatureandlatte.com/).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};