用 Context Engineering 与 PRP 流程构建生产级 MCP ServerGitHub OAuth PostgreSQL Cloudflare Workers 实战指南【免费下载链接】context-engineering-introContext engineering is the new vibe coding - its the way to actually make AI coding assistants work. Claude Code is the best for this so thats what this repo is centered around, but you can apply this strategy with any AI coding assistant!项目地址: https://gitcode.com/gh_mirrors/co/context-engineering-introMCPModel Context ProtocolServer 正成为 AI 编码助手连接外部数据与操作的标准桥梁但「凭感觉写一个能跑的工具」与「交付一个带认证、权限、监控的生产级服务」之间隔着大量工程细节。本文以 context-engineering-intro 仓库中的 MCP Server Builder 用例 为骨架系统讲解如何用Context Engineering与PRPProduct Requirements Prompt流程从零构建并部署一个具备 GitHub OAuth 认证、PostgreSQL 集成、Cloudflare Workers 边缘部署与可观测性的生产级 MCP Server。读完本文你将掌握 PRP 驱动的 AI 开发工作流、MCP 工具注册模式、OAuth 认证与数据库安全的底层实现并能够直接复用本仓库模板开始自己的项目。为什么 MCP Server 开发需要 Context Engineering传统的 PRD 只回答「做什么」和「为什么做」却刻意回避「怎么做」而 LLM 生成代码的质量恰恰高度依赖上下文的质量。本仓库的 PRP 概念文档 给出了精确定义A PRP is PRD curated codebase intelligence agent/runbook——the minimum viable packet an AI needs to plausibly ship production-ready code on the first pass.PRP 在保留 PRD 的目标与理由部分之外增加了三层 AI 关键内容Context上下文精确的文件路径与内容、库版本、代码片段示例。直接给 LLM 具体的引用而非宽泛描述能显著提升输出质量这也是ai_docs/目录用于注入库文档的原因Implementation Details and Strategy实现细节与策略明确说明如何构建包括 API 端点、测试运行器、Agent 模式ReAct、Plan-and-Execute、类型注解、依赖与架构模式Validation Gates验证门禁确定性的检查如 pytest、ruff、静态类型检查把质量左移在早期捕获缺陷比后期返工成本更低。「Garbage In → Garbage Out」在 Agent 工程中尤其成立粗糙的输入会产生脆弱的代码。PRP 的价值正在于把「做什么」与「怎么做」焊接在一起让 AI 编码 Agent 第一次就能交出接近生产级的代码。本用例将这套思想落到了 MCP Server 开发上GitHub OAuth 认证、数据库集成、Cloudflare Workers 部署全部通过 PRP 模板与专属命令驱动。快速开始从模板搭建项目前置条件已安装 Node.js 与 npm一个 Cloudflare 账号免费套餐即可一个用于 OAuth 的 GitHub 账号一个 PostgreSQL 数据库本地或托管均可。第 1 步复制模板并初始化项目# 克隆 context engineering 仓库 git clone https://github.com/coleam00/Context-Engineering-Intro.git cd Context-Engineering-Intro/use-cases/mcp-server # 将模板复制到你的新项目目录 python copy_template.py my-mcp-server-project # 进入新项目 cd my-mcp-server-project # 安装依赖 npm install # 全局安装 Wrangler CLI npm install -g wrangler # 登录 Cloudflare wrangler logincopy_template.py 做了什么读取模板根目录的.gitignore规则做 gitignore 感知的复制跳过构建产物与依赖目录把README.md重命名为README_TEMPLATE.md方便你创建自己的 README完整保留源码、示例、测试与全部配置文件并完整保留 Context Engineering 工程结构——这后一点是关键因为模板自带的PRPs/、.claude/commands/才是整套流程的引擎。从 copy_template.py 源码看脚本还内置了模板完整性校验validate_template_integritycopy_template.py它会检查CLAUDE.md、.claude/commands/prp-mcp-create.md、.claude/commands/prp-mcp-execute.md、PRPs/templates/prp_mcp_base.md、PRPs/INITIAL.md、package.json、tsconfig.json、src/index.ts、src/types.ts等关键文件是否全部就位缺一即发出警告——可见「上下文组件」与代码同等重要。此外脚本支持--dry-run只预览要复制哪些文件与--force覆盖已存在的非空目录两个参数。复制完成后脚本会打印下一步指引编辑PRPs/INITIAL.md描述需求 → 用/prp-mcp-create生成 PRP → 用/prp-mcp-execute执行 PRP → 开发与部署。你将学到什么通过这个用例你将掌握用PRP 流程系统性构建复杂的 MCP Server为 MCP 开发定制专属的 Context Engineering方法遵循生产级 MCP Server 模板中的成熟模式实现GitHub OAuth 认证与基于角色的访问控制在Cloudflare Workers上部署并接入监控与错误处理。PRP 流程从需求到生产的六步法第 1 步就是上面的快速开始克隆、复制模板、装依赖、配好 Wrangler。第 2 步定义你的 MCP Server编辑 PRPs/INITIAL.md 描述你的具体需求。README 给出了一个天气服务的示例模板## FEATURE: We want to create a weather MCP server that provides real-time weather data with caching and rate limiting. ## ADDITIONAL FEATURES: - Integration with OpenWeatherMap API - Redis caching for performance - Rate limiting per user - Historical weather data access - Location search and autocomplete ## OTHER CONSIDERATIONS: - API key management for external services - Proper error handling for API failures - Coordinate validation for location queries仓库里 INITIAL.md 实际填写的是一个「用 Anthropic LLM 解析 PRP 并落库」的 Taskmaster 简化版需求在FEATURE中声明目标在ADDITIONAL FEATURES中列出 LLM 抽取、任务/文档/标签 CRUD、任务获取与列表等能力并在OTHER CONSIDERATIONS中给出关键约束如「不要用复杂正则用 LLM 解析 PRP」「Anthropic 模型与 API Key 必须走环境变量」「每个任务一个文件保持关注点分离」。注意事项部分往往决定了实现质量值得认真对待。第 3 步生成你的 PRP使用 MCP 专属的 PRP 命令生成完整的实施计划/prp-mcp-create INITIAL.md这个命令会做什么读取你的功能请求研究现有 MCP 代码库模式研究认证与数据库集成模式在PRPs/your-server-name.md生成一份完整的 PRP包含全部上下文、验证回路与逐步任务清单。PRP 生成后务必做全量验证在 PRP 框架下你应当作为流程的一部分参与进来确保所有上下文的质量——执行的产出上限就是你的 PRP。把/prp-mcp-create当作一个高质量起点而不是终点。第 4 步执行你的 PRP/prp-mcp-execute PRPs/your-server-name.md这个命令会做什么加载包含全部上下文的完整 PRP用 TodoWrite 创建详细实施计划按成熟模式逐个实现各组件运行全量验证TypeScript 编译、测试、部署确保 MCP Server 端到端可用。第 5 步配置环境变量# 创建环境文件 cp .dev.vars.example .dev.vars # 编辑 .dev.vars填入你的凭据 # - GitHub OAuth app 凭据 # - 数据库连接串 # - Cookie 加密密钥CLAUDE.md 提供了对应的生产环境做法——通过 Wrangler 以 Secret 形式注入避免明文入库wrangler secret put GITHUB_CLIENT_ID wrangler secret put GITHUB_CLIENT_SECRET wrangler secret put COOKIE_ENCRYPTION_KEY wrangler secret put DATABASE_URL wrangler secret put SENTRY_DSN第 6 步测试与部署# 本地测试默认端口 8787带 OAuth 的主服务入口为 http://localhost:8792/mcp wrangler dev --config your wrangler config (.jsonc) # 用 MCP Inspector 做集成测试 npx modelcontextprotocol/inspectorlatest # 连接到: http://localhost:8792/mcp # 部署到生产 wrangler deploypackage.json 中还预置了对应脚本npm run dev、npm run deploy、npm run type-check等价于tsc --noEmit、npm testvitest。开发前可用wrangler types从 Worker 配置生成 TypeScript 类型用npx prettier --write .统一格式、npx eslint src/做静态检查提交前记得先跑npm run type-check与wrangler dev --dry-run即wrangler deploy --dry-run只验证部署配置不实际发布。MCP 专属的 Context Engineering 组件本用例为 MCP 服务器开发定制了专门的上下文工程组件专属 Slash 命令位于模板的.claude/commands/目录copy_template.py 将其列为模板必备文件/prp-mcp-create—— 专门为 MCP Server 生成 PRP/prp-mcp-execute—— 带全量验证地执行 MCP PRP。它们是仓库根目录通用命令的 MCP 特化版本针对 MCP 开发模式做了定制。专属 PRP 模板模板 PRPs/templates/prp_mcp_base.md 是整套流程的核心上下文包它覆盖工具注册与认证的MCP 专属模式部署用的Cloudflare Workers 配置GitHub OAuth 集成模式数据库安全与 SQL 注入防护从 TypeScript 到生产的全链路验证回路。该模板开篇即声明四项核心原则Context is King注入所有必要的 MCP 模式、认证流、部署配置、Validation Loops提供从 TypeScript 编译到生产部署的可执行测试、Security First内置认证、授权与 SQL 注入防护、Production Ready包含监控、错误处理与部署自动化。Goal 小节用占位符[SPECIFIC MCP FUNCTIONALITY]引导你填写自己的工具清单What 小节把「MCP Server 特性 / 认证与授权 / 数据库集成 / 部署与监控」拆成可勾选的验收项Success Criteria例如MCP Inspector 验证通过、OAuth 全链路authorize → callback → MCP 访问走通、TypeScript 零错误编译、鉴权阻止未授权访问敏感操作、错误信息不泄露系统细节等。AI 文档目录PRPs/ai_docs/文件夹提供两份可直接注入上下文的参考文档mcp_patterns.md—— 核心 MCP 开发模式与安全实践claude_api_usage.md—— 如何在 LLM 驱动功能中接入 Anthropic API。模板架构一个生产级 MCP Server 长什么样实际仓库结构以当前仓库 use-cases/mcp-server 的实际目录为准模板提供如下分层结构use-cases/mcp-server/ ├── src/ # TypeScript 源码 │ ├── index.ts # 主 MCP Server标准版OAuth PostgreSQL │ ├── index_sentry.ts # 接入 Sentry 监控的版本 │ ├── types.ts # Props / 工具 Schema / 统一响应类型 │ ├── auth/ │ │ ├── github-handler.ts # GitHub OAuth 2.0 完整流程 │ │ └── oauth-utils.ts # 上游 token 交换、URL 构造、HMAC 签名 Cookie │ ├── database/ │ │ ├── connection.ts # PostgreSQL 单例连接池 │ │ ├── security.ts # SQL 校验、写操作识别、错误脱敏 │ │ └── utils.ts # withDatabase 带计时与错误处理的封装 │ └── tools/ │ └── register-tools.ts # 集中式工具注册中心 ├── examples/ # 示例工具勿编辑或 import 本目录 │ ├── database-tools.ts # Postgres MCP Server 工具创建与注册最佳实践 │ └── database-tools-sentry.ts # 上述工具 Sentry 监控的版本 ├── PRPs/ # Product Requirement Prompts │ ├── README.md │ ├── INITIAL.md │ ├── ai_docs/ │ │ ├── mcp_patterns.md │ │ └── claude_api_usage.md │ └── templates/prp_mcp_base.md ├── tests/ # vitest 单元测试fixtures / mocks / unit ├── wrangler.jsonc # Cloudflare Workers 主配置 ├── package.json / tsconfig.json / vitest.config.js ├── worker-configuration.d.ts # wrangler types 生成的类型 ├── copy_template.py # 模板复制脚本 └── CLAUDE.md # 实现指南与编码规范说明README 架构章节中描述的结构如src/github-handler.ts、src/database.ts平铺在 src 根下是模板早期形态的简化示意图当前仓库已演进为按auth/、database/、tools/分域的模块化布局功能完全对应。核心组件与关键特性特性说明关键文件 GitHub OAuth完整认证流程 基于角色的访问控制src/auth/github-handler.ts️ 数据库集成PostgreSQL 连接池 安全校验src/database/️ 模块化工具关注点分离 集中注册src/tools/register-tools.ts☁️ Cloudflare WorkersDurable Objects 全局边缘部署wrangler.jsonc 监控可选 Sentry 生产集成src/index_sentry.ts 测试从 TypeScript 到部署的全量验证tests/源码级纵深入口与 OAuth 认证链路MCP Server 入口src/index.tssrc/index.ts 展示了 MCP Server 与 OAuth Provider 的组合方式export class MyMCP extends McpAgentEnv, Recordstring, never, Props { server new McpServer({ name: PostgreSQL Database MCP Server, version: 1.0.0, }); async cleanup(): Promisevoid { await closeDb(); // Durable Object 关闭时回收数据库连接 } async alarm(): Promisevoid { await this.cleanup(); } async init() { // 按用户权限注册全部工具 registerAllTools(this.server, this.env, this.props); } } export default new OAuthProvider({ apiHandlers: { /sse: MyMCP.serveSSE(/sse), // SSE 传输 /mcp: MyMCP.serve(/mcp), // HTTP streamable 传输 }, authorizeEndpoint: /authorize, clientRegistrationEndpoint: /register, defaultHandler: GitHubHandler, tokenEndpoint: /token, });关键点MyMCP继承McpAgent同时暴露/mcpHTTP与/sseSSE双传输协议cleanup/alarm钩子确保 Durable Object 生命周期结束时数据库连接池被正确回收OAuthProvider将/authorize、/token、/register交给统一的 OAuth 2.1 服务器实现而自定义的 GitHub 认证逻辑由GitHubHandler接管。GitHub OAuth 完整流程src/auth/github-handler.tsgithub-handler.ts 实现了标准的 OAuth 2.0 授权码流程授权请求GET /authorize解析客户端认证请求后先检查该 client 是否已被 HMAC 签名 Cookie 标记为已批准已批准则直接重定向到 GitHub否则渲染批准对话框表单确认POST /authorize校验表单提交、提取 state并生成跳过下次批准对话框的 Set-Cookie 头重定向上游构造 GitHub 授权 URLhttps://github.com/login/oauth/authorizescope 为read:userstate 中携带 base64 编码的请求信息回调换 tokenGET /callback用临时 code 调用fetchUpstreamAuthToken换取 access tokenhttps://github.com/login/oauth/access_token拉取用户信息用new Octokit({ auth: accessToken })获取 GitHub 用户login、name、email完成授权调用OAUTH_PROVIDER.completeAuthorization把{ accessToken, email, login, name }作为props注入 token之后在MyMCP内部可通过this.props访问。这段流程把「GitHub 身份」与「MCP 客户端」绑定在一起用户在浏览器里完成 GitHub 授权后MCP 客户端拿到的 token 内嵌了用户属性工具层因此能感知「谁在调用」。Cookie 安全系统HMAC 签名模板采用 HMAC 签名的批准 Cookie 机制位于 src/auth/oauth-utils.ts签名用crypto.subtle.sign(HMAC, key, data)生成十六进制签名验证时用crypto.subtle.verify比对密钥来自COOKIE_ENCRYPTION_KEY环境变量。这样客户端一旦批准过某个 OAuth client后续访问可跳过重复的批准对话框同时 Cookie 内容无法被篡改。源码级纵深PostgreSQL 集成与数据库安全连接池管理src/database/connection.ts utils.ts数据库层采用单例连接池配合 Cloudflare Workers 的运行时约束// 单例连接池来自 CLAUDE.md 文档化的实现模式 export function getDb(databaseUrl: string): postgres.Sql { if (!dbInstance) { dbInstance postgres(databaseUrl, { max: 5, // Workers 环境最多 5 条连接 idle_timeout: 20, connect_timeout: 10, prepare: true, // 启用预处理语句 }); } return dbInstance; }src/database/utils.ts 的withDatabase封装了统一执行入口记录开始时间 → 执行操作 → 打印耗时日志出错时记录console.error后重新抛出让上层如 Sentry继续捕获。值得注意的设计取舍由于是连接池单个操作后不关闭连接连接自动归还池池在 Durable Object 关闭时才整体回收——这正是index.ts中cleanup钩子的职责。SQL 注入防护src/database/security.tssecurity.ts 提供三层防护源码中的实际实现比 README 示例更完整validateSqlQuery对空查询、危险模式drop、truncate、alter、create、grant、revoke、xp_cmdshell、sp_executesql等同时匹配「语句开头」与「分号拼接」两种形态做正则校验isWriteOperation判断语句是否以insert、update、delete、create、drop、alter、truncate、grant、revoke、commit、rollback开头用于在只读工具中拦截写操作formatDatabaseError错误信息脱敏——凡包含password、timeout、connection等敏感字样的原始错误一律替换为不泄露细节的用户友好提示。源码注释也诚实标注了边界这类关键字校验是simple check生产环境应使用参数化查询。本模板的策略是双保险——工具层用validateSqlQuery做第一道闸db.unsafe执行时依赖库层参数化能力权限上再以executeDatabase只对白名单用户开放作为最终防线。基于角色的访问控制examples/database-tools.tsexamples/database-tools.ts 定义工具权限模型const ALLOWED_USERNAMES new Setstring([ // 在此添加可执行数据库写操作的 GitHub 用户名 coleam00 ]);三个数据库工具按权限分级listTables所有已认证用户单条 SQL 查询information_schema.columns聚合出每张表的列名、类型、可空性、默认值先探查结构再查询queryDatabase所有已认证用户只读先过validateSqlQuery再用isWriteOperation拦截写语句仅放行 SELECT 等只读操作executeDatabase仅特权用户只有ALLOWED_USERNAMES中的 GitHub 用户名才能注册该工具支持 INSERT/UPDATE/DELETE/DDL返回结果会明确标注⚠️ Database was modified与执行人。权限判断发生在工具注册期if (ALLOWED_USERNAMES.has(props.login))才调用server.tool(...)而非调用期这是模板刻意强调的安全模式特权工具对普通用户根本不可见。模块化工具注册src/tools/register-tools.tsregister-tools.ts 是集中注册中心它 import 各功能域的工具模块并逐一调用注册函数把server、env、props传给每个模块。新增工具的标准路径是新建工具模块如src/tools/your-feature-tools.ts导出registerYourFeatureTools(server, env, props)在 types 文件中定义 Zod 输入校验 Schema按 examples 的模式实现带错误处理的工具 handler在registerAllTools中追加注册注释里已留好registerAnalyticsTools、registerReportingTools等占位示例更新文档。所有工具必须返回 MCP 兼容的标准响应对象并使用 Zod 做输入校验——例如queryDatabase的 Schema 要求sql非空且必须以select开头limit为正整数且上限 1000错误则统一返回isError: true的文本内容权限不足、写操作被拦截、数据库异常各有结构化错误消息。部署、监控与可观测性Cloudflare Workers 配置wrangler.jsoncwrangler.jsonc 声明了运行时所需的一切main: src/index.tsSentry 版本需改为src/index_sentry.tscompatibility_date: 2025-03-10compatibility_flags: [nodejs_compat]Durable ObjectsMyMCP类绑定为MCP_OBJECT配套migrations中的new_sqlite_classes声明tag: v1——MCP Agent 的状态持久化依赖它KVOAUTH_KV命名空间用于 OAuth state 与会话管理dev.port: 8792本地开发时 MCP 入口即http://localhost:8792/mcp。技术栈方面模板基于modelcontextprotocol/sdk官方 MCP TypeScript SDK、agents/mcpCloudflare Workers MCP Agent 框架、workers-mcpWorkers 传输层、cloudflare/workers-oauth-providerOAuth 2.1 服务端实现外加honoHTTP 路由、octokitGitHub API、postgresPostgreSQL 驱动、zod校验。客户端接入Claude Desktop本地开发与生产部署均可通过mcp-remote接入CLAUDE.md 文档化{ mcpServers: { database-mcp: { command: npx, args: [mcp-remote, http://localhost:8792/mcp], env: {} } } }生产环境把地址换成https://your-worker.workers.dev/mcp即可。Sentry 监控可选src/index_sentry.ts 提供了带全量埋点的版本通过sentry/cloudflare实现100% 采样率的分布式追踪、每次 MCP 工具调用以mcp.tool/name为 span 名做 traceattributes 携带工具参数、把 GitHub 用户username/email绑定到事件、错误统一走handleError返回带事件 ID 的用户友好消息。启用方式# 开发环境 echo SENTRY_DSNhttps://your-dsnsentry.io/project .dev.vars echo NODE_ENVdevelopment .dev.vars wrangler dev --config wrangler.jsonc # 确保 main src/index_sentry.ts # 生产环境 wrangler secret put SENTRY_DSN wrangler secret put NODE_ENV # 设为 production wrangler deploy标准版src/index.ts则以console.log/console.error输出结构化日志数据库操作耗时、用户认证事件User authenticated: login (name)、工具调用与失败记录等。测试与验证回路模板的验证回路覆盖多个层级TypeScript 编译检查npm run type-check/npx tsc --noEmit→ 单元测试npx vitest→ MCP Inspector 集成测试npx modelcontextprotocol/inspectorlatest连接http://localhost:8792/mcp→ 部署验证wrangler deploy --dry-run。仓库中的 tests/ 目录提供了 vitest 单测骨架覆盖数据库安全security、数据库工具database-tools、响应辅助函数response-helpers等模块并配套 auth/database/mcp 的 fixtures 与 mocks——这正是prp_mcp_base.md中Validation Loops原则的落地。CLAUDE.md 还给出两条硬性纪律NEVER 把密钥或环境变量提交进仓库、NEVER 跳过 Zod 输入校验ALWAYS 使用 TypeScript strict 模式、ALWAYS 用 Wrangler CLI 做开发与部署。关键文件速查用途文件用例总览与六步流程use-cases/mcp-server/README.md实现指南与编码规范use-cases/mcp-server/CLAUDE.md需求定义模板use-cases/mcp-server/PRPs/INITIAL.mdMCP 专属 PRP 模板use-cases/mcp-server/PRPs/templates/prp_mcp_base.mdAI 参考文档mcp_patterns.md / claude_api_usage.md主入口OAuth 双传输use-cases/mcp-server/src/index.tsGitHub OAuth 流程use-cases/mcp-server/src/auth/github-handler.ts数据库安全校验use-cases/mcp-server/src/database/security.ts连接池与执行封装use-cases/mcp-server/src/database/utils.ts工具注册中心use-cases/mcp-server/src/tools/register-tools.ts数据库工具示例use-cases/mcp-server/examples/database-tools.tsWorker 部署配置use-cases/mcp-server/wrangler.jsonc模板复制脚本use-cases/mcp-server/copy_template.py成功指标与落地建议按本流程走完你会获得快速实现最少迭代次数拿到可用 MCP Server、生产就绪安全认证 监控 错误处理、可扩展架构关注点分离 模块化设计、全量验证从 TypeScript 到生产部署。改进方向README 的贡献建议添加更多 MCP Server 示例展示不同模式、用更全面的上下文增强 PRP 模板、改进验证回路以更好捕获错误、沉淀边界情况与常见陷阱。最终目标是通过完备的 Context Engineering让 MCP Server 开发变得可预测、可成功——从copy_template.py复制模板、配置环境、在 PRPs/INITIAL.md 定义需求开始然后用/prp-mcp-create生成、/prp-mcp-execute执行你的 PRP交付你的第一个生产级 MCP Server。【免费下载链接】context-engineering-introContext engineering is the new vibe coding - its the way to actually make AI coding assistants work. Claude Code is the best for this so thats what this repo is centered around, but you can apply this strategy with any AI coding assistant!项目地址: https://gitcode.com/gh_mirrors/co/context-engineering-intro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
