{"id":"dc182410-d99d-45b9-ba77-471f79f85d42","slug":"bluewriter","kind":"mcp","name":"BlueWriter","summary":"Writing application with timeline canvas, encyclopedia allowing world building and easy movement of story parts in time. Your story can be published linearly or with flashbacks etc. while your writing","owner":"AltonLord","repoUrl":"https://github.com/AltonLord/BlueWriter","license":"GPL-3.0","licenseTier":"strong-copyleft","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-12-22T21:48:43.000Z","addedAt":"2026-10-21T16:32:02.501Z","logoUrl":"https://avatars.githubusercontent.com/u/40799908?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["design-media","writing","utilities"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T12:37:05.607Z","sample":false,"url":"https://conduits.dev/tools/bluewriter","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# BlueWriter\n\nA modern fiction writing application built with Python and Qt (PySide6), featuring AI assistant integration through the Model Context Protocol (MCP).\n\n![License](https://img.shields.io/badge/license-GPLv3-blue.svg)\n![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)\n![Tests](https://img.shields.io/badge/tests-197%20passing-brightgreen.svg)\n\n## Features\n\n- 📚 **Project Organization** - Manage multiple writing projects with stories and chapters\n- 🗒️ **Visual Canvas** - Arrange chapters as sticky notes on an infinite canvas\n- 📝 **Rich Text Editor** - Full-featured editor with formatting toolbar\n- 📖 **Encyclopedia** - World-building database for characters, locations, items, and more\n- 🤖 **AI Integration** - Control BlueWriter through Claude and other AI assistants via MCP\n- 💾 **Auto-Save** - Never lose your work with automatic saving\n\n## Screenshots\n\n*Coming soon*\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10 or higher\n- pip (Python package manager)\n\n### Setup\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/AltonLord/BlueWriter.git\ncd BlueWriter\n```\n\n2. Create a virtual environment:\n```bash\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n```\n\n3. Install dependencies:\n```bash\npip install -r requirements.txt\n```\n\n4. Run BlueWriter:\n```bash\npython main.py\n```\n\n## Usage\n\n### Basic Workflow\n\n1. **Create a Project** - Start by creating a new project for your novel or story collection\n2. **Add Stories** - Create one or more stories within your project\n3. **Write Chapters** - Add chapters as sticky notes on the canvas, then double-click to edit\n4. **Build Your World** - Use the Encyclopedia to track characters, locations, and lore\n5. **Publish** - Mark stories as complete when finished\n\n### Keyboard Shortcuts\n\n| Action | Shortcut |\n|--------|----------|\n| New Chapter | `Ctrl+N` |\n| Save | `Ctrl+S` |\n| Find/Replace | `Ctrl+F` |\n| Bold | `Ctrl+B` |\n| Italic | `Ctrl+I` |\n| Underline | `Ctrl+U` |\n\n## AI Integration (MCP)\n\nBlueWriter can be controlled by AI assistants like Claude through the Model Context Protocol.\n\n### Setup for Claude Desktop\n\n1. Ensure BlueWriter is installed and working\n2. Add to your Claude Desktop config (`~/.config/claude-desktop/config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"bluewriter\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"bluewriter_mcp.bluewriter_server\"],\n      \"cwd\": \"/path/to/BlueWriter\",\n      \"env\": {\n        \"PYTHONPATH\": \"/path/to/BlueWriter\"\n      }\n    }\n  }\n}\n```\n\n3. Restart Claude Desktop\n4. Launch BlueWriter (the app must be running for MCP to work)\n5. Ask Claude to interact with your projects!\n\n### Example Prompts\n\n- \"List my BlueWriter projects\"\n- \"Create a new chapter called 'The Discovery' in story 1\"\n- \"Show me all characters in my encyclopedia\"\n- \"Move chapter 3 to position 500, 200 on the canvas\"\n- \"Write an opening paragraph for chapter 1\"\n\n### Available Tools\n\nBlueWriter provides **46 MCP tools** in 6 categories:\n\n| Category | Tools | Examples |\n|----------|-------|----------|\n| Project | 6 | list, create, open, delete |\n| Story | 9 | create, publish, reorder |\n| Chapter | 13 | create, move, edit content |\n| Encyclopedia | 9 | create, search, categorize |\n| Canvas | 6 | pan, zoom, focus, fit |\n| State | 3 | get state, save all |\n\nSee [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) for complete documentation.\n\n## REST API\n\nBlueWriter exposes a REST API on `http://127.0.0.1:5000` when running.\n\n### Quick Reference\n\n```bash\n# List projects\ncurl http://127.0.0.1:5000/projects\n\n# Create a project\ncurl -X POST http://127.0.0.1:5000/projects \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"My Novel\"}'\n\n# Get chapter content\ncurl http://127.0.0.1:5000/chapters/1\n```\n\n### Documentation\n\n- **Swagger UI**: http://127.0.0.1:5000/docs\n- **ReDoc**: http://127.0.0.1:5000/redoc\n- **Full API Docs**: [docs/API.md](docs/API.md)\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests\npytest tests/ -v\n\n# Run with coverage\npytest tests/ --cov=services --cov=api --cov=events\n\n# Run specific test category\npytest tests/test_services/ -v\npytest tests/test_api/ -v\npytest tests/test_mcp/ -v\n```\n\n### Project Structure\n\n```\nBlueWriter/\n├── main.py                 # Application entry point\n├── views/                  # Qt UI components\n├── models/                 # Data models\n├── services/               # Business logic layer\n├── api/                    # REST API (FastAPI)\n├── events/                 # Event bus system\n├── adapters/               # Qt adapter for events\n├── bluewriter_mcp/         # MCP server\n├── database/               # SQLite database layer\n├── tests/                  # Test suite (197 tests)\n├── docs/                   # Documentation\n└── data/                   # User data (database, dictionaries)\n```\n\n### Architecture\n\n```\n┌─────────────────┐     ┌─────────────────┐\n│  MCP Server     │────▶│   REST API      │\n│  (Claude, etc.) │     │   (FastAPI)     │\n└─────────────────┘     └────────┬────────┘\n                                 │\n                        ┌────────▼────────┐\n                        │  Service Layer  │\n                        │  (Business Logic)│\n                        └────────┬────────┘\n                                 │\n              ┌──────────────────┼──────────────────┐\n              │                  │                  │\n     ┌────────▼────────┐ ┌──────▼──────┐ ┌────────▼────────┐\n     │   Event Bus     │ │  Database   │ │   Qt Adapter    │\n     │  (Pub/Sub)      │ │  (SQLite)   │ │  (UI Updates)   │\n     └─────────────────┘ └─────────────┘ └────────┬────────┘\n                                                  │\n                                         ┌────────▼────────┐\n                                         │    Qt UI        │\n                                         │  (PySide6)      │\n                                         └─────────────────┘\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [PySide6](https://www.qt.io/qt-for-python) (Qt for Python)\n- REST API powered by [FastAPI](https://fastapi.tiangolo.com/)\n- MCP integration using [mcp](https://modelcontextprotocol.io/)\n\n## Support\n\nIf you encounter any issues or have questions:\n\n1. Check the [documentation](docs/)\n2. Search existing [issues](https://github.com/AltonLord/BlueWriter/issues)\n3. Open a new issue if needed\n\n---\n\nMade with ❤️ for writers who want AI assistance in their creative process.\n"}