AI目标规划服务器

展开It MCP服务器

将AI助手连接到 展开它 --使用人工智能生成的计划、代理辅助的澄清、丰富的计划导入、个人进度跟踪、队列分析和技能评估来创建目标。

为想要使用的平台（学院、LMS工具、教练应用程序）而构建 展开它 作为它们的执行层。三个自主级别：完全自主、半自动审查，或通过人工智能丰富导入自己的步骤。使用人工智能验证的MCQ生成技能评估，对其进行评分，并根据结果自动创建有针对性的学习路径。使用自定义元数据标记目标，以跟踪和分析整个队列。

快速开始

npx @unfoldit/mcp-server

或全局安装：

npm install -g @unfoldit/mcp-server

配置

设置以下环境变量：

克劳德桌面/克劳德代码

添加到MCP配置(claude_desktop_config.json 或 .mcp.json):

{
  "mcpServers": {
    "unfoldit": {
      "command": "npx",
      "args": ["@unfoldit/mcp-server"],
      "env": {
        "UNFOLD_API_KEY": "unfold_sk_..."
      }
    }
  }
}

光标

增添 .cursor/mcp.json 在您的项目中：

{
  "mcpServers": {
    "unfoldit": {
      "command": "npx",
      "args": ["@unfoldit/mcp-server"],
      "env": {
        "UNFOLD_API_KEY": "unfold_sk_..."
      }
    }
  }
}

API关键范围

您的API密钥需要特定的作用域，具体取决于您使用的工具：

评估范围是可选的。请您的组织所有者在API密钥设置中启用它们。

可用工具（13）

create_goal

使用AI生成的计划创建目标。代理使用您提供的上下文自动回答澄清问题。集 auto_respond=false 在计划生成之前审查代理建议。将目标标记为 metadata 对整个队列进行分组和分析。

输入：

• title （必填）--目标标题

• description --目标描述。更多细节产生更好的AI计划

• context --为代理提供丰富的上下文：

  • tech_stack --例如[“Python”、“React”]
  • team_size --例如3
  • timeline --例如“3个月”、“2026年第三季度”
  • constraints --例如“每周2小时”
  • experience_level --例如“初级”、“高级”
  • industry --例如“金融科技”
  • additional_notes --任何其他上下文

• auto_respond --true（默认）：代理回答所有问题。false：返回问题和建议以供审阅

• clarification_answers --按问题ID预设答案（代理跳过这些答案）

• goal_context --“个人”或“专业”（默认：“专业”）

• priority --“低”、“中”或“高”（默认值：“中”）

• claim_expires_in_days --索赔链接有效期（默认值：30）

• progress_share --生成可嵌入的进度链接（默认值：true）

• metadata --用于分析分组的自定义键值标签，例如。 { cohort: "spring-2026", track: "frontend" }

• category --资源类别提示：“学习”、“health_adhd”或“一般”。如果没有提供，则从目标标题和描述中自动检测到。确定在将资源附加到子步骤时使用哪些源和搜索策略。

• resource_world --覆盖此目标的资源发现：

  • preferred_sources --要优先考虑的源域，例如。 ["coursera.org", "docs.python.org"]
  • excluded_sources --要抑制的源域
  • youtube_playlists --用于从中提取资源的YouTube播放列表ID
  • lms_search_endpoint --自定义LMS搜索端点URL
  • content_policies -- { require_verified_sources, show_disclaimer, disclaimer_text }

• assessment （自v0.7.0起）——规划者用于偏置步骤选择的结构化评估输入。受到歧视 assessment_type:

  • skill_proficiency v1--放下 score_skill_assessment 直接回应。规划者优先考虑薄弱环节，压缩强环节，并锚定步骤 work_item_context.
  • clinical_intake v1——ADHD/指导/临床背景。线材形状已锁定；提示生成器当前已被截断并返回 assessment_type_not_supported 直到真正的合作伙伴驱动它。敏感型——需要每个组织都启用超级管理员。
  • general v1——捕获所有不符合任何类型形状的评估数据。被视为柔和的暗示；仅 constraints 被视为硬性限制。

  看 指南_评估_计划_MCP 了解规范的端到端演练。

