Laravel MCP 聊天应用

使用 Laravel 12 和 MCP（模型上下文协议）服务器构建的极简聊天应用程序。允许发送消息、回复线程、按频道组织对话、用表情符号反应、搜索和列出用户；所有功能均可通过现成的 MCP 工具访问。

要求：PHP 8.4+，SQLite，Node.js（用于资源），Composer 和 npm。

注意：此项目基于 Laravel Starter Kit 模板，并添加了一个完整的面向聊天的 MCP 服务器。

🚀 特性

• 发送和列出最近的消息
• 回复（线程）和查看完整线程
• 带有自动继承频道的频道/房间
• 表情符号反应（防重复：每个用户/表情/消息）
• 关键词搜索、用户搜索和日期范围搜索
• 列出活跃用户及其统计数据
• 使用 Pest 进行测试，使用 PHPStan 进行静态分析，使用 Pint/Rector 进行格式化

🧩 可用的 MCP 工具

工具名称（参数 → 简短描述）：

• [send-message] (name, content, channel?) → 发送消息；默认频道：general
• [get-messages] (limit?) → 最近的消息（默认 50 条）
• [reply-to-message] (parent_message_id, name, content) → 回复并创建线程；继承父级频道
• [get-message-thread] (message_id) → 查看消息及其所有时间顺序的回复
• [get-channels] () → 频道列表及其统计数据（数量，最新活动）
• [get-channel-messages] (channel, limit?) → 获取频道的主要消息
• [add-reaction] (message_id, user_name, emoji) → 添加反应；每个用户/表情/消息只能有一个
• [remove-reaction] (message_id, user_name, emoji) → 移除你的反应
• [get-message-reactions] (message_id) → 按表情分组的反应及其响应者
• [get-users-list] (limit?, sort_by?) → 列出唯一用户及其总消息数和最新活动
• [search-messages] (query, limit?) → 搜索关键词或短语（不区分大小写）
• [get-messages-by-user] (name, limit?) → 按作者过滤（部分匹配）
• [get-messages-by-date-range] (start_date?, end_date?, limit?) → 按日期过滤

常见参数：字符串长度限制（name: 1-50, content: 1-500, channel: <=50）。结果限制：1-100（默认 50）。

允许的表情符号：👍 ❤️ 😂 🎉 🚀 👏 🔥 💯 👎 😮 😢 😡 🤔 💡 ✅ ❌

🧪 快速示例（MCP 客户端）

• 向频道发送消息： { "name": "Alice", "content": "来自Python的问候！", "channel": "python" }

• 回复消息： { "parent_message_id": 42, "name": "Bob", "content": "完全同意" }

• 查看线程： { "message_id": 42 }

• 列出频道： {}

• 频道的消息： { "channel": "general", "limit": 10 }

• 添加反应： { "message_id": 1, "user_name": "Jane", "emoji": "👍" }

• 搜索消息： { "query": "Laravel", "limit": 20 }

🛠️ 本地启动

1. 依赖项和环境

• 复制 .env 并生成密钥
• 确保 SQLite 可用

2. 安装和构建

• composer install
• npm install
• npm run build (或 npm run dev)

3. 数据库

• 创建 SQLite 文件：database/database.sqlite（如果不存在）
• php artisan migrate
• 可选：填充示例数据集 Knowmadmood
  • php artisan db:seed --class=Database\Seeders\KnowmadmoodSeeder

4. 服务器

• php artisan serve

5. MCP 端点

• 可用路径：/mcp/chat

提示

• 如果前端没有看到更改，请运行 npm run dev 或 npm run build
• 有用的脚本：composer test, composer lint, composer test:types

📖 功能使用指南

消息

• 发送使用 [send-message]（可选频道；默认为 general）
• 列表使用 [get-messages]

线程

• 创建回复使用 [reply-to-message]（验证父级存在）
• 查看线程使用 [get-message-thread]（包括计数、时间顺序和反应）

频道

• 频道字段已索引；最大 50 字符
• 回复自动继承父级频道
• 工具：[get-channels], [get-channel-messages], [send-message] (channel), [reply-to-message] (继承)

反应和用户

• 反应：[add-reaction], [remove-reaction], [get-message-reactions]
• 用户：[get-users-list] 可排序 name, messages（默认）或 last_activity

搜索和过滤

• 关键词：[search-messages]
• 按用户：[get-messages-by-user]
• 日期范围：[get-messages-by-date-range]

🗄️ 数据模型和关系

• Message: id, parent_id (可为空，自引用外键)，name, content, channel (索引)，时间戳
• Reaction: id, message_id (外键)，user_name, emoji, 时间戳，UNIQUE(message_id, user_name, emoji)
• 关系：
  • Message hasMany replies (parent_id)
  • Message belongsTo parent
  • Message hasMany reactions
  • Reaction belongsTo Message

优化的典型查询：

• 按频道的消息（使用 channel 索引）：WHERE channel = ? AND parent_id IS NULL
• 频道列表：GROUP BY channel 使用 MAX(created_at) 和 COUNT(*)

🧰 开发、质量和测试

• 代码检查和格式化：Pint 和 Rector → composer lint
• 类型覆盖（Pest）：composer test:type-coverage
• 静态分析（PHPStan）：composer test:types
• 单元测试（Pest）：composer test:unit
• 完整套件：composer test

测试涵盖：线程、频道、反应、用户、搜索和过滤、验证和输出格式（相对时间戳，单复数正确，结果限制）。

📦 示例数据（可选）

Knowmadmood Seeder 创建了消息、线程、反应和多个现实的频道：

• 命令：php artisan db:seed --class=Database\Seeders\KnowmadmoodSeeder
• 示例频道：general, jobs, php, python, devops, off-topic
• 包含线程和主要消息及回复的不同反应

🌐 网络访问和实用工具

• 本地服务器：php artisan serve → http://localhost:8000
• MCP 端点：http://localhost:8000/mcp/chat
• 有用的 SQL/CLI：参见 HOW_TO_VIEW.md 以了解如何使用 sqlite3 和快速别名进行查询

🔭 建议的下一步

• 明确的频道管理（创建/重命名/删除，描述，私有）
• 在搜索工具中按特定频道搜索
• 线程和频道的通知/订阅
• 高级统计（趋势，顶级反应者，最常用的表情符号）

📄 许可证

MIT。基于 Laravel Starter Kit 并扩展为一个聊天 MCP 服务器。