Microsoft Forms API

msforms-api

原生支持 AI 的 Microsoft Forms 自动化工具，可用于检查表单、解析分支逻辑、验证答案、上传文件、提交回复并保存回复链接。

可将其用作：

1. MCP 服务，供 AI Agent 和编辑器使用——推荐大多数用户采用。
2. Agent 技能，由 CLI 支持，适用于能够运行 shell 命令的 Agent。
3. CLI，用于脚本和终端工作流。
4. TypeScript SDK，用于自定义应用。

说明

此项目由 GitHub Copilot App 使用 GPT-5.6 Sol 生成，采用 Extra High 推理级别和 Autopilot 模式。

警告

此项目使用了通过逆向工程还原的 Microsoft Forms Web API。Microsoft 未对这些端点提供文档或保证。它们可能在不另行通知的情况下发生变更。 此项目与 Microsoft 无关联，也未获得 Microsoft 背书。

快速开始

前置条件

• Node.js，版本 22 或更高。
• Google Chrome 或 Microsoft Edge。如果两者均不可用，将自动安装 Playwright Chromium。

安装为 Agent 技能

CLI 技能会指导 Agent 检查分支逻辑、准备并验证答案、上传获授权的文件，并要求在提交前获得明确批准：

npx -y skills add Maxim-Mazurok/msforms-api

安装程序会检测 Claude Code、Cursor、GitHub Copilot 和 Codex 等受支持的 Agent，然后询问技能的安装位置。选择全局范围即可在所有项目中使用。

该技能通过 npx 运行 msforms-api，因此无需全局安装软件包或配置 MCP。它是 MCP 服务的另一种使用方式；两者使用相同的 CLI 和 SDK 行为。

在 AI 工具中安装

点击上方的安装徽章，或使用此 MCP 配置。对于 Cursor，请将其保存为 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "microsoft-forms": {
      "command": "npx",
      "args": ["-y", "-p", "msforms-api@latest", "msforms-api-mcp"]
    }
  }
}

首次使用时，请让你的 Agent 对 Microsoft Forms 进行身份验证。系统会打开浏览器供你登录，之后的操作会复用持久会话。

试试：

检查此 Microsoft Form，并说明每个问题、验证规则、文件上传规则和分支：https://forms.cloud.microsoft/...

Agent 可以准备并验证答案，但不会提交。提交操作使用单独的破坏性 MCP 工具，并且需要明确确认。

code --add-mcp '{"name":"microsoft-forms","command":"npx","args":["-y","-p","msforms-api@latest","msforms-api-mcp"]}'

code --add-mcp '{"name":"microsoft-forms","command":"npx","args":["-y","-p","msforms-api@latest","msforms-api-mcp"]}'

claude mcp add microsoft-forms -- npx -y -p msforms-api@latest msforms-api-mcp

Agent 可以做什么

• 读取完整的表单元数据，包括原始 API 对象。
• 了解问题类型、选项、必填状态和文本验证规则。
• 通过稳定的问题标识符解析选项分支。
• 检查矩阵行及其共用选项。
• 检查文件数量、大小和扩展名限制。
• 验证并序列化答案，但不提交。
• 通过经过身份验证的 Forms 前端上传文件。
• 仅在明确确认后提交。
• 在已登录的帐户中保存和列出回复链接。

MCP 工具

forms_submit 标记为破坏性且非幂等。它使用 MCP v2 多轮征询。用户拒绝或未明确确认时，提交代码绝不会运行。

以下位置还提供了涵盖多个工作流的安全指南：

npx -y -p msforms-api@latest msforms-api guide

CLI

无需全局安装即可运行：

# Sign in once
npx -y -p msforms-api@latest msforms-api auth

# Inspect a form
npx -y -p msforms-api@latest msforms-api inspect \
  --form 'https://forms.cloud.microsoft/Pages/ResponsePage.aspx?id=...'

# Validate answers without submitting
npx -y -p msforms-api@latest msforms-api validate \
  --form 'https://forms.cloud.microsoft/Pages/ResponsePage.aspx?id=...' \
  --answers @answers.json

# Submit only when intended
npx -y -p msforms-api@latest msforms-api submit \
  --form 'https://forms.cloud.microsoft/Pages/ResponsePage.aspx?id=...' \
  --answers @answers.json \
  --save-response \
  --confirm

经常使用 CLI 的用户可以全局安装：

npm install --global msforms-api
msforms-api auth

每条命令都会输出 JSON。添加 --compact 可生成单行输出。