• request_id （从v0.8.0开始，可选，幂等密钥）——在5分钟的窗口内，两个 create_goal 呼叫相同 request_id 返回相同的目标并声明链接，而不是创建新的链接。看 幂等性 下面是规则。忽略每次通话都获得新的目标（默认）。

退货： goalId, claimLink, claimToken, progressLink, planGenerationStatus, questions （如果auto_response＝false）， agentAnswersUsed, idempotentReplay （自v0.8.0以来）， claimStatus （自v0.8.0以来）， warnings （始终存在，无时为空）

get_goal_status

获取目标的当前状态和完整的分步细节。当计划准备就绪时，返回单个步骤数据（时间戳、花费的时间、阻塞器计数、子步骤进度）。

输入：

• goal_id （必填）--create_goal中的目标ID

退货： 目标状态， progress, resourceCategory, steps[] （当计划准备就绪时，提供每一步的详细信息）， metadata, claimCreatedAt, claimedAt, assignedTo, agentAnswersUsed

get_analytics

API创建的所有目标的汇总队列分析。返回KPI、有风险的学习者、阶梯级下降漏斗，以及按元数据维度或资源类型进行的可选细分。

输入：

• group_by --按（例如“跟踪”、“队列”、“部门”）细分完成率的元数据关键字
• inactive_days --将这几天内没有步骤活动的目标标记为有风险（默认值：7）
• include_funnel --包括逐步完成漏斗（默认值：true）
• include_resources --按类型和来源包括资源参与（默认值：false）
• metadata --筛选到特定的队列或细分市场，例如。 { cohort: "spring-2026" }
• date_from --ISO日期（YYYY-MM-DD）。仅包括在此日期或之后创建的目标
• date_to --ISO日期（YYYY-MM-DD）。仅包括在此日期或之前创建的目标

退货：

• totalGoals, activeGoals, completedGoals, blockedGoals, completionRate, avgDaysToComplete
• claimsTotal, claimsClaimed, claimsPending, claimsExpired, avgHoursToClaim
• atRiskCount, atRiskGoals[] （goalId、标题、元数据、非活动天数、进度百分比）
• completionByDimension[] （当group_by被设置时）
• stepFunnel[] （stepOrder、stepTitle、完成率、平均完成时间）
• resourceEngagement[] （当include_resources=true时）

get_clarification

使用代理建议的答案和置信水平获取未决澄清问题。使用后 create_goal 和 auto_respond=false.

输入：

• goal_id （必填）--create_goal中的目标ID

退货： 问题与 agentAnswer, agentConfidence （高/中/低/回退）， agentSource

提交澄清

提交澄清问题的答案并触发计划生成。对于要覆盖的问题，请提供自己的答案。其余部分保留代理建议。

输入：

• goal_id （必填）--create_goal中的目标ID
• answers --您的答案由问题ID键入（仅包括覆盖）
• accept_agent_answers --接受代理对未覆盖问题的建议（默认值：true）

退货： goalId, status, planGenerationStatus, agentAnswersUsed

导入计划

导入一个包含步骤和子步骤的预先制定的计划。完全跳过澄清。人工智能通过依赖关系、关键路径、持续时间估计、严重性、复杂性和速赢标志丰富了步骤。

输入：

• title （必填）--目标标题
• description --目标描述
• steps （必填）--步骤数组，每个步骤包含：
  • title （必填）--步骤标题
  • description --步骤说明
  • substeps --可选的子步骤数组，包括标题、描述、类型（研究/工作/决策/验证）
• enrich --运行AI富集（默认值：true）。将0学分设置为false
• enrich_options --控制要运行的富集功能：
  • dependencies, critical_path, duration_estimates, severity, complexity, quick_wins, resources
• goal_context --“个人”或“专业”（默认：“专业”）
• priority --“低”、“中”或“高”（默认值：“中”）
• claim_expires_in_days --索赔链接有效期（默认值：30）
• progress_share --生成可嵌入的进度链接（默认值：true）
• metadata --用于分析分组的自定义键值标签，例如。 { cohort: "spring-2026", track: "backend" }

