# Novel

**Repository Path**: Git_Anything/Novel

## Basic Information

- **Project Name**: Novel
- **Description**: AI小说仓库
- **Primary Language**: C#
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-21
- **Last Updated**: 2026-04-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Novel MCP Server

AI 辅助小说创作的 MCP (Model Context Protocol) 服务器，支持项目管理、角色设定、知识图谱、伏笔追踪等功能。

## 功能特性

### 🎯 核心功能
- **项目管理**：创建、管理小说项目
- **卡片系统**：19种卡片类型（角色、场景、章节、物品、概念等）
- **知识图谱**：实体关系管理（同盟、敌对、亲属等）
- **伏笔追踪**：伏笔的埋设与解决
- **角色记忆**：动态角色状态管理
- **上下文组装**：为 AI 写作提供完整上下文

### 🛠️ MCP 集成
- 21 个 MCP 工具
- 4 个 MCP 资源
- 5 个写作提示词

## 快速开始

### 1. 安装依赖

```bash
cd d:\AI_WorkFlow\Novel
pip install -e .
```

### 2. Claude Desktop 配置

找到 Claude Desktop 配置文件：
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

添加配置：
```json
{
  "mcpServers": {
    "novel-mcp": {
      "command": "python",
      "args": ["-m", "novel_mcp.server"],
      "cwd": "D:\\AI_WorkFlow\\Novel"
    }
  }
}
```

重启 Claude Desktop 使配置生效。

## 使用指南

### 基础工作流

1. **创建项目**
   ```
   请使用 create_project 创建项目：
   - 名称：我的科幻小说
   - 描述：关于时间循环的科幻故事
   ```

2. **创建角色**
   ```
   请使用 create_card 创建角色：
   - 项目ID：1
   - 标题：主角李明
   - 模型名称：CharacterCard
   - 内容：包含姓名、年龄、职业、性格等
   ```

3. **建立关系**
   ```
   请使用 upsert_relation 建立关系：
   - 项目ID：1
   - 源角色：李明
   - 目标角色：王芳
   - 关系类型：同盟
   ```

4. **埋设伏笔**
   ```
   请使用 plant_foreshadow 添加伏笔：
   - 项目ID：1
   - 标题：神秘符号出现
   - 备注：第1章的关键悬念
   ```

5. **添加记忆**
   ```
   请使用 add_memory 添加记忆：
   - 项目ID：1
   - 角色名：李明
   - 分类：emotional_state
   - 信息：对第一次进入实验室的紧张感
   ```

6. **组装上下文**
   ```
   请使用 assemble_context 组装上下文：
   - 项目ID：1
   - 参与角色：["李明", "王芳"]
   - 包含关系、记忆、卡片：是
   ```

7. **生成内容**
   ```
   请使用 write_chapter 提示词生成章节内容
   ```

### 可用工具

#### 项目管理
- `create_project` - 创建新项目
- `list_projects` - 列出所有项目
- `get_project` - 获取项目详情
- `update_project` - 更新项目信息

#### 卡片管理
- `create_card` - 创建卡片
- `list_cards` - 列出卡片
- `get_card` - 获取卡片详情
- `update_card` - 更新卡片内容
- `delete_card` - 删除卡片

#### 知识图谱
- `upsert_relation` - 建立或更新关系
- `list_relations` - 列出关系
- `get_entity_subgraph` - 获取关系子图
- `delete_relation` - 删除关系

#### 追踪系统
- `plant_foreshadow` - 埋下伏笔
- `resolve_foreshadow` - 解决伏笔
- `list_foreshadows` - 列出伏笔
- `add_memory` - 添加角色记忆
- `get_character_state` - 获取角色状态
- `list_memories` - 列出记忆

#### 上下文工具
- `assemble_context` - 组装写作上下文

#### 提示词
- `generate_outline` - 生成故事大纲
- `write_chapter` - 写章节内容
- `review_chapter` - 审查章节质量
- `extract_relations_from_text` - 从文本提取关系
- `extract_character_dynamics` - 提取角色动态

### 可用资源

- `novel://projects` - 列出所有项目
- `novel://projects/{id}` - 查看特定项目
- `novel://cards/{id}` - 查看特定卡片
- `novel://card-types` - 查看所有卡片类型

## 技术架构

### 数据模型
- **Project**: 项目表
- **CardType**: 卡片类型表
- **Card**: 卡片表
- **KGRelation**: 知识图谱关系表
- **ForeshadowItem**: 伏笔表
- **CharacterMemory**: 角色记忆表

### 卡片类型
1. **角色卡** (CharacterCard) - 角色设定
2. **场景卡** (SceneCard) - 场景描述
3. **章节** (Chapter) - 章节内容
4. **标签** (Tags) - 项目标签
5. **世界观** (WorldBuilding) - 世界观设定
6. **概念卡** (ConceptCard) - 核心概念
7. **物品卡** (ItemCard) - 重要物品
8. **组织卡** (OrganizationCard) - 组织设定
9. **其他** - 大纲、设定、指南等

### 关系类型
- 同盟 ↔ ally
- 敌对 ↔ enemy
- 亲属 ↔ family
- 师徒 ↔ mentor
- 伙伴 ↔ partner
- 上级 ↔ superior
- 隶属 ↔ affiliated
- 控制 ↔ controller
- 影响 ↔ influence
- 其他 ↔ other

## 开发与测试

### 运行测试
```bash
python -m pytest tests/ -v
```

### 启动服务器
```bash
python -m novel_mcp.server
```

## 项目结构

```
src/novel_mcp/
├── models/          # SQLModel 数据模型
├── schemas/         # Pydantic Schema
├── services/        # 业务逻辑层
├── tools/           # MCP 工具
├── resources.py     # MCP 资源
├── prompts.py       # MCP 提示词
├── server.py        # FastMCP 服务器
└── db.py            # 数据库管理

docs/
├── claude-desktop-setup.md  # Claude Desktop 配置文档
└── plans/           # 项目规划文档

tests/
├── test_*.py        # 单元测试
└── test_integration.py  # 集成测试
```

## 依赖项

### 核心依赖
- **mcp** >= 1.12.0 - MCP 框架
- **sqlmodel** >= 0.0.22 - ORM 框架
- **pydantic** >= 2.0 - 数据验证

### 开发依赖
- **pytest** >= 8.0 - 测试框架
- **pytest-asyncio** >= 0.24 - 异步测试支持

## 版本历史

### v0.1.0 (2026-04-22)
- 初始版本发布
- 完整的 MCP 服务器实现
- 39 个测试用例全部通过
- 支持完整的小说创作工作流

## 许可证

本项目采用 MIT 许可证。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 仓库地址

- **Gitee**: https://gitee.com/Git_Anything/Novel.git
- **版本**: v0.1.0

---

开始你的 AI 辅助小说创作之旅吧！🚀