使用说明

MCP 应用 - 你的冒险由你决定 AI 🎮📚

这是一款复杂且全面的交互式叙事应用程序，利用人工智能技术创作个性化的冒险故事。它采用现代网络技术构建，并与模型上下文协议（MCP）集成，通过Gemini命令行界面实现无缝的自然语言交互。

🎥 演示视频

📹 观看完整演示 - 全面介绍应用程序功能、MCP（多渠道计划/管理控制面板等，具体含义需根据上下文确定）集成以及自然语言交互。

🎬 观看演示视频

点击上方按钮直接在Google Drive上观看演示视频

📥 替代下载选项

Google Drive（谷歌云端硬盘）: 从Google Drive观看/下载 ⭐ 推荐
直接下载: MCP应用录制视频.mp4
尺寸约61 MB
格式MP4（兼容所有设备）

🎯 演示内容包括：

✅ 故事创作基于主题的故事生成
✅ 翻译成中文是：✅（这个符号本身在中文中没有特定的翻译，它通常用作表示正确、确认或完成的标记，所以直接保留原样或根据上下文解释为“正确”、“确认”等意思。） 互动式游戏玩法做出选择并推动故事发展
✅ 表示“正确”或“对”。 MCP 集成通过Gemini CLI使用自然语言命令
✅ 前端界面React组件与用户体验
✅ 后端APIFastAPI 端点和作业处理
✅ 实时更新作业状态监控和故事加载

注：该视频托管在Google Drive上，以确保最佳观看体验，并且在GitHub上也能无缝播放。

🌟 主要特点

🎯 核心功能

🧠 基于人工智能的故事生成利用OpenAI的GPT模型创作引人入胜、富有创意的叙事作品
🎮 互动式叙事做出能动态影响故事走向和结局的选择
🎨 基于主题的创作根据任何主题生成故事（太空冒险、中世纪奇幻、侦探悬疑等）
⚡ 实时处理异步故事生成，同时全面跟踪任务状态
💾 持久化存储用于故事持久化和检索的SQLite数据库
🔄 状态管理通过会话跟踪保持跨会话的游戏状态

🤖 高级MCP（多控制器协议/模块控制器协议等，具体含义根据上下文确定）集成

🗣️ 自然语言接口通过Gemini CLI使用对话命令与应用程序进行交互
🔧 FastMCP 服务器自定义MCP服务器，提供全面的应用功能作为可调用工具
🌉 无缝桥梁自然语言与FastAPI后端之间的智能翻译
📊 状态追踪在MCP交互过程中保持游戏状态
🎯 上下文感知记住当前故事位置和可用选项

🔄 应用流程

flowchart TD
    A[User Input Theme] --> B[Frontend: StoryGenerator]
    B --> C[API: POST /stories/create]
    C --> D[Backend: Story Creation Job]
    D --> E[OpenAI: Generate Story]
    E --> F[Database: Save Story Structure]
    F --> G[Job Status: Completed]
    G --> H[Frontend: StoryGame Component]
    H --> I[User Makes Choice]
    I --> J[API: POST /stories/choice]
    J --> K[Backend: Process Choice]
    K --> L[OpenAI: Continue Story]
    L --> M[Database: Update Story]
    M --> N[Return Next Story Segment]
    N --> H
    
    %% MCP Integration Flow
    O[Gemini CLI] --> P[MCP Server]
    P --> Q[Natural Language Processing]
    Q --> R[MCP Tools]
    R --> S[create_story]
    R --> T[check_job_status]
    R --> U[get_story]
    R --> V[make_choice]
    R --> W[get_current_status]
    R --> X[list_available_options]
    
    S --> C
    T --> Y[Job Status Response]
    U --> Z[Story Data Response]
    V --> J
    W --> AA[Current Game State]
    X --> BB[Available Choices]
    
    %% Styling
    classDef frontend fill:#e1f5fe
    classDef backend fill:#f3e5f5
    classDef database fill:#e8f5e8
    classDef mcp fill:#fff3e0
    classDef ai fill:#fce4ec
    
    class A,B,H frontend
    class C,D,G,J,K,M,N backend
    class F database
    class O,P,Q,R,S,T,U,V,W,X mcp
    class E,L ai

🏗️ 技术架构

📱 前端技术栈（React + Vite）

frontend/
├── src/
│   ├── components/
│   │   ├── StoryGenerator.jsx    # Theme input and story creation interface
│   │   ├── StoryGame.jsx         # Interactive story display and choice handling
│   │   ├── StoryLoader.jsx       # Story loading, navigation, and history
│   │   ├── LoadingStatus.jsx     # Real-time job status monitoring
│   │   └── ThemeInput.jsx        # Enhanced theme input component
│   ├── App.jsx                   # Main application component
│   ├── util.js                   # API configuration and utilities
│   ├── App.css                   # Application styling
│   └── index.css                 # Global styles
├── public/
│   └── vite.svg                  # Vite branding
├── package.json                  # Dependencies and scripts
├── vite.config.js               # Vite configuration
└── eslint.config.js             # ESLint configuration