退货： goalId, planId，丰富 steps[] 使用元数据， claimLink

列表_来源_类别

列出目标分类的可用资源类别。返回每个类别的活动提供者、内容安全策略和免责声明文本。使用此功能构建自适应UI，或在创建目标之前发现哪些类别可用。

输入： 无

退货： 类别数组，每个类别都有 id, name, description, activeProviders, showDisclaimer, disclaimerText

list_goals

使用可选过滤器列出组织中的所有目标。使用 metadata 为了过滤到队列， category 按目标类型划分， assigned_email 查找特定的学习者，或 inactive_days 在不进行全面分析的情况下找到有风险的目标。

输入：

• status --按目标状态筛选（草稿、正在进行中、已完成、已阻止、已暂停）
• claim_status --按索赔状态筛选（未索赔、已索赔、已过期、已撤销）
• category --按资源类别筛选（学习、健康、一般）。使用此方法将ADHD目标与混合队列中的学习目标区分开来。
• metadata --按“key=value”格式的元数据标签过滤，例如。 ["track=frontend", "cohort=spring-2026"]
• assigned_email --仅返回分配给此学员电子邮件的目标
• inactive_days --仅返回过去N天内没有步骤活动的目标（1-365）
• include_steps （自v0.9.1以来）--包括每个步骤的详细信息(steps[])对于计划已经准备好的每个目标。默认情况下关闭以保持列表有效载荷精简；设置为true以呈现不带 get_goal_status 按目标呼叫。
• limit --最大结果（默认值：50，最大值：100）
• offset --分页偏移

退货： 目标状态数组 progress, resourceCategory, metadata, claimCreatedAt, claimedAt.何时 include_steps=true，每个计划好的目标也都有 steps[] --台阶形状与 get_goal_status （时间戳、花费的时间、阻断器计数、子步骤计数）。目标仍在产生回报 steps: null步骤没有分页；每个目标返回完整的步骤列表。

撤销索赔

使索赔链接无效，因此无法再使用。

输入：

• claim_token （必需）--声明链接URL中的令牌

删除目标

删除通过API创建的目标。主要用例：学习者重新进行技能评估后，致电 create_goal 随着新 suggested_goal_seed 然后 delete_goal 在过时的目标上，仪表板显示当前目标，而不是重复的目标。默认软删除（可恢复）；集 hard_delete=true 永久删除该行。作用域为api创建的目标——无法删除用户在webapp UI中创建的目标。

输入：

• goal_id （必填）--目标的UUID（ goalId 由create_goal返回）
• hard_delete --如果为真，则永久删除该行，而不是软删除。默认值为false。

生成技能评估

为学习者生成技能水平评估（MCQ）。问题在返回之前是人工智能生成和验证的（结构+语义检查）。返回已签名的 assessment_token 对学习者的答案进行评分。

输入：

• work_item_context （必填）——学习者正在准备的工作项目：
  • title （必填）--工作项标题
  • description --工作项描述（最多2000个字符）
  • domain_tags --问题锚定标签
• skill （必填）-评估技能（例如“Python”、“SQL”、“项目管理”）
• target_proficiency （必填）——学习者应达到的等级：“初级”、“低级”、“中级”、“高级”
• num_questions （必填）--要生成的MCQ数量（3-20）
• difficulty_mix --分布为 {easy, medium, hard} 浮点数的总和为1.0。违约： {easy: 0.2, medium: 0.5, hard: 0.3}
• band_thresholds --自定义熟练程度范围。默认值：初学者[0,10]，低[11,50]，中[51,85]，高[86100]
• language --ISO语言代码（默认值：“en”）
• request_id （必填）——标识键。相同的request_id返回相同的评估。

退货： assessment_token, questions[] （茎、选项、难度、技能面）， band_map, max_raw_score, target_band, model_meta

需要范围： assessment:generate

分数_技能_评估

