ALM X++ MCP Server

almxppmcp

npx 启动器，用于 ALM XPP 云端 MCP——一个通过 MCP 提供 90 个工具的 Dynamics 365 Finance & Operations AI Agent。

已在官方 MCP 注册表中发布，名称为 io.github.alimbenhelal-pro/alm-xpp-mcp。

该服务基于预构建的标准 D365 F&O 代码库索引回答问题： 200K+ 个 AOT 对象、1.3M+ 个代码块、25M+ 个交叉引用和 24M+ 个标签翻译——涵盖 74 种语言中的 392K 个标签 ID。

为什么使用索引，而不是通用模型

通用模型会根据训练期间记住的内容回答 X++ 问题。此服务则基于特定版本的标准 D365 代码库副本作答：

	实际含义
已知版本	云端 MCP 根据服务已建立索引的版本作答，而非你的版本。当前加载的版本可通过 GET /mcp 查看——依赖涉及版本的回答前，请先确认
你自己的版本	若要为你的环境的确切版本建立索引，请使用本地 MCP：它与 D365 SDK 一起运行，并为该计算机上的 PackagesLocalDirectory 建立索引。云端 MCP 无法做到这一点——它永远不会接触你的平台二进制文件
可追溯	每项结果都附带其来源的 AOT 对象和模型，因此你可以在 Visual Studio 中打开并核查
你的扩展	将 D365-Custom-Model-Path 指向你的元数据，或让它为你的 Azure DevOps 存储库建立索引，这样搜索时就会同时检索你的代码和标准代码
不会用你的代码训练	你的元数据按会话建立索引，用于回答你的调用；不会用于训练任何内容

三种服务器，三种角色

D365 F&O 周边会出现三种不同的 MCP 服务。本 README 始终使用以下名称指代它们：

名称	说明	获取方式
Cloud MCP	托管式 ALM XPP 服务：可搜索已索引的 D365 代码库，提供 90 个工具	本软件包——npx almxppmcp
Local MCP	在你自己的开发计算机上与 D365 SDK 一起运行：提供 121 个工具，其中 36 个可写入 AOT 文件、编译 X++、同步数据库。它也是唯一能通过读取该计算机上的 PackagesLocalDirectory，为你的确切平台版本建立索引的服务	单独授权的组件，请联系 [email protected]
Environment MCP	Microsoft 自有的 Dynamics 365 ERP MCP server，由你的 F&O 环境本身提供，服务实时数据	在 D365FO 中启用，然后直接从 VS Code 连接

此 npm 软件包仅包含 Cloud MCP。Local MCP 需单独授权，而 Environment MCP 属于 Microsoft——客户端会自行连接到它。

要求

• API 令牌——前往仪表板获取
• Node.js >= 18，仅当你使用下文介绍的 npx 启动器时需要

---

MCP 客户端配置

Cloud MCP 是一个位于 https://api.almxpp.com/mcp 的可流式 HTTP MCP 服务，通过 X-API-Key 标头进行身份验证。任何支持 HTTP 的客户端都可以直接连接——无需 Node.js，也无需启动器。

工具调用仅由 api.almxpp.com 提供。 almxpp.com 和 www.almxpp.com 托管网站；向它们发送 JSON-RPC POST 请求会被拒绝，并返回指出正确 URL 的消息。只有主机名会变——你的 API 密钥和标头保持不变。

VS Code / GitHub Copilot——.vscode/mcp.json

{
  "servers": {
    "almxppmcp": {
      "type": "http",
      "url": "https://api.almxpp.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_TOKEN"
      }
    }
  }
}

标头

X-API-Key 是唯一必需的标头。其他标头可启用需要你自己的上下文的工具——未设置这些标头时，相应工具只会报告尚未配置。