身份验证和本地数据

身份验证会打开可见的浏览器，并将其配置文件存储在：

~/.msforms-api/browser-profile

SDK 使用该配置文件获取作用域受限的 Forms Cookie、防伪令牌和会话元数据。它不会打印或返回这些凭据。常规读取和提交使用直接的 Forms HTTP 请求。文件上传需要浏览器辅助，因为 Forms 前端负责管理 SharePoint 授权。

覆盖配置文件或浏览器：

msforms-api --profile ~/.config/my-forms-profile --browser chrome auth

MCP 环境变量：

删除 ~/.msforms-api/browser-profile 即可移除本地会话。

答案格式

答案使用 forms_inspect 返回的确切问题 ID 作为键。

矩阵答案使用每行问题 ID，而不是矩阵组 ID。

{
  "text-question-id": "Ada Lovelace",
  "multiple-choice-question-id": ["Desktop", "Laptop"],
  "date-question-id": "2026-08-12",
  "ranking-question-id": ["Branching", "Uploads", "Ratings"],
  "matrix-row-question-id": { "label": "Agree" },
  "file-question-id": [
    {
      "name": "document.pdf",
      "uploadSessionUrl": "https://...",
      "link": "https://...",
      "badgerToken": null,
      "time": 1786492949627,
      "status": 3,
      "id": "sharepoint-item-id"
    }
  ]
}

SDK

npm install msforms-api

import { MicrosoftFormsClient } from "msforms-api";

const client = new MicrosoftFormsClient();
const form = await client.getForm(formUrl);

const answers = {
  [form.questions[0].id]: "Example answer",
};

const validation = await client.validateAnswers(formUrl, answers);
if (!validation.valid) {
  throw new Error(JSON.stringify(validation.issues));
}

const submission = await client.submitResponse(formUrl, answers, {
  saveResponse: true,
});

if (submission.saveResponseStatus === "failed") {
  console.error(submission.saveResponseError);
  await client.saveResponse(
    formUrl,
    submission.responseId,
    submission.submitDate,
  );
}

submitResponse() 在 SDK 层直接执行。使用 SDK 的应用必须自行实现用户确认边界。CLI 需要 --confirm；MCP 需要引导式询问。

submissionStatus: "submitted" 或返回的 responseId 表示永久响应已创建。请求保存响应链接可能会独立失败。在这种情况下，saveResponseStatus 为 "failed"，提交详情仍保留在结果中，调用方不得再次提交。只能重试幂等的 saveResponse() 操作。

表单结构

规范化的表单模型包括：

• ID、标题、副标题、顺序、类型和必填状态。
• 选项标签和 branchTargetId 值。
• 继承选项的矩阵行。
• 文本验证边界和规则。
• 文件上传限制。
• 已解析的表单设置。
• 完整的原始表单和问题对象，以实现向前兼容。

分支示例：

{
  "id": "source-question-id",
  "type": "Question.Choice",
  "options": [
    {
      "label": "Yes",
      "branchTargetId": "target-question-id"
    }
  ]
}

forms_validate 返回可见的问题 ID、问题，以及确切序列化的答案数组。分支逻辑跳过的问题会被省略。

工作原理

浏览器引导程序会公开防伪令牌、服务器会话 ID、表单所有者租户和用户、答题者租户和用户，以及表单预取 URL。客户端会将这些数据与作用域限定的 Forms Cookie 结合，用于直接请求。

观察到的端点系列：

GET  /formapi/api/{tenant}/users/{owner}/light/runtimeForms('{formId}')
POST /formapi/api/{tenant}/users/{owner}/forms('{formId}')/responses
POST /formapi/api/{tenant}/users/{owner}/runtimeForms('{formId}')/questions('{questionId}')/CreateUploadSession
POST /formapi/api/{ownerTenant}/users/{owner}/saveResponseLink
GET  /formapi/api/{responderTenant}/users/{responder}/getResponseLinks

规范化模型会保留原始对象，以便在此软件包提供一流支持之前，仍可检查新引入的 Forms 属性。

限制

• API 为私有 API，可能会发生变化。
• 文件上传目前要求上传问题在渲染的分支中可见。
• 身份验证依赖 Microsoft Forms 网页登录行为。
• 此软件包用于正当的表单自动化。请遵守表单所有者的要求、租户政策、隐私要求和适用法律。

开发

请参阅 CONTRIBUTING.md。

npm install
npm run type-check
npm test
npm run format-check
npm run spell-check
npm run build

许可证

MIT