企业官网建设流程全解析

ms-365-mcp-server 是一个通过 Microsoft Graph API 操作 Microsoft 365 的 Model Context Protocol（MCP）服务器，为 AI 助手提供 300+ 个邮件、日历、OneDrive、Teams 等工具。本文是一份面向贡献者的完整开发者指南：从克隆仓库、用npm run generate生成 Graph API 客户端，到用npm run verify一键通过全部质量检查，带你走通首个 PR 的完整流程。🚀

一、3分钟了解项目结构

开始贡献前，先看清代码布局，心里有数再动手：

二、环境准备：Node.js 与依赖安装

最快配置方法如下，三条命令搞定：

# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/ms/ms-365-mcp-server cd ms-365-mcp-server # 2. 安装依赖（需要 Node.js >= 20，推荐版本） npm install # 3. 本地试跑 npm run dev

版本注意（来自 package.json 与 CI 配置）：

• 官方推荐Node.js 20+；最低要求 Node 18（CI 使用 18 / 20 / 22 三个版本做矩阵测试）。
• 测试框架 Vitest 4 需要 Node 20+，所以在 Node 18 上无法跑npm test。
• 如需自定义 Azure 应用认证，可参考 .env.example 创建.env文件。

三、npm run generate：Graph API 客户端是怎么生成的

这是贡献本项目最特殊的一步。与"改几行代码"不同，这里的工具接口来自代码生成，理解它是贡献的前提。

npm run generate实际执行 bin/generate-graph-client.mjs，对 Graph 的v1.0 和 beta 两个版本分别执行 3 个步骤：

1. 📥 下载 OpenAPI 规范—— 从微软拉取 Graph API 的 OpenAPI 描述文件，保存到openapi/目录；
2. 🔧 裁剪规范—— 对照 src/endpoints.json 中声明的工具，把原始规范裁剪成只包含所需端点的精简版（原始规范高达 45MB）；
3. 🚀 生成客户端代码—— 用 openapi-zod-client 生成带 Zod 校验的 TypeScript 客户端，输出到 src/generated/client.ts 与 src/generated/client-beta.ts。

为什么这样做？src/generated/README.md 记录了三代方案演进：从"AI 映射文档"到"直接解析 45MB 完整规范"，最终定型为"精简规范 + 生成静态客户端"——启动更快、包体更小、类型安全。

⚠️关键规则：src/generated/下的文件由脚本生成并已提交进仓库。ESLint 配置（eslint.config.js）明确忽略该目录和bin/，所以不要手工修改生成代码；正确姿势是改输入（endpoints.json），再重新生成。

典型场景：当你新增了一个 Graph 端点工具后，必须重跑npm run generate，否则客户端里没有对应的请求函数。

四、本地开发：运行、调试与 MCP Inspector

改完代码，本地验证有这几种方式：

# stdio 模式直接运行（配合 Claude 等 MCP 客户端） npm run dev # HTTP 模式 + 文件变更自动重启 npm run dev:http # 打开 MCP Inspector 图形界面，交互式调试工具调用 npm run inspector

npm run inspector是推荐的第一步：它会在浏览器里列出所有工具，可直接填入参数观察返回结果，比盯着日志调试高效得多。调试 OAuth 流程时可参考 README 中"Setting up Azure AD for OAuth Testing"一节。

五、提交前必做：npm run verify 一键质量检查

一键安装检查步骤其实就一条命令。npm run verify串联了 6 道关卡，全部通过才算合格：

npm run verify

为什么要跑typecheck？CI 工作流 里有一句注释解释得很直白：tsup 只剥离类型并不检查类型，光靠build抓不住类型错误。

好消息是：本地npm run verify通过的 ≈ CI 通过的——CI 在 Node 18/20/22 矩阵上执行的正是同一组检查（Node 18 额外做产物冒烟测试）。

遇到格式问题时别手动对齐，用自动修复更省心：

npm run format # Prettier 自动排版 npm run lint:fix # ESLint 可修复项自动处理

六、常见贡献路径速查表 🧭

给新贡献者的 3 条建议：

1. 先跑通再动手：克隆后先执行npm install、npm run generate、npm run verify，确认本地环境全绿；
2. 生成代码永远走generate：endpoints.json是"单一事实来源"，改它、重新生成、验证，不要碰src/generated/；
3. 提交前必跑verify：README.md 的 Contributing 章节明确要求所有 PR 先通过它——这也是项目对代码质量的底线。

结语

掌握npm run generate到npm run verify这条主线，你就具备了为 ms-365-mcp-server 贡献代码的完整能力：改endpoints.json扩展工具面，改src/打磨核心逻辑，用一条verify对齐 CI 标准。🎉 祝你的首个 PR 顺利合入！