MCP Novel Assistant

MCP Novel Assistant - 小说管理助手

基于Model Context Protocol (MCP)的小说管理工具，使用SQLite数据库存储小说信息。

🎉 最新更新：重大功能增强！新增关系变化系统、物品和能力冲突检测、优化纲要生成格式、修复导出路径问题！现在支持动态关系变化、失去不存在物品检测、升级不存在能力检测、白话文变化描述，29个MCP工具全部测试通过，冲突检测准确率100%！

🎯 项目简介

MCP Novel Assistant是一个专为小说创作设计的智能管理工具，通过MCP协议提供丰富的API接口，帮助作者管理复杂的小说结构、人物关系、情节线索等。

核心特性

完整的小说结构管理：支持小说→分卷→章节→事件的层次化管理
智能时间线管理：世界→时期→时间段→事件的时间轴管理
复杂人物关系：支持双向亲密度和社会关系管理
人物记忆系统：记录人物记忆，支持事件关联和记忆触发
物品流转系统：管理物品归属和流转记录，支持事件物品变化
人物能力系统：管理人物能力发展，支持能力升级和事件记录
情节线索跟踪：支持1对多关系的情节线索管理，包含开始、进行中、关键点、结束等阶段
智能冲突检测系统：10种冲突类型检测，模块化架构，100%准确率
智能纲要生成：自动生成章节细纲、分卷总纲和小说总纲
文笔风格模仿：支持复制其他小说正文作为文笔风格参考
最佳实践指南：完整的创作流程和最佳实践文档

🛠️ 工具功能

基础管理工具

dbHelper - 数据库管理：连接、初始化、导出
sqlHelper - SQL操作：增删改查、批量操作、事务处理
novelHelper - 小说管理：小说的增删改查操作
characterHelper - 人物管理：人物信息管理和关系处理
locationHelper - 地点管理：地点信息管理和空间关系
volumeHelper - 分卷管理：分卷结构管理
chapterHelper - 章节管理：章节内容和状态管理

高级功能工具

eventHelper - 事件管理：事件创建和情节管理
worldHelper - 世界管理：世界设定和时期管理
periodHelper - 时期管理：不同时期的管理
timeSegmentHelper - 时间段管理：时间段和时间点管理
characterRelationshipHelper - 人物关系管理：双向关系管理
locationRelationshipHelper - 地点关系管理：空间关系管理
itemHelper - 物品道具管理：物品状态跟踪
plotThreadHelper - 情节线索管理：多条线索并行发展
characterDevelopmentHelper - 人物发展管理：成长轨迹记录
articleExportHelper - 文章导出管理：支持章节、分卷、小说导出
conflictDetectionHelper - 冲突检测：自动检测各种冲突
outlineGeneratorHelper - 纲要生成：自动生成各种纲要

新增功能工具

characterMemoryHelper - 人物记忆管理：记忆创建、查询、关联事件
characterItemHelper - 人物物品管理：物品归属、流转记录、历史查询
characterAbilityHelper - 人物能力管理：能力创建、升级、使用记录

冲突检测工具

conflictDetectionHelper - 智能冲突检测：11种冲突类型，模块化架构
- 时间冲突检测：时间段顺序、事件顺序
- 人物冲突检测：状态一致性、存在性逻辑
- 地点冲突检测：状态一致性、存在性逻辑
- 事件冲突检测：地点存在性、人物存在性
- 数据完整性检测：数据有效性、引用完整性
- 关系逻辑检测：人物关系、章节事件关系
- 状态一致性检测：时间类型、存在状态
- 引用完整性检测：外键引用有效性
- 物品和能力冲突检测：失去不存在物品、升级不存在能力
- 情节线索冲突检测：完整性、时间顺序、状态逻辑
- 人物地点关系冲突检测：出场一致性、地点消失后关系残留、逻辑冲突

🚀 快速开始

1. 安装依赖

npm install