前端技术：

React 19.1.0最新版React，具备并发特性
Vite 6.3.5快速构建工具和开发服务器
React Router DOM 7.6.0客户端路由
Axios 1.9.0API通信的HTTP客户端
ESLint代码质量和一致性

⚙️ 后端技术栈（FastAPI + SQLite）

backend/
├── main.py                       # FastAPI application entry point
├── mcp_server.py                 # Comprehensive MCP server implementation
├── core/
│   ├── config.py                 # Application configuration and settings
│   ├── models.py                 # SQLAlchemy database models
│   ├── prompts.py                # AI prompts for story generation
│   └── story_generator.py        # OpenAI integration and story logic
├── routers/
│   ├── story.py                  # Story-related API endpoints
│   └── job.py                    # Job status and management endpoints
├── db/
│   └── database.py               # Database connection and table creation
├── schemas/
│   ├── story.py                  # Pydantic schemas for story validation
│   └── job.py                    # Pydantic schemas for job validation
├── models/
│   ├── story.py                  # Story data models
│   └── job.py                    # Job data models
├── pyproject.toml                # Python project configuration
├── requirements.txt              # Python dependencies
├── uv.lock                       # UV lock file for dependency management
└── run_mcp_server.sh            # MCP server startup script

后端技术：

**FastAPI 0.115.12+**现代、快速的网络框架，带自动API文档
SQLAlchemy 2.0.41及以上版本高级数据库操作ORM（对象关系映射）
LangChain 0.3.25及以上版本大型语言模型（LLM）应用框架
**LangChain OpenAI 0.3.18+**LangChain的OpenAI集成
**Uvicorn 0.34.2+**FastAPI的ASGI服务器
**Python-dotenv 1.1.0+（或译为：Python-dotenv 1.1.0及以上版本）**环境变量管理
Pydantic数据验证和序列化

🚀 安装与设置

📋 先决条件

Python 3.13+ （如 pyproject.toml 中所指定）
Node.js 16及以上版本 （用于前端开发）
OpenAI API密钥 （用于故事生成）
Git（版本控制系统） （用于版本控制）

🔧 安装步骤

克隆仓库

git clone <your-repository-url>
cd MCP\ APP

后端设置

cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies using pip or uv
pip install -r requirements.txt
# OR if using uv:
uv pip install -r requirements.txt

环境配置

# Create .env file in backend directory
cat > .env << EOF
DATABASE_URL=sqlite:///./databse.db
API_PREFIX=/api
DEBUG=True
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173,https://localhost:3000,https://localhost:5173
OPENAI_API_KEY=your_openai_api_key_here
EOF

前端设置
```
cd ../frontend
npm install
```

🏃‍♂️ 运行应用程序

启动后端服务器
```
cd backend
source venv/bin/activate  # or venv\Scripts\activate on Windows
python main.py
```
- 后端可用地址： http://localhost:8000
- API文档： http://localhost:8000/docs
- ReDoc 文档： http://localhost:8000/redoc
启动前端开发服务器
```
cd frontend
npm run dev
```
- 前端访问地址： http://localhost:5173

🤖 MCP（机器控制协议/多控制器协议等，具体含义根据上下文确定）集成深度解析

🔍 什么是MCP？

模型上下文协议（MCP）是一种标准化协议，用于将人工智能助手与外部工具和数据源相连接。我们的实现创建了一个桥梁，将自然语言指令与应用程序的功能联系起来。

🛠️ MCP 服务器架构

MCP服务器（mcp_server.py提供：

状态管理追踪当前故事、节点位置和会话数据
工具暴露提供了6种全面的自然语言交互工具
错误处理强大的错误处理机制，提供详细的错误信息
会话持久性在交互过程中保持游戏状态

🔧 MCP 服务器设置

安装FastMCP

cd backend
source venv/bin/activate
pip install fastmcp

配置Gemini CLI

更新您的 ~/.gemini/settings.json：

{
  "theme": "Atom One",
  "selectedAuthType": "oauth-personal",
  "mcpServers": {
    "adventure-game": {
      "command": "/path/to/MCP APP/backend/run_mcp_server.sh",
      "args": [],
      "env": {}
    }
  }
}

使脚本可执行
```
chmod +x backend/run_mcp_server.sh
```

🛠️ 可用的MCP工具