标头	可启用的功能
X-API-Key	必需。 你的 API 令牌。也可使用 Authorization: Bearer <token>。
D365-Custom-Model-Path	调用计算机上自有扩展 / ISV 元数据的绝对路径。分析工具会从此处读取
D365-Standard-Model-Path	PackagesLocalDirectory 的绝对路径，用作标准对象的只读参考
DEVOPS_ORG_URL	Azure DevOps 组织，例如 https://dev.azure.com/MyOrg
DEVOPS_PROJECT	Azure DevOps 项目名称。必须与 DEVOPS_ORG_URL 一起提供。
DEVOPS_PAT	Azure DevOps 令牌。用于为你自己的 X++ 元数据建立索引，并读取工作项。
DEVOPS_REPO	存放元数据的代码库；当项目包含多个代码库时需要设置
DEVOPS_BRANCH	要建立索引的分支，默认为 main
DEVOPS_METADATA_PATH	代码库中存放 AOT XML 的文件夹，默认为 Metadata
D365FO-Url	实时环境的基础 URL，供 odata_* 和 dmf_* 工具使用
D365FO-Tenant-Id	该环境的 Entra 租户
D365FO-Client-Id	在 D365FO 的 Microsoft Entra applications 下注册的 Entra 应用
D365FO-Client-Secret	该应用的密钥
AppInsights-Workspace-Id	Log Analytics 工作区，供 appinsights_* 工具使用
AppInsights-Tenant-Id	该工作区的 Entra 租户
AppInsights-Client-Id	在该工作区具有 Log Analytics Reader 权限的 Entra 应用
AppInsights-Client-Secret	该应用的密钥

也可以使用 d365fo_set_connection 和 appinsights_set_connection 在会话期间设置实时环境和遥测凭据，这样它们就不会存放在配置文件中。

examples/vscode-mcp.full-headers.json 汇总了以上所有配置，并通过 VS Code inputs 提示输入每个密钥，因此不会将任何密钥保存在文件中。

---

npx 启动器

有些客户端只支持 stdio。almxppmcp 命令适用于这种情况：它会读取你的令牌，将其作为 X-API-Key 标头发送，并通过 stdio 中继到 Cloud MCP。它没有依赖项——只有这一个文件，所需功能均由 Node 18 提供。

npx almxppmcp --api-key YOUR_TOKEN

或设置环境变量：

export ALMXPPMCP_API_KEY=YOUR_TOKEN
npx almxppmcp

--api-key 和 ALMXPPMCP_API_KEY 是向启动器提供令牌的两种方式。 无论哪种方式，令牌最终都会作为 HTTP 标头 X-API-Key 发送——令牌相同，所在层不同。

VS Code（如果你更喜欢使用启动器）——.vscode/mcp.json

{
  "servers": {
    "almxppmcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "almxppmcp", "--api-key", "YOUR_TOKEN"]
    }
  }
}

Cursor——.cursor/mcp.json

{
  "mcpServers": {
    "almxppmcp": {
      "command": "npx",
      "args": ["-y", "almxppmcp", "--api-key", "YOUR_TOKEN"]
    }
  }
}

Claude Desktop——claude_desktop_config.json

{
  "mcpServers": {
    "almxppmcp": {
      "command": "npx",
      "args": ["-y", "almxppmcp", "--api-key", "YOUR_TOKEN"]
    }
  }
}

**提示：**将 YOUR_TOKEN 替换为控制面板上显示的令牌。将其设为环境变量可避免硬编码（Cursor 和 Claude Desktop 的根键是 mcpServers，VS Code 的根键是 servers）：

{
  "mcpServers": {
    "almxppmcp": {
      "command": "npx",
      "args": ["-y", "almxppmcp"],
      "env": { "ALMXPPMCP_API_KEY": "YOUR_TOKEN" }
    }
  }
}

---

环境变量

变量	描述
ALMXPPMCP_API_KEY	你的 API 令牌（--api-key 的替代方式）
ALMXPPMCP_SERVER_URL	覆盖 MCP 端点（默认值：https://api.almxpp.com/mcp）

