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
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
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_KEYOpenAI API 错误
验证
- 是正确的并且有学分前端问题：
- 端口5173已被占用Vite 将自动使用下一个可用端口
- API连接错误确保后端在正确的端口上运行
node_modules构建错误
清晰
- 并重新安装依赖项MCP问题：
mcp_config.json - MCP服务器无法启动检查Python路径在
- 工具不可用验证MCP服务器是否正在运行并已连接
状态未持久化
检查MCP服务器日志中的错误 DEBUG=True 🔍 调试模式 .env 通过设置启用调试模式
- 在你的
- 文件。这提供了：
- 详细的错误信息
- 请求/响应日志记录
数据库查询日志记录
MCP服务器调试输出
FastMCP 文档
SQLAlchemy 教程
React Router 指南
📝 许可证 © 2025 苏菲·哈桑·阿西姆。版权所有。 这个项目遵循MIT许可证授权——详见
许可证 详情请查阅文件。
如需咨询，请联系：
hassanasim337@gmail.com（这个邮箱地址本身在中文中没有特定的翻译，直接保持原样即可，表示的是一个电子邮箱地址，即“hassanasim337的谷歌邮箱”）
- 👨💻 作者 苏菲·哈桑·阿西姆
- 📧 电子邮件：
- hassanasim337@gmail.com（这个邮箱地址本身在中文中没有特定的翻译，直接保留原样即可，表示的是一个电子邮箱地址）
🎯 MCP APP的创作者——你的冒险AI由你定
- 📅 版权所有 © 2025 🙏 致谢
- FastAPI - 现代、快速的Web框架，用于构建API
- React - 用于构建用户界面的JavaScript库
- 快点 - 下一代前端工具链
- FastMCP - 模型上下文协议服务器实现
- OpenAI（开放人工智能研究所） - 基于人工智能的故事生成能力
- SQLAlchemy - Python SQL工具包和对象关系映射（ORM）
LangChain
- 开发大型语言模型（LLM）应用的框架
- 📞 支持与社区🆘 寻求帮助
- 检查文件/文档审阅此README文件和内联代码注释
- 搜索问题查看现有的GitHub问题
- 创建问题提交详细的错误报告或功能请求
社区
参与项目论坛的讨论
- 🐛 报告错误在报告错误时，请包含：
- 环境操作系统（OS）、Python版本、Node.js版本
- 重现步骤重现问题的详细步骤
- 预期行为应该发生什么
- 实际行为实际上发生了什么
- 错误信息完整的错误日志和堆栈跟踪
屏幕截图
（如适用）视觉证据
- 💡 功能需求对于功能请求，请提供：
- 用例为什么这个功能会很有价值
- 提出的解决方案你如何设想它的运作方式
- 替代方案你考虑过的其他方法
______________________________________________________________________
额外的背景信息 任何相关的背景信息
*🎭 快乐讲故事！*