工具	描述	参数	示例用法
`create_story`	生成以主题为新故事	`theme: str` “创作一个关于太空海盗的故事”
`check_job_status`	检查故事生成进度	`job_id: Optional[str]` “我的故事进展如何了？”
`get_story`	获取完整故事以进行游戏体验	`story_id: Optional[int]` “加载我的当前故事”
`make_choice`	制作互动故事选择	`choice_text: str` “选择第一个选项”
`get_current_status`	获取当前游戏状态	无	“我当前的位置是什么？”
`list_available_options`	列出所有可用选项	无	“我有哪些选择？”

💬 自然语言示例

一旦连接到Gemini CLI，您就可以使用对话式命令：

故事创作：

“创作一个关于太空探索的新冒险故事”
“创作一个以维多利亚时代伦敦为背景的神秘故事”
“创作一个关于龙和魔法的奇幻故事”

游戏玩法：

“我的故事进展如何了？”
“加载我的当前故事”
“我有什么选择呢？”
“我想选择第一个选项”
“选择通往城堡的那条路”

状态检查：

“我在故事中的当前处境是怎样的？”
“我的故事准备好了吗？”
“给我看看我们刚刚创作的完整故事”

🛠️ API 参考

📚 故事管理端点

方法	端点	描述	请求体	响应
项目	类别	描述	数值/范围	单位
工作信息	`GET`	`/api/stories/{story_id}/complete`
获取完整故事	无	故事完整数据	`POST`	`/api/stories/{story_id}/choice`

| 下一个故事片段 |

⚙️ 作业管理端点 | 方法 | 终点 | 描述 | 响应 | |--------|----------|-------------|----------| GET | /api/jobs/{job_id} |

| 获取作业状态 | 作业状态及详情 |

📊 数据模型

{
  "id": "integer",
  "title": "string",
  "theme": "string",
  "created_at": "datetime",
  "root_node": {
    "id": "integer",
    "content": "string",
    "is_ending": "boolean",
    "options": [
      {
        "text": "string",
        "next_node_id": "integer"
      }
    ]
  },
  "all_nodes": {
    "node_id": {
      "content": "string",
      "is_ending": "boolean",
      "options": "array"
    }
  }
}

故事结构：

🎯 工作原理详解 - 深入探讨

🔄 故事生成过程主题输入
**用户提供一个主题（例如，“太空冒险”）**人工智能处理
OpenAI GPT生成包含多条路径的初始故事设定数据库存储
故事结构已保存至SQLite数据库作业跟踪
异步作业系统追踪生成进度互动游戏

用户做出选择，动态地延续故事情节

🧠 人工智能集成详情模型
使用OpenAI的GPT模型进行故事生成提示工程
自定义提示确保故事结构一致且质量上乘叙事连贯性
保持多个段落中的故事一致性动态分支
根据用户的选择创建多个故事路径结束检测

识别自然的故事结局

💾 数据库模式

id故事表：
title主键
theme生成的故事标题
created_at用户提供的主题
root_node_id时间戳

引用起始节点

id故事节点表：
story_id主键
content外键关联到故事（或“外键指向故事”）
is_ending故事文本内容
is_winning_ending用于故事结局的布尔标志

布尔标志，用于表示积极结局

id故事选项表：
node_id主键
text指向故事节点的外键
next_node_id选择描述

指向下一个节点的外键

id工作表（或任务表）：
status主键（UUID）
story_id作业状态（待处理、处理中、已完成、已失败）
theme指向生成故事的外键
created_at原主题
completed_at创建作业的时间戳
error作业完成时间戳

如果失败，显示错误信息

🔧 配置与环境

🌍 环境变量 | 变量 | 描述 | 默认值 | 是否必需 | |----------|-------------|---------------|----------| DATABASE_URL |（无对应中文）|（无对应中文）|（无对应中文）|（无对应中文）| sqlite:///./databse.db | | SQLite 数据库连接字符串 | API_PREFIX | 序号 | /api | API路由前缀 DEBUG | 编号 | True | | 启用调试模式 | ALLOWED_ORIGINS | 不 | | OPENAI_API_KEY | 允许的CORS来源 | localhost变体 | 否 | | 用于故事生成的OpenAI API密钥 | 无 |

是的

http://localhost:3000 🔒 CORS 配置
http://localhost:5173 后端已配置为允许来自以下来源的请求：
https://localhost:3000 （React 默认端口）
https://localhost:5173 (Vite 默认端口)

(HTTPS 变体)

MCP APP/
├── backend/                    # FastAPI backend
│   ├── core/                  # Core application logic
│   ├── db/                    # Database configuration
│   ├── models/                # Data models
│   ├── routers/               # API route handlers
│   ├── schemas/               # Pydantic schemas
│   ├── main.py                # Application entry point
│   ├── mcp_server.py          # MCP server implementation
│   └── requirements.txt       # Python dependencies
├── frontend/                  # React frontend
│   ├── src/                   # Source code
│   ├── public/                # Static assets
│   └── package.json           # Node.js dependencies
├── mcp_config.json           # MCP configuration
├── mcp_requirements.txt      # MCP-specific dependencies
├── setup_mcp.sh              # MCP setup script
└── README.md                  # This file