---

有哪些工具可用？

Cloud MCP 提供 14 个类别中的 90 个工具，如下所列。

Local MCP 包含其中不依赖云端索引的 85 个工具，以及另外 36 个必须在 D365 环境旁运行的工具（构建、部署、数据库同步、工作区写入），因此该服务端共提供 121 个工具。 两个服务端合计提供 126 个不同的工具。

类别	工具数	名称
搜索	5	search_d365_code、search_labels、batch_search、federated_search、search_context_docs
检索	6	get_object_details、list_objects、list_custom_model_objects、get_object_context、compare_objects、get_menu_item_info
关系与影响	11	find_related_objects、find_references、find_extensions、get_relation_graph、find_entity_for_table、find_callers、find_change_impact、find_event_handlers、find_relation_path、find_similar_implementations、trace_field_lineage
质量与分析	7	validate_best_practices、detect_performance_issues、find_error_patterns、fix_best_practice_violations、recommend_extension_strategy、suggest_edt、validate_object_naming
安全与许可	4	trace_security_chain、trace_role_license_tree、get_security_coverage_for_object、generate_security_report
代码生成	8	generate_unit_test、suggest_refactoring、generate_diagram、generate_query、create_aot_object、generate_data_entity、generate_xpp_form、generate_xpp_template
功能领域	2	generate_fdd、explain_workflow
特色功能	2	analyze_upgrade_impact、map_business_process
升级与发行说明	6	resolve_client_profile、save_client_profile、list_release_note_inputs、prepare_release_note_context、generate_release_note_document、diff_model_versions
实时环境	5	d365fo_set_connection、d365fo_clear_connection、odata_export_entity、odata_upsert_rows、get_data_entity_info
数据迁移	7	dmf、dmf_create_data_project、dmf_apply_entity_filter、dmf_import_file、dmf_export_package、dmf_get_job_status、dmf_transform_excel
性能诊断	4	appinsights_set_connection、appinsights_clear_connection、appinsights_query、appinsights_diagnose_slowness
编排与报告	6	plan_and_execute、summarize_for_stakeholder、resolve_workspace_roots、resync_devops_index、healthcheck、get_output_page
Azure DevOps	17	ado_query_workitems、ado_analyze_workitem、ado_list_prs、ado_analyze_pr_impact、ado_gap_fit_analysis、ado_estimate_effort、ado_post_comment、ado_post_pr_comment、ado_create_task、ado_read_attachment、ado_update_workitem、ado_review_xpp_pr、ado_pr_dependency_map、ado_wiki_list、ado_wiki_get_page、ado_wiki_create_or_update_page、ado_wiki_delete_page

除代码搜索外，值得关注的功能包括：

• 升级影响——将两个 D365 版本与您自己的自定义内容进行比较，并生成 Word 和 PowerPoint 格式的回归报告。
• 实时环境——连接到正在运行的环境，通过 OData 读取和写入真实记录，并运行数据管理项目。
• 性能诊断——查询 Application Insights 遥测数据，并获取实际性能瓶颈的排名诊断。
• Azure DevOps——涵盖工作项、拉取请求和 Wiki，从分析到审查。

包含参数和提示词示例的完整参考文档：https://www.almxpp.com/docs

---

此仓库包含什么

此仓库仅包含客户端 — 作为 almxppmcp 发布到 npm 的 npx 启动器：

路径	用途
bin/almxppmcp.js	解析 API 密钥和服务 URL，然后将客户端的标准输入/输出桥接到 Cloud MCP（通过 HTTP）——不涉及第三方软件包
server.json	MCP 注册表清单

Cloud MCP 本身——索引、检索、90 个工具和许可层——为闭源，运行于 https://api.almxpp.com/mcp。启动器不会看到你的代码：它会使用你提供的令牌，通过 HTTPS 转发请求。

---

许可证

MIT