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 查询是否考虑了 N1 问题”、“确保 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 numberstock为 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 所有字段可能是可选的。requireAuthauthRole: 这些参数会触发工具在生成的代码中插入对应的权限校验逻辑。你需要确保项目的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 助手——也就是你的编程伙伴——的指尖。