经验知识存储与查询服务器

MCP服务器经验教训

中央MCP服务器，用于存储和查询经验教训和项目特定的实施细节。一个Laravel应用程序，为任何支持MCP的AI客户端提供两个MCP端点-- 光标, 克劳德代码, 谷歌反重力以及其他。

讲解员视频

观看解释 油管.

与ashwinmram/mcp推杆配合使用

此服务器与 ashwinmram/mcp推杆 包裹 通过HTTP API从您的Laravel项目推送课程和项目详细信息。

• 安装： composer require ashwinmram/mcp-pusher:^3.0
• 链接： GitHub | Packagist
• 最佳实践： 复制 知识获取提示 进入你的代理人；agent收集git上下文，综合经验教训，运行 mcp:append → 草稿。 mcp:push 在会议结束时。可选的 光标预紧钩 自动显示相同的提示。

mcp推杆包从以下位置推送会话草稿 docs/.mcp-session/*.jsonl 到 /api/lessons （通用）和 /api/project-details （项目特定） 一 mcp:push。参见 推动知识（mcp推杆3.0） 和 软件包/laravel mcp推送器/README.md.

主要特点

• MCP经验教训 (/mcp/lessons)--搜索、浏览和检索具有相关性评分的课程
• 项目详情MCP (/mcp/project-details?project=…)--项目特定的实现细节（路径、环境、约定）
• 工具： SearchLessons，GetLessonByCategory，GetLessonStags，FindRelatedLessons，MarkLessonHelpful，SuggestSearchQueries，GetTopLessons，GetCategoryStatistics
• 资源： lessons://overview, lessons://search-guide
• 提示： 课程学习概述，课程分类

仪表盘

经过身份验证的用户可以在以下网址查看实时统计数据 /dashboard每张卡片显示一个当前值、一个基线和一个方差徽章。

使用了两种比较模式，两者都基于 30天:

查看应用内 文档 对于相同的细节。

先决条件

• PHP 8.2+，12+<NUM>#2
• MySQL或SQLite
• Laravel羊群 （推荐）或等效的本地开发设置
• 支持MCP的AI客户端（Cursor、Claude Code、Google Antigravity或其他）

初始设置

1.克隆和安装

composer install
cp .env.example .env
php artisan key:generate
php artisan migrate

2.配置环境变量

将以下内容添加到您的 .env 文件：

# MCP server (HTTP base URL for MCP clients and API pushes)
APP_URL=https://mcp-server.test
MCP_SERVER_NAME="Lessons Learned MCP Server"

# MCP client (for pushing from this project via mcp-pusher)
MCP_SERVER_URL=https://mcp-server.test
MCP_API_TOKEN=  # Generated in step 3

3.生成API令牌

生成用于MCP身份验证的Sanctum API令牌：

php artisan mcp:generate-token --name="mcp-client-token"

如果不存在用户，此命令将创建一个用户，生成一个Sanctum令牌并显示它。 复制令牌 （仅显示一次）并将其添加到 .env:

MCP_API_TOKEN=your-token-here

在MCP客户端中使用相同的令牌 Authorization: Bearer … 头球

4.验证设置

确保您的网站可访问。使用Laravel Herd：

curl https://mcp-server.test

如果需要，将项目链接到Herd：

herd link mcp-server

测试MCP端点：

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     https://mcp-server.test/mcp/lessons

配置您的AI客户端

所有客户都需要：

• 课程URL： https://mcp-server.test/mcp/lessons
• 项目详细信息URL（可选）： https://mcp-server.test/mcp/project-details?project=<source> — project 必须匹配 php artisan mcp:push --source=…
• 头球 Authorization: Bearer YOUR_SANCTUM_TOKEN

示例配置文件（复制和编辑）： 光标, 克劳德, 反重力.Root mcp.json.示例 是一个最小的面向游标的示例。

光标

设置UI

1. 打开光标设置： ⇧+⌘+J （Mac）或 Ctrl+Shift+J （Windows/Linux）
2. 特性 → 主控程序 → 添加MCP服务器
3. 配置：
   • 姓名： lessons-learned-local （或任何名称）
   • 运输： SSE
   • 网址： https://mcp-server.test/mcp/lessons
   • 标题： {"Authorization": "Bearer YOUR_SANCTUM_TOKEN_HERE"}
4. 保存和 重新启动游标

项目 mcp.json

{
    "mcpServers": {
        "lessons-learned-local": {
            "transport": "sse",
            "url": "https://mcp-server.test/mcp/lessons",
            "headers": {
                "Authorization": "Bearer YOUR_SANCTUM_TOKEN_HERE"
            }
        }
    }
}

• 全球的： ~/.cursor/mcp.json 或设置UI--所有项目
• 项目： mcp.json 在项目根目录中——仅此项目（gitignore令牌）

验证： 设置→ MCP → 服务器 连接问：“关于测试Laravel包，我们有什么经验教训？”

克劳德代码

更喜欢 超文本传输协议 交通（Laravel Mcp::web 使用HTTP）。使用 上海证券交易所 仅当HTTP失败时。

命令行界面

claude mcp add --transport http lessons-learned \
  https://mcp-server.test/mcp/lessons \
  --header "Authorization: Bearer YOUR_TOKEN"

claude mcp add --transport http project-details-my-app \
  "https://mcp-server.test/mcp/project-details?project=my-app" \
  --header "Authorization: Bearer YOUR_TOKEN"

项目 .mcp.json

{
    "mcpServers": {
        "lessons-learned": {
            "type": "http",
            "url": "https://mcp-server.test/mcp/lessons",
            "headers": {
                "Authorization": "Bearer YOUR_TOKEN"
            }
        }
    }
}

范围： local （默认， ~/.claude.json), project (.mcp.json 回购），或 user。参见 克劳德代码MCP文档.

验证： claude mcp list --服务器显示已连接；启动会话并查询课程。

谷歌反重力

共享配置： ~/.gemini/config/mcp_config.json （Antigravity IDE和CLI共享此路径 谷歌代码实验室).

{
    "mcpServers": {
        "lessons-learned": {
            "serverUrl": "https://mcp-server.test/mcp/lessons",
            "headers": {
                "Authorization": "Bearer YOUR_TOKEN"
            }
        },
        "project-details-my-app": {
            "serverUrl": "https://mcp-server.test/mcp/project-details?project=my-app",
            "headers": {
                "Authorization": "Bearer YOUR_TOKEN"
            }
        }
    }
}

UI： 代理面板→ ... → MCP服务器 → 刷新；添加或验证服务器。

验证： MCP服务器显示已连接；向代理询问可用的课程。

代理启动说明

为您的AI客户端安装代理说明：

看 代理说明README 用于标记和手动路径。

# Example: full setup for Cursor + Claude + Antigravity (workspace skills)
php artisan mcp:install-agent-instructions --with-hooks --with-claude-md --with-cursorrules

这个monorepo使用了一个简短的 .cursorrules 指数；消费者项目应使用上述安装命令或从以下位置复制存根 packages/laravel-mcp-pusher/stubs/.

会话如何使用MCP服务器

1. 您的AI客户端使用配置的URL和Bearer令牌进行连接
2. 服务器暴露 lessons://overview 和MCP工具/提示
3. 配置了启动说明后，代理会阅读概述并查询相关课程
4. 课程为会议期间的编码决策提供了经验教训

示例提示（任何客户端）

• “关于Laravel验证，我们有什么经验教训？”
• “向我展示标记为‘php’和‘最佳实践’的课程”
• “给我一个可用课程的概述”
• “我们对测试Laravel包了解多少？”

可用的MCP组件

工具

• 搜索课程 --按关键字、类别或标签搜索（MySQL FULLTEXT+相关性评分）
• GetLessonByCategory --获取一个类别中的所有课程
• GetLessonTags --列出可用标签
• 查找相关讲座 --按主题关系查找相关课程
• MarkLesson有用 --为相关性评分提供反馈
• 建议搜索查询 --使用相关查询扩展搜索
• GetTop课程 --获得相关性最高的课程（可按类别选择）
• 获取类别统计信息 --类别统计数据（平均相关性、顶级课程、使用情况）

资源

• lessons://overview --课程、类别、标签和最近课程概述
• lessons://search-guide --搜索策略、查询示例、相关性评分

提示

• 课程学习概述 --现有经验教训概述
• 课程分类 --特定类别的经验教训总结

推动知识（mcp推杆3.0）

消费者项目使用 ashwinmram/mcp推杆。参见 3.0中的新功能.

工作流程（所有IDE）

1. 复制 知识获取提示 从README包中屏蔽到您的代理中（或使用可选 光标预紧钩).
2. Agent收集git上下文，综合经验教训，运行 mcp:append → docs/.mcp-session/lessons-draft.jsonl 和 project-details-draft.jsonl.
3. 会议结束：审查草稿（见 包README)那么 php artisan mcp:push --source=<project>.

成功推送后，草稿文件将被清除，除非 --no-truncate.使用 mcp:extract-session 只有在压实后草稿很薄并且您已经提交了工作时（仅限git；请参阅 mcp推手自述).

文件布局（3.0）

your-project/
└── docs/
    └── .mcp-session/
        ├── lessons-draft.jsonl         ← generic lessons
        └── project-details-draft.jsonl ← project-specific details

此服务器（monorepo）

php artisan mcp:push --source=mcp-server

其他Laravel项目

composer require ashwinmram/mcp-pusher:^3.0

配置 MCP_SERVER_URL, MCP_API_TOKEN，微笑。 docs/.mcp-session/.完整指南： 包README.

可选：游标挂钩（此monorepo）

mkdir -p .cursor/hooks
cp packages/laravel-mcp-pusher/stubs/cursor-hooks/hooks.json.example .cursor/hooks.json
cp packages/laravel-mcp-pusher/stubs/cursor-hooks/pre-compact-checkpoint.sh .cursor/hooks/
cp packages/laravel-mcp-pusher/stubs/knowledge-capture-prompt.txt .cursor/hooks/
chmod +x .cursor/hooks/pre-compact-checkpoint.sh

项目详细信息MCP服务器

网址： https://mcp-server.test/mcp/project-details?project=<source_project>

使用相同的Bearer令牌。为每个项目添加一个MCP服务器条目(?project=… 必须匹配 --source 推）。

管理代币

php artisan mcp:list-tokens
php artisan mcp:list-tokens --revoke=<TOKEN_ID>
php artisan mcp:list-tokens --revoke-all
php artisan mcp:generate-token --name="mcp-client-token" --force

生产设置

1. 更新 .env 随着生产 APP_URL 和 MCP_SERVER_URL
2. php artisan mcp:generate-token --name="mcp-production" --email="admin@yourdomain.com"
3. 更新 每个MCP客户端 带有生产URL和令牌
4. 集 SANCTUM_STATEFUL_DOMAINS 对于您的生产域

故障排除

令牌不工作

• php artisan mcp:list-tokens
• php artisan mcp:generate-token --force

客户端无法连接

• 确认URL可访问： curl -H "Authorization: Bearer TOKEN" https://mcp-server.test/mcp/lessons
• 检查 Authorization: Bearer YOUR_TOKEN （包括 Bearer)
• 光标： 重启应用程序；验证设置→ MCP → 有联系的；配置中的SSE传输
• 克劳德代码： claude mcp list；试试看 --transport http 然后 --transport sse 如有需要
• 反重力： 刷新代理面板中的MCP服务器；验证 ~/.gemini/config/mcp_config.json 用途 serverUrl 和标题
• 畜群： 网站已链接并正在运行(herd link mcp-server)

代理中未加载课程

• 重启AI客户端（MCP通常在启动时连接）
• 询问：“使用课程学习概述提示”
• tail -f storage/logs/laravel.log

身份验证错误（401）

• 重新生成令牌；验证客户端配置中的Bearer标头

SSL/证书问题

群 .test 域使用本地证书。如果客户端拒绝HTTPS：

• 信任客户端中的证书，或使用 mkcert

数据库/CORS

• php artisan migrate:status / php artisan migrate
• 确保域位于 config/sanctum.php 有状态域

安全考虑

1. 令牌存储 --永远不要承诺代币；使用 .env
2. 代币轮换 --如果受到威胁，请进行轮换
3. 超文本传输安全协议 --生产中需要
4. 速率限制 --考虑MCP端点

项目结构

• routes/ai.php --MCP路由注册
• app/Mcp/ --Lessons服务器，项目详细信息服务器
• docs/.mcp-session/ --mcp推杆会议草稿
• packages/laravel-mcp-pusher — ashwinmram/mcp推杆 （本地副本）

其他资源

• Laravel圣所
• 模型上下文协议
• Laravel MCP
• 光标MCP
• 克劳德代码MCP
• 谷歌反重力MCP代码实验室
• Laravel羊群

许可证

麻省理工学院