Content
StoryWeave
A modern novel outline management tool that helps authors plan and manage their novel's volume, act, and scene structure in a visual flowchart. It also provides MCP services and AI Agent, allowing users to automatically generate structured outlines based on inspiration. **AI creation and manual editing are combined**, seamlessly switching in the same editor.
## Features
### Book Management
- Card-based bookshelf display, at a glance
- Create a new novel, support custom cover image upload
- Secondary confirmation when deleting a book, preventing misoperation
- Automatically sort by last modification time
- Data persistence stored in server-side JSON files
### Outline Flowchart Editing
- Three-layer node structure: **Volume → Act → Scene**, clearly presenting the story architecture
- Visual drag-and-drop canvas, freely arrange node positions
- Node connection rules: Volume can only connect to Act, Act can only connect to Scene
- One-click automatic arrangement (based on dagre algorithm), quickly organize the layout
- Side editing panel, real-time editing node properties
- Secondary confirmation pop-up when deleting nodes
- Canvas zooming, panning, and mini-map navigation
- Automatic saving, editing and saving in real-time
### Assistant (Integrated)
- ****: AI chat panel directly embedded in the editor, no need to switch applications
- **Four-stage workflow**: Inspiration analysis → Create a book → Build an Verify and optimize
- **SSE Streaming Output**: Real-time display-generated content, tool calls visible
- **GLM-5 Large**: Access through Anthropic compatible protocol
- **MCP Protocol Integration**: Agent automatically calls MCP Tools to complete outline creation
- **Quick Inspiration Templates**: Three-act structure/Hero's Journey/Free Inspiration one-click launch
- **Multi-round Dialogue**: Support setting adjustments, outline modifications, and other interactive creations
- **Dialogue Persistence**: Based on IndexedDB (Dexie) storage conversation history by book, automatically restored after refresh/restart
- **Markdown Rendering**: AI replies fully support Markdown format (headings, lists, code blocks, tables, quotes, etc.)
- **One-click Switching**: Click the ✨ button to open/close the AI panel, freely switch between manual editing and AI creation
### MCP Service (for AI Agent)
- **14 MCP Tools**: Complete book and node CRUD operations, including batch creation of outlines
- **6 MCP Resources**: Expose book lists, outline data, structure templates other resources
- **4 MCP Prompts**: Outline analysis, scene story synopsis generation, inspiration to outline
- **HTTP API Server**: RESTful interface for UI frontend calls
- **Shared Data Layer**: MCP service and UI frontend operate on the same data source, Agent-created outlines are real-time visible in the UI
### Node Types
| Type | Icon | Color Identifier | Properties |
|------|------|---------------|------------|
| 📚 | Amber | Title, volume number, transformation before and after, volume summary |
| Act | 🎭 | Purple | Title, act number (1/2/3), belonging volume, transformation before and after, core conflict |
| Scene | 🎬 | Cyan | Title, belonging act, transformation before and after, location, character list |
## Tech Stack
### Frontend
- **Vue 3** — Composition APIscript setup>` + TypeScript
- **Vue Flow** — Visualize and interact with flowcharts
- **Dagre** — Automatic layout algorithm
- **Dexie**DB encapsulation, conversation history persistence
- **Marked** parsing and rendering
- **Lucide Vue Next** — Icon library
- **Tailwind CSS 4** — Atomic styling
- **Vite** — Build tool
### MCP Server
- **Node.js** — Runtime
- **TypeScript** — Type safety
- **@modelcontextprotocol/sdk** — MCP protocol SDK
- **Express** — HTTP API server
- **Zod** — Parameter validation
### AI Agent
- **Python 3.12+** — Runtime
- **FastAPI** — Agent HTTP API service (SSE streaming push)
- **Uvicorn** — ASGI server
- **LangChain** — LLM application framework
- **LangGraph** — ReAct Agent construction
- **langchain-anthropic** — Anthropic protocol adaptation (access GLM-5)
- **langchain-mcp-adapters** — MCP protocol adaptation
## Project Structure
```
story-weave/
├── src/ # Frontend source code
│ ├── App.vue # Main application component (bookshelf/editor view switching + AI panel)
│ ├── main.ts # Entry file
│ ├── style.css # Global styles and CSS variables
│ ├── components/
│ │ ├── BookshelfView.vue # Bookshelf page
│ │ ├── NovelCard.vue # Book card component
│ │ ├── CreateNovelModal.vue # New novel popup
│ │ ├── ConfirmModal.vue # Confirmation popup (delete and other operations)
│ │ ├── PlotNode.vue # Flowchart node component (volume/act/scene)
│ │ ├── EditorPanel.vue # Node editing side panel
│ │ └── AiPanel.vue # AI creation assistant chat panel
│ ├── composables/
│ │ ├── useNovels.ts # Book data management composable
│ │ └── useAiChat.ts # AI conversation state management + Dexie persistence
│ └── services/
│ ├── tauri.ts # Data persistence service (HTTP API implementation)
│ └── agent.ts # AI Agent SSE streaming communication service
├── mcp-server/ # MCP server
│ ├── src/
│ │ ├── index.ts # MCP Server entry (stdio transmission)
│ │ ├── api-server.ts # HTTP API server (for UI calls)
│ │ ├── storage.ts # Data storage layer (JSON file read/write)
│ │ ├── tools.ts # MCP Tools definition
│ │ ├── resources.ts # MCP Resources definition
│ │ └── prompts.ts # MCP Prompts definition
│ ├── dist/ # Compilation output
│ ├── package.json
│ └── tsconfig.json
├── agent/ # AI Agent
│ ├── __init__.py # Package initialization
│ ├── config.py # LLM configuration, MCP connection configuration, system prompts
│ ├── agent.py # Agent core logic (LangChain + MCP + LangGraph)
│ ├── server.py # FastAPI server (SSE streaming push + REST API)
│ └── requirements.txt # Python dependencies
├── .mcp.json # MCP service configuration
├── vite.config.ts # Vite configuration (including API proxy)
└── package.json
```
## Quick Start
### Environment Requirements
- Node.js >= 18
- npm >= 9
- Python >= 3.12
### Install Dependencies
```bash
# Install frontend dependencies
npm install
# Install MCP server dependencies
cd mcp-server
npm install
cd ..
# Install AI Agent dependencies
pip install -r agent/requirements.txt
```
### Start Development Environment
Three services need to be started (run in three terminals respectively):
```bash
# Terminal 1: Start MCP HTTP API server (data layer)
cd mcp-server
npm run api
# Terminal 2: Start AI Agent FastAPI service
python -m agent.server
# Terminal 3: Start frontend development server
npm run dev
```
> **Windows PowerShell Note**: PowerShell 5.x does not support `&&` syntax, please split `cd xxx && command` into two lines and execute separately, or upgrade to PowerShell 7+. The above example uses a separate line, which can be used directly.
The frontend development server will automatically proxy requests to the corresponding backend:
- `/api/agent/*` → `http://localhost:8000` (AI Agent service)
- `/api/*` → `http://localhost:3001` (MCP HTTP API service)
### Build Production Version
```bash
# Build frontend
npm run build
# Build MCP server mcp-server
npm run build
```
## MCP Service Details
### Architecture
```
┌─────────────────────────────────────────────────────────────────────────┐
│ StoryWeave │
│ │
│ ┌────────────── MCP/stdio ┌──────────────┐ │
│ │ AI Agent │ ◄─────────────► │ MCP Server │ │
│ │ (Python) │ │ (Node.js) │ │
│ │ LangChain │ │ Tools × 14 │ │
│ │ LangGraph │ │ Resources×6 │ │
│ │ FastAPI │ │ Prompts × 4 │ │
│ └──────┬───────┘ └──────┬────── │
│ │ SSE streaming push │ │
│ │ │ JSON file read/write │
│ ┌───────┐ REST API ┌──────┴───────┐ │
│ Vue Frontend │ ◄─────────────► │ HTTP API │ │
│ │ (Vite) │ │ Server │ │
│ AiPanel │ │ │ │
│ └──────────────┘ └────────────── │
│ │
│ Shared Data Storage (JSON) │
└─────────────────────────────────────────────────────────────────────────┘
```
MCP Server and HTTP API Server share the same data storage layer, ensuring that Agent and UI operate on the same data. provides SSE streaming interface through FastAPI, and the Vue frontend's AiPanel component directly consumes this interface to achieve a unified.
### MCP Tools (14)
#### Book Management
| Tool Name | Description |
|--------|------|
create_book` | Create a new novel |
| `` | List all novels |
| `get_book` | Get the details of a specified novel |
| `update_book` | Update novel metadata |
| `delete_book` a novel and its outline data |
#### Node Operations
| Tool Name | Description |
|--------|------|
| `` | Add avolume/act/sc can automatically connect lines `list_nodes` |, can filter by| `update_node Update node properties |
delete_node` | node and its associated connections |
| `connect_nodes` two nodes |
| `disconnect_nodes` | Disconnect node connections |
#### Outline Operations
| Tool Name | Description |
|--------|------|
| `get_outline` | Get the outline tree structure (volume → scene level) |
| `validate_outline` | integrity and consistency |
| `batch_create_outline` create a complete outlinemost efficient way) |
### MCP Resources (6)
| Description |
|-----|------|
| `storyweave://books` | All book lists |
| `storyweave://books/{bookId}` | Specified book details |
| `storyweave://books/{bookId}/outline` | Original outline data (nodes + edges) |
| `storyweave://books/{bookId}/tree` | Outline tree structure |
| `storyweave://templates/three-act` | Three-act structure template |
| `storyweave://templates/hero-journey` | Hero's Journey template |
### MCP Prompts (4)
| Prompt Name | Description |
|--------|------|
| `analyze_plot` | Analyze the outline structure, find weaknesses, and provide improvement suggestions |
| `suggest_scenes` | Based on the existing act structure, suggest supplementing missing scenes |
| `generate_synopsis` | Generate a story synopsis based on the outline |
| `create_outline_from_idea` | Create a complete novel outline from inspiration description |
### Client
Add the following configuration in an MCP-supported client (such as Claude Desktop, Cursor, etc.):
```json
{
"mcpServers": {
"storyweave": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "/path/to/story-weave/mcp-server",
env": {
"STORYWEAVE_DATA_DIR": "/path/to/story-weave/data"
}
}
}
}
```
### HTTP API Interface
The API server runs on `http://localhost:3001` by default, and the port can be modified through the environment variable `STORYWEAVE_API_PORT`.
| Method | Path |
|------|------|------|
| GET | `/` | Get book list |
| POST | `/` | Create a new novel |
| GET | `/api/books/:bookId Get book details |
| PUT | `/api/books/:bookId` | Update book information |
| DELETE | `/api/books/:bookId` | Delete a book |
| GET | `/api/books/:bookId/outline` | Get outline data |
| PUT | `/api/books/:bookId/outline` | Save outline data |
| GET | `/api/books/:bookId/outline/tree` | Get outline tree structure |
| GET | `/api/books/:bookId/outline/validate` | Verify outline integrity |
| POST | `/api/books/:bookId/nodes` | Add nodes |
| PUTapi/books/:bookId/nodes/:nodeId` | Update nodes |
| DELETE | `/api/books/:bookId/nodes/:nodeId` | Delete nodes |
| POST | `/apibookId/edges Connect nodes |
| DELETE | `/api/books/:bookId/edges` | Disconnect node connections |
| GET | `/api/health` | Health check |
### Agent API Interface
The Agent FastAPI service runs on `http://localhost:8000` by default, and the port can be modified through the environment variable `AGENT_PORT`.
| Method | Path | Description |
------|------|
| `/api/agent/health` | Health check |
| POST | `/api/agent/chat` | Synchronous chat (returns complete response) |
| POST | `/api/agent/chat/stream` | SSE streaming chat (real-time push text and tool call events) |
## AI Agent Details
### Work Flow
The Agent adopts a four-stage workflow, executed strictly in order:
```
User Inspiration
│
▼
┌──────────────────────────────┐
│ Stage 1: Inspiration Analysis │ No tool calls
│ Output: Core premise, worldview, │
│ characters, themes, recommended │
│ structure │
└──────────┬───────────────────┘
│ User confirmation
▼
┌──────────────────────────────┐
│ Stage 2: Create Book + Read │ MCP Tools: create_book
│ Template │ MCP Resource: templates/*
└──────────┬───────────────────┘
│
▼
┌──────────────────────────────┐
│ Stage 3: Batch Build Outline │ MCP Tool: batch_create_outline
│ Output: Complete volume → act │
│ → scene tree │
└──────────┬───────────────────┘
│
▼
┌──────────────────────────────┐
│ Stage 4: Verification and │ MCP Tools: validate_outline
│ Optimization │ MCP Tools: get_outline, update_node
│ Output: Final outline summary │
└──────────────────────────────┘
```
### Module Description
| File | Responsibility |
|------|------|
| `agent/config.py` | GLM-5 model configuration, MCP Server connection configuration, system prompts (four-stage workflow) |
| `agent/agent.py` | `StoryWeaveAgent` class: MCP client management, Agent creation, streaming output, tool call visualization |
| `agent/server.py` | FastAPI server: SSE streaming push, REST API, CORS support, Agent lifecycle management |
### Model Configuration
| Configuration Item | Value |
|--------|-----|
| Model | GLM-5 (`astron-code-latest`) |
| API Endpoint | `https://maas-coding-api.cn-huabei-1.xf-yun.com/anthropic` |
| Protocol | Anthropic compatible |
| Access Method | `langchain-anthropic` → `ChatAnthropic` |
### Outline Quality Standards
The outline generated by the Agent must meet the following standards:
- Each volume contains 3 acts (act_number is 1, 2, or 3)
- The first act has at least 3 scenes, the second act has at least 4 scenes, and the third act has at least 3 scenes
- Each scene must have a clear `change_before` and `change_after` to form a transformation arc
- Conflicts between acts must escalate
- Key characters appear reasonably in each scene and cannot disappear out of thin air
- Scene locations must be specific and cannot use vague descriptions
### Custom Model
To switch to another model, modify the configuration in `agent/config.py`:
```python
# Switch to OpenAI
GLM_MODEL_ID = "gpt-4o"
GLM_ANTHROPIC_URL = "https://api.openai.com/v1"
# Switch to another Anthropic-compatible endpoint
GLM_MODEL_ID = "your-model-id"
GLM_ANTHROPIC_URL = "https://your-api-endpoint/anthropic"
```
Also, replace `ChatAnthropic` with the corresponding LangChain Chat class in `agent/agent.py`.
## User Guide
### Create a Novel
1. Click the "Create Novel" button on the bookshelf page
2. Enter the novel name and optionally upload a cover image
3. Click to confirm creation
### Edit Outline
1. Click any book card on the bookshelf page to enter the editor
2. Use the left toolbar to add volume, act, and scene nodes
3. Drag from the node bottom connection point to the top of another node to establish a hierarchical relationship
4. Click the node to open the right editing panel and modify node properties
5. Click "Auto Arrange" to organize the layout with one click
### Use AI Creation Assistant
1. Click the ✨ button in the top right corner of the editor page to open the AI panel
2. Enter your novel inspiration in the chat box or click the quick inspiration template
3. The Agent will generate novel settings (worldview, characters, themes), and after confirmation, automatically create an outline
4. The outline created by AI will be written to the data layer through the MCP service, and refresh the editor to see the flowchart display
5. You can continue to dialogue in the AI panel to adjust the outline content
6. Click the ✨ button to close the AI panel and return to manual editing mode
### Edit Node Properties
- **Volume**: Set title, volume number, transformation before and after, volume summary
- **Act**: Set title, act number, belonging volume, transformation before and after, core conflict
- **Scene**: Set title, belonging act, transformation before and after, location, characters (add with Enter)
### Delete Node
- Click the "Delete Node" button in the editing panel
- Or select the node and press Delete / Backspace
- A confirmation popup will appear, and confirm to delete
### Use MCP Client to Generate Outline
1. Start the API server and MCP service
2. Configure the StoryWeave service in the MCP client
3. Describe your novel inspiration to the Agent
4. The Agent will call the `create_outline_from_idea` prompt template to automatically create a complete volume → act → scene outline
5. Open the corresponding book in the UI to see the flowchart display of the outline
## Design Specifications
### Color Scheme
| Purpose | Color Value | Description |
|------|------|------|
| Main Color | `#4f46e5` | Buttons, selected state, emphasized elements |
| Main Color Hover | `#4338ca` | Button hover state |
| Background | `#f5f5f7` | Page background |
| Card | `#ffffff` | Card, panel background |
| Volume Identifier | `#f59e0b` | Amber |
| Act Identifier | `#8b5cf6` | Purple |
| Scene Identifier | `#06b6d4` | Cyan |
| Dangerous Operation | `#ef4444` | Delete button, error prompt |
### Interaction Specifications
- Unified rounded corners: 12px
- Transition animation: 0.2s ease
- Deletion operations require secondary confirmation
- Form focus displays main color border and light halo