（HTTPS 变体）

📁 文件结构概览

🚀 部署指南

☁️ 后端部署
生产考量因素：
用 PostgreSQL 替换 SQLite，以提高性能和可扩展性
使用环境特定的配置文件
实施适当的日志记录和监控

为生产环境设置反向代理（nginx）

FROM python:3.13-slim
WORKDIR /app
COPY backend/requirements.txt .
RUN pip install -r requirements.txt
COPY backend/ .
EXPOSE 8000
CMD ["python", "main.py"]

使用进程管理器（PM2、systemd）进行进程管理

Docker 部署：

cd frontend
npm run build

🌐 前端部署

构建过程：
部署选项：
静态托管（Netlify、Vercel、GitHub Pages）

CDN部署

DATABASE_URL=postgresql://user:password@localhost:5432/adventure_db
API_PREFIX=/api
DEBUG=False
ALLOWED_ORIGINS=https://yourdomain.com,https://www.yourdomain.com
OPENAI_API_KEY=your_production_openai_key

使用nginx进行容器部署

🔧 生产环境变量

cd backend
source venv/bin/activate
pytest tests/

🧪 测试

cd frontend
npm test

🔬 后端测试

🎨 前端测试

🧪 MCP 测试

通过连接到Gemini CLI并使用自然语言命令来测试MCP集成。

🤝 贡献
```
git clone <your-fork-url>
cd MCP\ APP
```

📝 开发工作流程

git checkout -b feature/amazing-feature

克隆仓库
- 创建特性分支
- 做出改变
- 遵循现有的代码风格
添加适当的测试
```
git commit -m 'Add amazing feature'
```

更新文档

git push origin feature/amazing-feature

提交更改

推送并创建拉取请求📋 代码标准
python遵循PEP 8风格指南
JavaScript使用 ESLint 配置
文档更新README文件以添加新功能说明
测试为新功能添加测试

类型提示

在Python代码中使用类型提示

🐛 故障排除

常见问题后端问题： main.py 端口8000已被占用
更改端口或者终止现有进程 DATABASE_URL 数据库连接错误 .env
检查在里面 OPENAI_API_KEY OpenAI API 错误

验证

是正确的并且有学分前端问题：
端口5173已被占用Vite 将自动使用下一个可用端口
API连接错误确保后端在正确的端口上运行 node_modules 构建错误

清晰

并重新安装依赖项MCP问题： mcp_config.json
MCP服务器无法启动检查Python路径在
工具不可用验证MCP服务器是否正在运行并已连接

状态未持久化

检查MCP服务器日志中的错误 DEBUG=True 🔍 调试模式 .env 通过设置启用调试模式

在你的
文件。这提供了：
详细的错误信息
请求/响应日志记录

数据库查询日志记录

MCP服务器调试输出

FastMCP 文档

SQLAlchemy 教程

React Router 指南

许可证详情请查阅文件。

如需咨询，请联系：

hassanasim337@gmail.com（这个邮箱地址本身在中文中没有特定的翻译，直接保持原样即可，表示的是一个电子邮箱地址，即“hassanasim337的谷歌邮箱”）

👨‍💻 作者苏菲·哈桑·阿西姆
📧 电子邮件：
hassanasim337@gmail.com（这个邮箱地址本身在中文中没有特定的翻译，直接保留原样即可，表示的是一个电子邮箱地址）

🎯 MCP APP的创作者——你的冒险AI由你定

FastAPI - 现代、快速的Web框架，用于构建API
React - 用于构建用户界面的JavaScript库
快点 - 下一代前端工具链
FastMCP - 模型上下文协议服务器实现
OpenAI（开放人工智能研究所） - 基于人工智能的故事生成能力
SQLAlchemy - Python SQL工具包和对象关系映射（ORM）

LangChain

- 开发大型语言模型（LLM）应用的框架

📞 支持与社区🆘 寻求帮助
检查文件/文档审阅此README文件和内联代码注释
搜索问题查看现有的GitHub问题
创建问题提交详细的错误报告或功能请求

社区

参与项目论坛的讨论

🐛 报告错误在报告错误时，请包含：
环境操作系统（OS）、Python版本、Node.js版本
重现步骤重现问题的详细步骤
预期行为应该发生什么
实际行为实际上发生了什么
错误信息完整的错误日志和堆栈跟踪

屏幕截图

（如适用）视觉证据

💡 功能需求对于功能请求，请提供：
用例为什么这个功能会很有价值
提出的解决方案你如何设想它的运作方式
替代方案你考虑过的其他方法

额外的背景信息 任何相关的背景信息

🎭 快乐讲故事！