1. 项目概述:一站式项目智能助手
如果你和我一样,日常开发主要围绕着 Next.js 和 Prisma 技术栈,那你肯定也经历过这样的场景:想快速了解一个新接手项目的全貌,得手动去翻看app/目录下的路由结构,还得去actions/文件夹里找有哪些 Server Actions,最后还得打开 Prisma Schema 文件看看数据模型。想生成一个新的 Server Action?又得去复制粘贴模板,手动填写 Zod Schema、权限校验和数据库操作逻辑。整个过程繁琐、重复,而且容易出错。
更别提现在 AI 辅助编码工具(比如 Claude Code、Cursor)已经成了标配,但它们对项目的“理解”往往停留在单个文件的层面,缺乏对整个项目架构和上下文的感知。你没法直接问它:“这个项目里关于用户管理的 Server Actions 都是怎么设计的?”或者“帮我生成一个创建订单的 Action,要包含库存校验”。
这就是project-mcp-server诞生的背景。它不是一个全新的框架,而是一个项目智能增强层。简单来说,它是一个符合 Model Context Protocol (MCP) 标准的服务器,专门为 Next.js + Prisma 项目打造。通过一个简单的交互式安装命令,它能为你的项目注入“智能”,让 AI 助手瞬间获得关于你项目的“超能力”:全景扫描、精准查询和基于真实上下文的代码生成。
它的核心价值在于“连接”与“增强”。它连接了你的项目代码库和 AI 助手,将原本静态的、需要人工解读的代码结构,转化为动态的、可查询的、可操作的智能工具。安装后,任何支持 MCP 的客户端(Claude Code、Cursor、VS Code with Continue 插件等)在打开你的项目目录时,都能自动加载这些工具,你和你的整个团队都能立即获得一致的、强大的项目智能支持。
2. 核心设计思路与架构解析
2.1 为什么选择 MCP (Model Context Protocol)
在深入代码之前,理解其基石——MCP——至关重要。MCP 是 Anthropic 提出的一种开放协议,旨在标准化 AI 应用(客户端)与外部工具、数据源(服务器)之间的通信。你可以把它想象成 AI 世界的“USB 协议”。
在project-mcp-server的语境下,选择 MCP 而非自己造轮子,是基于几个关键考量:
- 生态兼容性:MCP 正迅速成为 AI 工具生态的事实标准。支持 MCP,意味着你的项目智能能无缝接入 Claude Code、Cursor、Windsurf、Continue 等主流工具,避免了为每个工具单独开发适配器的成本。
- 协议标准化:MCP 定义了清晰的 JSON-RPC 接口规范,包括工具发现 (
tools/list)、调用 (tools/call)、资源读取等。这保证了服务器的稳定性和客户端交互的一致性。 - 配置即集成:MCP 采用声明式配置。客户端通过读取项目根目录的
.mcp.json文件来加载服务器。这意味着团队协作时,只需将此文件提交到代码库,所有成员打开项目即可获得相同的智能支持,无需任何手动配置。
project-mcp-server将自己定位为一个“项目领域”的 MCP 服务器,专注于提供与特定 Next.js + Prisma 项目强相关的工具集。
2.2 一体化安装与模块化设计
项目最亮眼的设计之一是它的安装流程。它没有提供一堆繁琐的、需要按顺序执行的 CLI 命令,而是通过一个统一的、交互式的npx project-mcp-server setup命令,将多个独立的、有价值的工具整合到一个安装向导中。
这种设计背后的逻辑是降低用户的决策和操作成本。开发者不需要分别研究 OpenSpec、Engram、Guardian Angel 是什么,如何安装,如何配置与 MCP 集成。安装向导就像一个经验丰富的技术顾问,为你清晰地展示可选的增强模块(组件),并一次性完成所有安装和配置工作。
从源码结构可以看出,这种模块化设计贯彻得非常彻底:
src/setup/installers/目录下,每个组件(如openspec.ts,engram.ts)都有自己独立的安装器。它们遵循统一的接口,由src/setup/index.ts中的向导协调器按需调用。- 这种“插件化”架构使得后续添加新的组件(例如,集成一个日志分析工具或性能监控工具)变得非常容易,只需实现对应的安装器并注册到向导中即可。
- 安装过程具备容错性。如果一个组件安装失败(例如网络问题导致 Engram 二进制文件下载失败),向导会记录错误并继续安装其他组件,而不是让整个安装过程崩溃。这在实际使用中非常友好。
2.3 工具设计:从静态扫描到动态生成
服务器提供的 10 个工具可以清晰地分为三类,体现了从信息获取到行动执行的完整工作流:
- 项目智能类工具(
project_scan,project_routes,project_actions,project_models):这些是“只读”的侦察兵。它们通过静态代码分析,构建项目的实时地图。例如,project_actions工具会解析actions/目录下的文件,不仅列出 Action 名称,还会提取其关联的 Zod Schema 和auth等标记,让 AI 能理解现有 Action 的契约和权限模型。 - 环境控制类工具(
env_status,env_run_check,env_prisma_status):这些是“诊断”工具。它们检查开发环境的健康状态,如 Docker 是否运行、.env.local变量是否缺失、是否有待执行的 Prisma 迁移。这相当于为 AI 助手装上了“听诊器”,能在你编码前或遇到问题时快速排查环境因素。 - 代码生成类工具(
generate_action,generate_page,generate_component):这些是“写”工具,也是价值的核心体现。它们不是基于通用模板生成代码,而是基于扫描到的真实项目上下文。例如,generate_action在为你生成“创建用户”的 Action 时,会去查询project_models工具的结果,获取User模型的真实字段定义,并据此生成类型安全的 Zod Schema 和 Prisma 查询语句。这确保了生成的代码与你的项目数据库模型 100% 匹配,极大减少了手动调整的工作量。
这种工具分层设计,使得 AI 助手能模拟一个资深开发者的工作流:先了解项目现状和环境状态,再基于现有模式和真实数据模型进行创造。
3. 核心组件深度集成与实战
3.1 OpenSpec:将 Spec-Driven Development 融入工作流
OpenSpec 倡导的是一种“先设计,后编码”的规范驱动开发模式。在传统的 AI 结对编程中,我们往往是直接对 AI 说“帮我写个登录页面”,然后开始来回调整。OpenSpec 引入了更结构化的协作流程:提案 (Propose) -> 规范 (Spec) -> 设计 (Design) -> 任务 (Task)。
project-mcp-server的安装器通过执行openspec init命令,将这套工作流“固化”到你的项目中。它会在.claude/skills/和.claude/commands/opsx/目录下生成一系列技能和命令。这意味着,安装后,你可以直接在 Claude Code 或 Cursor 的聊天框中输入/opsx:propose来启动一个新功能提案,AI 会引导你填写功能描述、验收标准等,最终生成结构化的开发任务。
实操心得:OpenSpec 的集成特别适合中小型团队或独立开发者管理复杂功能的开发。它迫使你在写代码前进行更深入的思考,将模糊的需求转化为清晰的、可执行的规范。生成的技能文件本质上是给 AI 的“操作手册”,能显著提升后续编码阶段 AI 输出代码的准确性和完整性。建议在开始一个全新模块或重构时,优先使用 OpenSpec 流程。
3.2 Engram:为项目赋予持久化记忆
AI 对话通常是“健忘”的,每次新开一个会话,之前关于技术决策、踩坑经验、项目特定约定的讨论都消失了。Engram 就是为了解决这个问题而生。它是一个本地的、基于 SQLite 的记忆系统,可以保存“观察”(代码片段、错误信息)、“会话”和“学习成果”。
安装 Engram 组件后,project-mcp-server会下载对应你操作系统的二进制文件,并将其配置为另一个 MCP 服务器添加到.mcp.json中。这样,AI 助手就获得了mem_save(保存记忆)、mem_search(搜索记忆)、mem_context(获取相关上下文)等工具。
工作流示例:当你解决了一个棘手的 Prisma 关联查询性能问题后,可以让 AI 使用mem_save工具,将问题描述、解决方案和关键代码片段保存到 Engram 中,并打上prisma、performance、optimization等标签。几周后,当另一个成员遇到类似问题时,AI 可以通过mem_search快速找到之前的解决方案,直接提供参考。
注意:Engram 的数据存储在本地
~/.local/share/engram/(类 Unix 系统)或%APPDATA%\engram\(Windows)目录下,是私有的。这意味着记忆不会上传到云端,保障了代码和讨论的隐私性。但对于团队共享记忆,目前需要手动分享数据库文件或依赖成员各自的本地记录。
3.3 Guardian Angel:把 AI 代码审查嵌入 Git 流程
代码审查是保证质量的关键环节,但人工审查耗时且可能不一致。Guardian Angel (GGA) 在代码提交前(pre-commit hook)自动介入,调用配置的 AI 模型(如 Claude、GPT、Ollama 本地模型)对暂存区的代码变更进行审查。
安装器会做三件事:
- 下载并安装 GGA 二进制文件。
- 在项目根目录创建或更新
AGENTS.md文件,这里定义了代码审查的标准和规则(例如,“必须包含错误处理”、“禁止直接使用any类型”)。 - (可选)在
.git/hooks目录下安装pre-commit钩子脚本。
当执行git commit时,钩子触发,GGA 会将代码 diff 和AGENTS.md中的规则一起发送给 AI,生成审查意见。如果 AI 认为代码有严重问题,它可以阻止本次提交。
避坑技巧:GGA 的审查深度和反馈质量高度依赖于AGENTS.md的编写。建议不要只写泛泛的规则,而是结合项目特点。例如,针对你的 Next.js 项目,可以加入:“检查 Server Action 是否都正确使用了'use server'指令”、“检查 Prisma 查询是否考虑了 N+1 问题”、“确保 Tailwind CSS 类名排序符合prettier-plugin-tailwindcss规范”。越具体,AI 审查的指导性就越强。
3.4 Gentleman-Skills:社区最佳实践的即插即用
这是一个由社区维护的技能库,包含了针对 React 19、Next.js 15、TypeScript、Tailwind 等现代技术栈的详细指南和最佳实践。project-mcp-server安装器会从 GitHub 下载这些技能文件,并复制到你的 AI 助手技能目录中。
这意味着,安装后,你的 AI 助手瞬间就“读”完了这些高质量的社区文档。当你询问“在 Next.js 15 里怎么实现路由拦截?”或者“React 19 的useHook 最佳实践是什么?”时,它能基于这些技能给出更准确、更符合最新社区共识的答案,而不是泛泛而谈或基于过时的知识。
4. 安装、配置与核心工具实战指南
4.1 逐步安装与配置详解
假设我们有一个名为my-saas-app的 Next.js + Prisma 项目,下面是如何一步步将其升级为“智能项目”。
步骤 1:环境准备与安装确保你的项目根目录下,并且 Node.js 版本在 20 以上。
cd /path/to/my-saas-app npx project-mcp-server setup此时,一个交互式命令行界面会启动。你会看到一个 ASCII 艺术风格的 Banner,然后是一个多选框列表,列出了所有可安装的组件:
[•] MCP Server(默认选中,核心)[ ] OpenSpec[ ] Engram[ ] Skills comunitarios[ ] Guardian Angel
使用上下箭头移动,空格键选中/取消选中。对于首次安装,我建议全部选中,以体验完整的增强工作流。选中后按回车继续。
步骤 2:安装过程解析安装器会按顺序执行以下操作,你可以在终端看到实时日志:
- 核心 MCP 服务器配置:在项目根目录创建
.mcp.json文件。这是最关键的一步,它建立了项目与 AI 客户端的连接。 - OpenSpec 初始化:运行
openspec init,在项目中创建.claude/目录结构及初始技能。 - Engram 安装:检测你的操作系统(macOS、Linux 或 Windows),从 GitHub Releases 下载对应的 Engram 二进制文件,将其安装到用户本地 bin 目录(如
~/.local/bin/),并在.mcp.json中添加 Engram 服务器配置。 - 社区技能下载:从 Gentleman-Skills 仓库下载最新的技能包,并复制到你的 AI 助手技能目录(例如,对于 Claude Desktop,可能是
~/Library/Application Support/Claude/claude_desktop_config/skills/)。 - Guardian Angel 安装:下载 GGA,创建
AGENTS.md模板,并询问你是否要安装 Git pre-commit hook。
安装完成后,安装器会给出一个清晰的总结,列出每个组件的安装状态(成功/失败)和下一步行动提示。
步骤 3:验证安装重启你的 AI 助手客户端(如 Claude Code 或 Cursor)。打开my-saas-app项目。客户端应该会自动读取.mcp.json并连接到新配置的 MCP 服务器。你通常可以在客户端的设置或连接状态页面看到已加载的服务器。
4.2 核心工具调用实战与参数详解
安装成功后,你就可以在 AI 助手的聊天窗口中,像调用普通函数一样使用这些工具了。以下是一些典型场景和详细参数说明。
场景一:快速项目导航与理解当你刚接手项目或需要回顾架构时,可以这样操作:
请帮我扫描一下当前项目的整体结构。AI 助手会调用project_scan()工具。该工具无参数,它会返回一个结构化的 JSON,包含:
routes: 所有 App Router 路径及其类型(Page, Layout, API等)。actions: 所有 Server Actions 列表。models: 所有 Prisma 数据模型。components: 检测到的 UI 组件(优先识别 shadcn/ui 组件)。
如果你想更聚焦:
列出所有与用户认证相关的 Server Actions。AI 可能会先调用project_actions(),然后在其返回的结果中进行本地筛选,或者更智能地,它可以直接尝试调用project_actions({ feature: 'auth' })(如果该参数被支持)。你需要查阅项目的具体工具定义来了解可用过滤器。
场景二:基于真实模型的代码生成这是最能体现价值的场景。假设你的 Prisma Schema 中有一个Product模型,现在需要创建一个新增产品的 Server Action。
你可以对 AI 说:
请为我生成一个创建新产品的 Server Action。需要验证输入,并且只有管理员可以调用。AI 助手会执行一个连贯的操作:
- 首先调用
project_models(),获取Product模型的详细字段定义(如id,name,description,price,stock,createdAt等)。 - 然后,它调用
generate_action()工具,并传递参数:{ "entity": "product", "operation": "create", "requireAuth": true, "authRole": "admin" } - 工具内部会基于获取的
Product模型字段,自动生成一个完整的 Zod Schema(例如,name为 string 且必填,price为 positive number,stock为 integer 等)。 - 最终,生成一个包含以下内容的 Action 代码文件:
'use server'指令。- 导入正确的
auth函数和角色检查逻辑(根据你项目的权限体系)。 - 生成的、与模型匹配的 Zod Schema (
productCreateSchema)。 - 使用 Prisma Client 创建新
Product的记录。 - 可选的重新验证标签(如
revalidateTag(‘products’))。 - 完整的错误处理。
关键参数解析:
entity: 对应 Prisma 模型名称(小写)。工具会进行智能匹配,即使你输入“Product”,它也能找到product模型。operation: 通常是“create”,“update”,“delete”,“list”,“get”。这决定了生成的 Action 基本模板和 Zod Schema 的差异(例如,update操作的 Schema 所有字段可能是可选的)。requireAuth&authRole: 这些参数会触发工具在生成的代码中插入对应的权限校验逻辑。你需要确保项目的auth工具或库已正确实现,并且generate_action工具了解其 API。
场景三:环境与状态检查在开始编码或遇到奇怪 bug 时,快速检查环境:
检查一下当前开发环境的状态,看看有没有明显问题。AI 调用env_status(),返回信息可能包括:
docker:{ “running”: true, “composeFileExists”: true }envFile:{ “.env.local”: true, “missingVariables”: [“STRIPE_SECRET_KEY”] }prisma:{ “clientGenerated”: true, “migrationsPending”: false }packageManager:“pnpm”
如果显示有缺失的环境变量,你可以立即去补充,避免运行时错误。
5. 高级工作流、问题排查与定制化
5.1 整合工作流示例:从设计到提交
让我们串联起所有组件,看一个功能开发的高效闭环:
- 记忆唤醒:
/mem_context(Engram) 或直接询问 AI:“我们之前关于用户仪表盘的数据聚合有什么讨论或决策吗?”。AI 使用 Engram 的mem_search查找历史记录。 - 项目侦察:
project_scan()和project_routes(),了解现有的用户相关路由和组件。 - 规范驱动设计:
/opsx:propose(OpenSpec)。与 AI 协作,填写新功能“用户行为分析面板”的提案表单,生成详细规范。 - 智能生成:基于规范,让 AI 调用
generate_page()生成仪表盘页面框架,再调用generate_component()生成图表组件。所有生成都基于现有的项目 UI 库(如 shadcn/ui)和代码风格。 - 环境验证:在关键节点运行
env_run_check({ check: ‘typecheck’ })和env_run_check({ check: ‘lint’ }),确保代码质量。 - 提交前审查:执行
git add .和git commit。Guardian Angel 的 pre-commit hook 被触发,自动调用 AI 对本次更改进行审查。根据AGENTS.md的规则,AI 可能会提示:“新增的AnalyticsChart组件缺少 React.memo 包装,考虑到其 props 变化频率低,建议优化性能。” 你根据反馈修改后再次提交。 - 保存经验:问题解决或功能完成后,让 AI 调用
mem_save(),将“用户仪表盘数据聚合使用useMemo优化查询”这个关键决策点保存到 Engram,供未来参考。
5.2 常见问题与排查指南
即使设计得再完善,在实际部署和使用中也可能遇到问题。下面是一个常见问题速查表:
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
| AI 客户端无法连接或找不到工具 | 1..mcp.json配置错误或路径不对。2. MCP 服务器进程未启动或崩溃。 3. 客户端不支持 MCP 或配置未刷新。 | 1. 检查项目根目录下.mcp.json文件是否存在且格式正确。确保MCP_PROJECT_ROOT环境变量在配置中指向正确路径(通常是“.”)。2. 在项目目录下手动运行 npx project-mcp-server启动服务器,观察终端是否有错误输出。常见错误是缺少依赖,运行npm install确保所有依赖已安装。3. 重启 AI 客户端。在客户端的设置中检查 “MCP Servers” 列表,确认你的项目服务器已加载。 |
generate_action生成的代码找不到 Prisma 模型 | 1. Prisma Schema 文件未被正确解析。 2. MCP_PROJECT_ROOT环境变量未指向正确项目根目录,导致扫描器找不到prisma/schema.prisma。3. 使用了非标准的 Prisma 文件位置或多 Schema 文件。 | 1. 运行npx prisma generate确保 Prisma Client 是最新的,同时验证 Schema 语法无误。2. 检查 .mcp.json中env配置的MCP_PROJECT_ROOT。在复杂项目结构(如 monorepo)中,可能需要将其设置为子项目路径。3. 项目支持多 Schema 文件。检查 project_models()工具的返回结果,看是否包含了所有预期的模型。如果未包含,可能是扫描器的 glob 模式未覆盖你的 Schema 文件位置。 |
| Engram 命令执行失败或返回“command not found” | 1. Engram 二进制文件下载失败或安装路径不在系统的 PATH 中。 2. 权限问题,二进制文件不可执行。 | 1. 检查~/.local/bin/(或 Windows 对应目录)下是否有engram可执行文件。如果没有,可以尝试从 Engram Releases 手动下载并放置到该目录。2. 在终端中,为二进制文件添加执行权限: chmod +x ~/.local/bin/engram。然后确认~/.local/bin在你的 PATH 中:echo $PATH。 |
| Guardian Angel 的 pre-commit hook 未运行 | 1. Git hook 安装失败或被覆盖。 2. AGENTS.md文件不存在或格式错误。3. GGA 二进制文件路径问题。 | 1. 检查.git/hooks/pre-commit文件是否存在且内容包含调用 GGA 的逻辑。可以重新运行安装向导并选择安装 hook。2. 确保项目根目录存在 AGENTS.md文件,并且是有效的 Markdown 格式。3. 尝试在终端直接运行 gga --help,看命令是否可用。如果不可用,可能需要手动将 GGA 二进制文件路径添加到系统 PATH,或在 hook 脚本中使用绝对路径。 |
| 社区技能未在 AI 助手中显示 | 1. 技能文件被下载到了错误的目录。 2. AI 客户端需要手动刷新或重启才能识别新技能。 | 1. 查看安装日志,确认技能被复制到了哪个目录。对比该目录与你 AI 客户端设置中指定的技能目录是否一致。 2. 完全退出并重启 AI 客户端应用。对于某些客户端,可能需要在设置中手动点击“重新加载技能”。 |
调试技巧:你可以使用项目自带的npm run inspect命令,通过 MCP Inspector 这个图形化工具来查看服务器提供的所有工具列表、它们的参数 schema,并进行手动测试调用。这对于开发自定义工具或深度调试极其有用。
5.3 进阶定制与扩展
project-mcp-server本身是开源的,这意味着你可以根据自己项目的特殊需求对其进行定制和扩展。
添加自定义工具:如果你有一套内部的项目规范或常用工具,可以为其创建自定义 MCP 工具。例如,为你的项目添加一个generate_api_docs工具,基于现有的路由和 Zod Schema 自动生成 OpenAPI 文档。
- 在
src/tools/目录下创建新的模块,例如src/tools/custom/。 - 实现你的工具函数,并按照 MCP SDK 的格式定义工具 schema(名称、描述、输入参数)。
- 在
src/index.ts中导入并注册这个新工具。 - 重新构建并发布你自己的版本,或直接在本地的
node_modules中链接使用。
调整扫描逻辑:默认的扫描器针对的是标准的 Next.js App Router 和 Prisma 结构。如果你的项目结构特殊(例如,将 Actions 放在lib/actions而非actions/),你可以修改src/scanner/目录下的相应文件(如actions.ts)中的文件路径匹配模式。
集成其他 MCP 服务器:.mcp.json文件可以配置多个 MCP 服务器。你可以手动编辑该文件,添加其他有用的服务器,例如连接公司内部知识库的服务器、数据库管理服务器等。project-mcp-server的安装向导为你创建了一个可扩展的配置中心。
这个项目的真正力量在于它将一系列离散的、强大的开发者工具,通过 MCP 这个统一协议,优雅地集成到了你的日常开发环境中。它减少了上下文切换,将项目知识、环境状态和社区最佳实践直接送到了 AI 助手——也就是你的编程伙伴——的指尖。