使用签名对提交的评估进行评分 assessment_token 从 generate_skill_assessment.返回学习者的熟练程度等级、差距与目标以及每个问题的结果。当学习者表现不佳时，包括 suggested_goal_seed 你可以通过 create_goal 创建有针对性的学习路径。

输入：

• assessment_token （必填）--generate_skill-assessment中的签名令牌
• answers （必填）--数组 {question_id, selected_option_id} （至少一个）
• band_thresholds --可选覆盖熟练程度范围（默认为令牌中嵌入的阈值）
• request_id （必填）--标识键

退货： raw_score, max_raw_score, raw_pct, band, target_band, gap_bands, per_question[], per_facet[] （每个子技能的服务器端聚合 total, correct, raw_pct, classification: weak | strong | mixed), weak_facets[], strong_facets[], facet_coverage (full | partial | difficulty_fallback), recommended_action （none/create_unfold_goal）， suggested_goal_seed

链条提示： 此响应与形状兼容 create_goal的新 assessment 领域（技能效率v1）。将其放入，并添加三个标题字段(assessment_type: "skill_proficiency", schema_version: "v1", assessed_at: <ISO timestamp>)规划者直接使用它。没有客户端连接逻辑，没有阈值调整。

需要范围： assessment:score

获取评估能力

获取技能评估的支持参数。在致电之前使用此功能进行反思 generate_skill_assessment。不需要输入参数。

退货： schema_version, supported_languages, min_questions, max_questions, supported_proficiency_bands, default_band_thresholds, default_difficulty_mix, open_domain, token_ttl_seconds

需要范围： assessment:read_capabilities

幂等性

可用时间： v0.8.0.

create_goal 接受可选 request_id 因此，合作伙伴可以安全地重试，而不会产生重复的目标。

规则

1. 将密钥范围限定为一个逻辑操作。 “逻辑运算”是一个学习者/一个注册。根据您自己的每个学习者标识符构建密钥，例如：
   复制

   request_id = "enrollment:42:learner:7"
   request_id = "course:python-101:user:abc-123"
   

2. 重试时重复使用密钥，而不是新学习者。 如果网络故障或进程重启导致您为同一学习者重新发送相同的呼叫，请使用相同的 request_id。如果您正在为不同的学习者创建目标，请生成一个新密钥。
3. 不要从身体中取出钥匙。 参加同一课程的两名学习者将产生相同的标题/描述/评估有效载荷。如果你重用一个身体衍生的密钥，第二个学习者将收到第一个学习者已经声明的声明链接。
4. 没有a request_id每一个召唤都会创造一个新的目标。 这是默认设置，始终是安全的。

缓存窗口

与同一租户进行两次通话+ request_id 在5分钟内返回相同的响应。5分钟后，密钥从缓存中掉出来，一个新的调用创建了一个新目标。今天，在pod重启和水平扩展方面尽最大努力；将窗口视为重试助手，而不是重复数据删除保证。

检测重播

响应中的两个新字段告诉您发生了什么：

• idempotentReplay: true --此响应是从缓存中提供的。之前有过同样的电话 request_id 产生了这个目标。
• claimStatus: "unclaimed" | "claimed" | "expired" | "revoked" --基础声明令牌的当前状态，每次重播时从数据库中刷新。 null 关于一个新的创造（隐含地“无人认领”）。

处理重试时对此进行分支：

const result = await create_goal({ title, request_id: enrollmentKey });

if (result.idempotentReplay && result.claimStatus && result.claimStatus !== "unclaimed") {
  // The link was already consumed by the original recipient. Don't
  // forward it again -- prompt the human or open a support ticket
  // depending on your flow.
} else {
  // Safe to forward the claimLink to the learner.
}

运作原理

第1级——半自动（审查代理商建议）

1. 呼叫 create_goal 和 auto_respond=false 以及你的背景
2. 使用客服建议的答案和置信度回复问题
3. 审查建议，推翻你不同意的任何建议
4. 呼叫 submit_clarification 触发计划生成
5. 投票 get_goal_status 直到 planGenerationStatus 已“完成”

第2层——全自动（代理处理一切）