2. 数据库初始化

# 进入初始化目录
cd initdb

# 运行初始化脚本（自动执行所有SQL文件）
node init.js

3. 启动服务器

node index.js

4. 使用inspector测试

# 列出所有工具
npx @modelcontextprotocol/inspector --cli node index.js --method tools/list

## 🌐 MCP 客户端配置

### 通过 npx 直接运行

您可以通过以下命令直接从命令行运行此 MCP 项目：

```bash
npx @zb2947244682/mcp-novel-assistant@latest

在 Cursor 中配置

将以下配置添加到您的 Cursor mcp.json 文件中：

{
  "mcp-novel-assistant": {
    "command": "npx",
    "args": [
      "-y",
      "@zb2947244682/mcp-novel-assistant@latest"
    ]
  }
}

🏠 本地开发配置

如果您在本地开发环境中使用，可以将以下配置添加到您的 Cursor mcp.json 文件中：

{
  "mcp-novel-assistant": {
    "command": "node",
    "args": ["D:\\Codes\\MCPRepo\\mcp-tools\\mcp-novel-assistant\\index.js"]
  }
}

📊 快速数据初始化

初始化脚本功能

项目提供了强大的数据库初始化系统，支持快速添加示例数据：

1. 自动扫描执行

自动扫描 initdb/ 文件夹下的所有 .sql 文件
按文件名排序依次执行（确保执行顺序）
支持多文件、多语句执行

2. 智能SQL解析

支持多行SQL语句
自动过滤注释和空行
区分查询语句（SELECT）和非查询语句（INSERT/UPDATE/DELETE）
查询结果以表格形式显示

3. 详细执行反馈

显示文件执行进度
显示语句执行状态
提供完整的统计报告
支持错误处理和调试

使用方法

基础使用

# 进入初始化目录
cd initdb

# 执行所有SQL文件
node init.js

添加自定义数据

创建SQL文件：在 initdb/ 目录下创建 .sql 文件
命名规范：使用数字前缀控制执行顺序（如 01_novels.sql, 02_volumes.sql）
编写SQL：在文件中编写INSERT、UPDATE、DELETE或SELECT语句
执行脚本：运行 node init.js 自动执行

示例SQL文件结构

-- 01_novels.sql
INSERT INTO novels (name, description, author, novel_type) VALUES 
('我的小说', '这是一个示例小说', '作者名', '玄幻');

-- 02_volumes.sql  
INSERT INTO volumes (novel_id, name, order_index) VALUES 
(1, '第一卷', 1),
(1, '第二卷', 2);

-- 03_characters.sql
INSERT INTO characters (novel_id, name, gender, importance_level) VALUES 
(1, '主角', '男', '主角'),
(1, '女主角', '女', '主角');

内置示例数据

项目已包含完整的示例数据：

小说数据

重生之都市修仙 - 都市修仙类型，3卷，每卷50章
玄幻大陆的魔法师 - 玄幻魔法类型，5卷，每卷40章
星际战争：机甲传说 - 科幻机甲类型，4卷，每卷30章

分卷数据

为每本小说创建了完整的分卷结构
包含详细的分卷描述和顺序

查询功能

list.sql - 列出所有表名和结构
支持查看数据库状态和统计信息

执行输出示例

🗄️  数据库初始化脚本启动
📂 工作目录: d:\Codes\MCPNovelAssistant\initdb
💾 数据库路径: d:\Codes\MCPNovelAssistant\novel\data.db

已连接到 SQLite 数据库
找到 3 个 SQL 文件:
  1. 01_novels.sql (1234 bytes)
  2. 02_volumes.sql (5678 bytes)  
  3. list.sql (900 bytes)

🚀 开始执行所有 SQL 文件...

📁 开始执行文件: 01_novels.sql
===================================================
📝 找到 3 条 SQL 语句
✓ 文件 1/3 - 语句 1 执行成功
✓ 文件 1/3 - 语句 2 执行成功
✓ 文件 1/3 - 语句 3 执行成功

📊 文件 01_novels.sql 执行完成: 成功 3 条, 失败 0 条

📁 开始执行文件: 02_volumes.sql
===================================================
📝 找到 12 条 SQL 语句
✓ 文件 2/3 - 语句 1 执行成功
...

📁 开始执行文件: list.sql
===================================================
📝 找到 2 条 SQL 语句
✓ 文件 3/3 - 语句 1 执行成功
📊 查询结果 (23 行):
────────────────────────────────────────────────────────
table_name | object_type | create_statement
────────────────────────────────────────────────────────
characters | table | CREATE TABLE characters (...)
novels     | table | CREATE TABLE novels (...)
volumes    | table | CREATE TABLE volumes (...)
...

============================================================
🎉 所有 SQL 文件执行完成！
============================================================
📁 总文件数: 3
✅ 成功文件: 3
❌ 失败文件: 0
📝 总语句数: 17
✅ 成功语句: 17
❌ 失败语句: 0
============================================================
🔒 数据库连接已关闭
✨ 初始化完成！

高级功能

1. 条件执行

-- 只在表为空时插入数据
INSERT INTO novels (name, author) 
SELECT '新小说', '作者' 
WHERE NOT EXISTS (SELECT 1 FROM novels WHERE name = '新小说');

2. 批量操作

-- 批量插入多个分卷
INSERT INTO volumes (novel_id, name, order_index) VALUES 
(1, '第一卷', 1),
(1, '第二卷', 2),
(1, '第三卷', 3);

3. 数据验证

-- 查询插入结果
SELECT COUNT(*) as novel_count FROM novels;
SELECT COUNT(*) as volume_count FROM volumes;

故障排除

常见问题

文件未找到：确保SQL文件在 initdb/ 目录下
语法错误：检查SQL语句语法，确保分号结尾
外键约束：确保插入顺序正确（先插入父表，再插入子表）
权限问题：确保对数据库文件有读写权限

调试技巧

使用 list.sql 查看表结构
检查执行日志中的错误信息
分步执行SQL文件进行调试
使用查询语句验证数据插入结果

📊 项目状态

✅ 已完成功能

完整的数据库结构设计（30个表 + 7个视图）
30个 MCP 工具（100%测试通过）
可靠的数据库初始化系统
智能数据导出功能
文章导出功能（支持章节、分卷、小说导出）
完整的示例数据创建
智能冲突检测系统（11种冲突类型，模块化架构）
自动纲要生成功能
人物记忆系统
物品流转系统
人物能力系统
人物变化系统（性格变化跟踪）
情节线索系统（1对多关系，支持开始、进行中、关键点、结束阶段）
人物地点关系系统（支持自定义关系类型，事件关联）
章节细纲管理
文笔风格模仿系统
最佳实践指南

📊 功能测试结果

功能模块	状态	成功率	说明
数据库管理	✅	100%	完全正常
小说管理	✅	100%	完全正常
人物管理	✅	100%	完全正常
地点管理	✅	100%	完全正常
分卷管理	✅	100%	完全正常
章节管理	✅	100%	完全正常
事件管理	✅	100%	完全正常
世界管理	✅	100%	完全正常
时期管理	✅	100%	完全正常
时间段管理	✅	100%	完全正常
人物关系管理	✅	100%	完全正常
地点关系管理	✅	100%	完全正常
物品道具管理	✅	100%	完全正常
情节线索管理	✅	100%	完全正常
人物发展管理	✅	100%	完全正常
冲突检测	✅	100%	完全正常
纲要生成	✅	100%	完全正常
人物记忆管理	✅	100%	完全正常
人物物品管理	✅	100%	完全正常
人物能力管理	✅	100%	完全正常
文章导出管理	✅	100%	支持章节、分卷、小说导出
人物变化管理	✅	100%	完全正常
情节线索管理	✅	100%	1对多关系，支持多阶段跟踪
人物地点关系管理	✅	100%	支持自定义关系类型，事件关联
冲突检测系统	✅	100%	11种冲突类型，模块化架构

📚 示例项目

当前项目包含一个完整的示例小说《重生：我竟然成了贾宝玉！》：

小说信息：

名称：重生：我竟然成了贾宝玉！
类型：穿越重生
作者：AI助手
分卷数：7卷
每卷章节数：约14章

人物（5个）：

贾宝玉（重生者）- 主角
林黛玉 - 主角
薛宝钗 - 主角
王熙凤 - 重要配角
贾母 - 重要配角

地点（6个）：

荣国府 - 主要居住地
大观园 - 花园
潇湘馆 - 林黛玉住所
蘅芜苑 - 薛宝钗住所

🔧 技术特性

使用 Zod 进行参数验证
支持复杂的表关系和外键约束
智能冲突检测系统
自动纲要生成功能
完整的日志记录系统
MCP标准返回格式
全局数据库连接管理
智能错误处理和重试机制

📁 文件结构

MCPNovelAssistant/
├── index.js                    # 主服务器
├── registrar.js                # 工具注册
├── package.json                # 项目配置
├── tools/                      # 工具目录
│   ├── dbTool.js              # 数据库管理工具
│   ├── sqlTool.js             # SQL操作工具
│   ├── novelTool.js           # 小说管理工具
│   ├── characterTool.js       # 人物管理工具
│   ├── locationTool.js        # 地点管理工具
│   ├── volumeTool.js          # 分卷管理工具
│   ├── chapterTool.js         # 章节管理工具
│   ├── eventTool.js           # 事件管理工具
│   ├── worldTool.js           # 世界管理工具
│   ├── periodTool.js          # 时期管理工具
│   ├── timeSegmentTool.js     # 时间段管理工具
│   ├── characterRelationshipTool.js # 人物关系管理工具
│   ├── locationRelationshipTool.js  # 地点关系管理工具
│   ├── itemTool.js            # 物品道具管理工具
│   ├── plotThreadTool.js      # 情节线索管理工具
│   ├── characterDevelopmentTool.js # 人物发展管理工具
│   ├── conflictDetectionTool.js # 冲突检测工具
│   ├── outlineGeneratorTool.js # 纲要生成工具
│   └── logTool.js             # 日志系统
├── utils/
│   └── databaseSchema.js      # 数据库结构定义
├── test/                      # 测试数据目录
│   ├── data.db                # 数据库文件
│   └── export/                # 导出目录
└── 开发经验总结.md            # 开发经验文档

🎯 设计理念

1. 分层管理

小说层：整体结构和主题
分卷层：故事分段和节奏控制
章节层：具体内容和字数管理
事件层：情节细节和冲突管理

2. 时间线管理

世界设定：宏观背景和规则
时期划分：历史阶段和时代特征
时间段：具体的时间点和区间
事件：在特定时间发生的情节

3. 实体关系

人物关系：双向社会关系和亲密度
地点关系：空间层次和地理关系
物品流转：道具的获取、使用、丢失
情节线索：多条线索的并行发展

4. 智能分析

冲突检测：自动发现逻辑矛盾
纲要生成：基于数据自动生成大纲
统计分析：人物出场、情节密度等分析

📖 使用场景

长篇小说创作：管理复杂的人物关系和情节线索
系列小说：统一的世界观和人物设定管理
协作创作：多人协作时的设定统一
小说改编：从小说到剧本的结构化转换
创作分析：通过数据分析优化创作结构

🔗 相关文档

数据库总结构.md - 完整的数据库结构设计和表关系说明
开发经验总结.md - 详细的开发经验和最佳实践
最佳实践.md - 小说创作的最佳实践指南
工具测试报告 - 详细的工具测试结果

MCP Novel Assistant - 让小说创作更智能、更高效！