1. 呼叫 create_goal 带上下文（auto_response默认为true）
2. 代理使用您的上下文+用户历史记录回答所有澄清问题
3. 计划在后台生成（15-30s）
4. 立即获取索赔链接——将其发送给您的用户
5. 投票 get_goal_status 完成和 agentAnswersUsed 透明度

第3层——导入（自带步骤）

1. 呼叫 import_plan 用你的步骤和子步骤
2. 人工智能丰富了依赖关系、持续时间、严重性、关键路径
3. 计划立即准备就绪（无需澄清）
4. 获取索赔链接和丰富的步骤元数据

先评估后学习（评估到目标）[更新v0.7.0]

将评分评估转化为个性化计划的规范链，没有客户端连接逻辑：

1. 呼叫 generate_skill_assessment 具备技能、目标熟练程度和工作项目背景
2. 在用户界面中向学习者提出问题
3. 呼叫 score_skill_assessment 带有令牌和学习者的答案。响应包括 per_facet, weak_facets, strong_facets, facet_coverage （服务器端聚合）。
4. 呼叫 create_goal 随着分数反应下降到新的 assessment 领域（技能效率v1）。规划者使用弱/强刻面来偏置步骤并将其锚定 work_item_context.
5. 将索赔链接发送给学员。

带有效载荷示例的完整演练 skill_proficiency, general，以及 clinical_intake 住在 指南_评估_计划_MCP.

遗产之路。 v0.7.0之前的集成将分数填充到 additional_context.unfold_assessment 根据 有效载荷公约这仍然有效 POST /api/v1/ext/goals 用于向后兼容；在幕后，这两条路径现在都通过同一个promptbuilder注册表进行路由。新的集成应使用结构化 assessment 场上 create_goal.

示例提示

“为初学者创建一个Python认证学习路径，每周2小时，持续3个月。”

“导入我们的Jira sprint待办事项列表作为目标，其中包含依赖关系和时间估计。”

“为Sarah制定一个辅导计划，但在制定计划之前，让我先复习一下问题。”

“为患有时间盲症的患者制定一个ADHD晨间例行指导计划，其中包含health_ADHD类别。”

“列出春季队列中的所有health_adhd目标，并告诉我哪些目标有风险。”

“显示所有尚未使用索赔链接的目标。”

“目标abc-123的进展如何？学习者开始了吗？”

“为需要中等熟练程度才能从事ML管道工作的人生成一个包含8个问题的Python评估。”

“对这项评估进行评分，如果学习者没有达到目标，则根据结果创建一个目标。”

获取API密钥

1. 首选 App.formmation.com
2. 创建或切换到您的组织
3. 转到组织设置
4. 滚动到 API密钥 部分
5. 点击 +创建密钥，为其命名，并复制密钥

键入错误和警告（v0.7.0+）

当一个工具因键入错误而失败时，响应是一个结构化的JSON信封，而不是一个字符串化的消息。上的分支 error_code:

对目标创建的成功回应也 warnings: ApiWarning[] （始终存在，无时为空）。已知警告代码：

这两个分支都保留了结构化的信封，因此AI编码代理可以在 error_code 或警告 code 串。请参阅 版本控制策略 以确保这些代码的稳定性。

版本控制

这个包遵循semver。固定次要版本范围("@unfoldit/mcp-server": "^0.8.0")--您将自动获得修复和附加功能；突破性的更改需要一个重大的版本升级。我们支持最新的两个次要版本；年龄较大的未成年人只接受安全修复。

注意：在1.0之前的时代，每个微小的凸起（例如0.7.x->0.8.0）可能包括附加的表面变化，例如新的可选请求字段或新的响应字段。现有代码继续工作；根据需要选择新的行为。

看 指南_MCP_版本 对于完整的政策。看 更改日志.md 对于每次发布中发生的变化。

了解更多

• 展开它 --基于人工智能的目标规划与执行平台
• 开发者 --API和MCP文件
• GitHub --源代码和问题
• 评估计划指南 --得分-进球链的端到端演练
• 版本控制策略 --Semver规程、支持的版本窗口、弃用策略

许可证

麻省理工学院