{
  "markdown": "# almxppmcp\n\n[![npm version](https://img.shields.io/npm/v/almxppmcp?logo=npm&color=cb3837)](https://www.npmjs.com/package/almxppmcp)\n[![npm downloads](https://img.shields.io/npm/dm/almxppmcp?logo=npm&color=cb3837&label=downloads%2Fmonth)](https://www.npmjs.com/package/almxppmcp)\n[![MCP endpoint](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.almxpp.com%2Fbadge%2Fstatus)](https://api.almxpp.com/mcp)\n[![MCP registry](https://img.shields.io/badge/MCP%20registry-listed-0ea5e9?logo=modelcontextprotocol&logoColor=white)](https://registry.modelcontextprotocol.io/?q=alm-xpp-mcp)\n[![M8ven Score](https://m8ven.ai/badge/mcp/alimbenhelal-pro-alm-xpp-mcp-1i8l2g?v=32353b85dcc6252a58d8367376c60e8f)](https://m8ven.ai/mcp/alimbenhelal-pro-alm-xpp-mcp-1i8l2g)\n[![license](https://img.shields.io/github/license/alimbenhelal-pro/ALM-XPP-MCP?color=34d399)](LICENSE)\n[![node](https://img.shields.io/node/v/almxppmcp?logo=node.js&logoColor=white&color=339933)](https://nodejs.org)\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-Alim%20Ben%20Helal-0A66C2?logo=linkedin&logoColor=white)](https://www.linkedin.com/in/alimbenhelal)\n\n> **npx launcher** for the [ALM XPP](https://www.almxpp.com) **Cloud MCP** - a Dynamics 365 Finance & Operations AI agent exposing **90 tools** over MCP.\n\nPublished in the [official MCP registry](https://registry.modelcontextprotocol.io/?q=alm-xpp-mcp) as\n`io.github.alimbenhelal-pro/alm-xpp-mcp`.\n\nThe server answers from a pre-built index of the standard D365 F&O codebase:\n**200K+ AOT objects**, **1.3M+ code chunks**, **25M+ cross-references** and\n**24M+ label translations** -- 392K label ids rendered across 74 languages.\n\n### Why an index rather than a general-purpose model\n\nA general model answers X++ questions from whatever it memorised during training. This server answers\nfrom a specific, versioned copy of the standard D365 codebase:\n\n| | What it means in practice |\n|---|---|\n| **A known release** | The Cloud MCP answers from the release **the server** has indexed, not from yours. The one currently loaded is reported by [`GET /mcp`](https://api.almxpp.com/mcp) -- check it before relying on a version-sensitive answer |\n| **Your own version** | Indexing **your** environment's exact build is what the **Local MCP** is for: it runs next to your D365 SDK and indexes the `PackagesLocalDirectory` on that machine. The Cloud MCP cannot do this -- it never sees your platform binaries |\n| **Traceable** | Every result carries the AOT object and model it came from, so you can open it in Visual Studio and check |\n| **Your extensions** | Point `D365-Custom-Model-Path` at your metadata, or let it index your Azure DevOps repository, and your own code is searched alongside the standard code |\n| **No training on your code** | Your metadata is indexed per session and used to answer your calls. It is not used to train anything |\n\n### Three servers, three roles\n\nThree different MCP servers show up around D365 F&O. This README always calls them by these names:\n\n| Name | What it is | How you get it |\n|---|---|---|\n| **Cloud MCP** | The hosted ALM XPP server: 90 tools over the indexed D365 codebase | this package -- `npx almxppmcp` |\n| **Local MCP** | Runs on your own dev machine, next to the D365 SDK: 121 tools, 36 of which write AOT files, compile X++, sync the database. It is also the only one that can index **your** exact platform build, by reading the `PackagesLocalDirectory` on that machine | separate licensed component, contact <alim@almxpp.com> |\n| **Environment MCP** | Microsoft's own **[Dynamics 365 ERP MCP server](https://learn.microsoft.com/dynamics365/fin-ops-core/dev-itpro/copilot/copilot-mcp)**, exposed by your F&O environment itself, serving live data | enabled inside D365FO, then [connected directly from VS Code](https://learn.microsoft.com/dynamics365/fin-ops-core/dev-itpro/copilot/mcp/mcp-vscode) |\n\nThis npm package covers the **Cloud MCP** only. The Local MCP is licensed separately, and the Environment\nMCP is Microsoft's -- your client connects to it on its own.\n\n## Requirements\n\n- An API token -- get one at the [dashboard](https://www.almxpp.com/account/dashboard)\n- Node.js >= 18, **only** if you use the `npx` launcher described further down\n\n---\n\n## MCP Client Configuration\n\nThe Cloud MCP is a **streamable HTTP** MCP server at `https://api.almxpp.com/mcp`, authenticated with the\n`X-API-Key` header. Any client that speaks HTTP connects to it directly -- no Node.js, no launcher.\n\n> **Tool calls are served on `api.almxpp.com` only.** `almxpp.com` and `www.almxpp.com` host the website;\n> a JSON-RPC POST sent there is refused with a message naming the correct URL. Only the host changes --\n> your API key and headers stay the same.\n\n### VS Code / GitHub Copilot -- `.vscode/mcp.json`\n\n```json\n{\n  \"servers\": {\n    \"almxppmcp\": {\n      \"type\": \"http\",\n      \"url\": \"https://api.almxpp.com/mcp\",\n      \"headers\": {\n        \"X-API-Key\": \"YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n### Headers\n\n`X-API-Key` is the only required header. The others unlock the tools that need your own context --\nwithout them those tools simply report that they are not configured.\n\n| Header | Unlocks |\n|---|---|\n| `X-API-Key` | **Required.** Your API token. `Authorization: Bearer <token>` works too. |\n| `D365-Custom-Model-Path` | Absolute path to your own extension / ISV metadata on the calling machine. Analysis tools read from here |\n| `D365-Standard-Model-Path` | Absolute path to `PackagesLocalDirectory`, used as a read-only reference for standard objects |\n| `DEVOPS_ORG_URL` | Azure DevOps organisation, e.g. `https://dev.azure.com/MyOrg` |\n| `DEVOPS_PROJECT` | Azure DevOps project name. Required alongside `DEVOPS_ORG_URL`. |\n| `DEVOPS_PAT` | Azure DevOps token. Indexes your own X++ metadata from the repo and reads work items. |\n| `DEVOPS_REPO` | Repository holding the metadata, when the project has several |\n| `DEVOPS_BRANCH` | Branch to index, default `main` |\n| `DEVOPS_METADATA_PATH` | Folder inside the repo holding the AOT XML, default `Metadata` |\n| `D365FO-Url` | Live environment base URL, for the `odata_*` and `dmf_*` tools |\n| `D365FO-Tenant-Id` | Entra tenant of that environment |\n| `D365FO-Client-Id` | Entra app registered in D365FO under **Microsoft Entra applications** |\n| `D365FO-Client-Secret` | Secret of that app |\n| `AppInsights-Workspace-Id` | Log Analytics workspace, for the `appinsights_*` tools |\n| `AppInsights-Tenant-Id` | Entra tenant of that workspace |\n| `AppInsights-Client-Id` | Entra app with *Log Analytics Reader* on the workspace |\n| `AppInsights-Client-Secret` | Secret of that app |\n\nThe live-environment and telemetry credentials can also be set for the session with\n`d365fo_set_connection` and `appinsights_set_connection`, so they never sit in a config file.\n\n[`examples/vscode-mcp.full-headers.json`](examples/vscode-mcp.full-headers.json) puts all of this together\nand keeps every secret out of the file by prompting for it through VS Code `inputs`.\n\n---\n\n## The `npx` launcher\n\nSome clients only speak stdio. The `almxppmcp` command covers that case: it reads your token, sends it as\nthe `X-API-Key` header, and relays the traffic to the Cloud MCP over stdio. It has **no dependencies** --\njust the one file, on top of what Node 18 already provides.\n\n```bash\nnpx almxppmcp --api-key YOUR_TOKEN\n```\n\nor set the environment variable:\n\n```bash\nexport ALMXPPMCP_API_KEY=YOUR_TOKEN\nnpx almxppmcp\n```\n\n> `--api-key` and `ALMXPPMCP_API_KEY` are the two ways of giving the token **to the launcher**.\n> Either way it ends up on the wire as the HTTP header `X-API-Key` -- same token, different layer.\n\n### VS Code, if you prefer the launcher -- `.vscode/mcp.json`\n\n```json\n{\n  \"servers\": {\n    \"almxppmcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"almxppmcp\", \"--api-key\", \"YOUR_TOKEN\"]\n    }\n  }\n}\n```\n\n### Cursor -- `.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"almxppmcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"almxppmcp\", \"--api-key\", \"YOUR_TOKEN\"]\n    }\n  }\n}\n```\n\n### Claude Desktop -- `claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"almxppmcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"almxppmcp\", \"--api-key\", \"YOUR_TOKEN\"]\n    }\n  }\n}\n```\n\n> **Tip:** replace `YOUR_TOKEN` with the token shown on your dashboard. Set it as an env var to avoid hard-coding it\n> (root key is `mcpServers` for Cursor and Claude Desktop, `servers` for VS Code):\n>\n> ```json\n> {\n>   \"mcpServers\": {\n>     \"almxppmcp\": {\n>       \"command\": \"npx\",\n>       \"args\": [\"-y\", \"almxppmcp\"],\n>       \"env\": { \"ALMXPPMCP_API_KEY\": \"YOUR_TOKEN\" }\n>     }\n>   }\n> }\n> ```\n\n---\n\n## Environment Variables\n\n| Variable | Description |\n|---|---|\n| `ALMXPPMCP_API_KEY` | Your API token (alternative to `--api-key`) |\n| `ALMXPPMCP_SERVER_URL` | Override the MCP endpoint (default: `https://api.almxpp.com/mcp`) |\n\n---\n\n## What tools are available?\n\nThe **Cloud MCP** exposes **90 tools** across 14 categories, listed below.\n\nThe **Local MCP** carries the 85 of them that do not depend on the cloud index, plus **36 more** that must\nrun next to your D365 environment (build, deploy, database sync, workspace writes) -- 121 tools on that side.\nAcross both servers the toolbox is **126 distinct tools**.\n\n| Category | Tools | Names |\n|---|---:|---|\n| **Search** | 5 | `search_d365_code`, `search_labels`, `batch_search`, `federated_search`, `search_context_docs` |\n| **Retrieve** | 6 | `get_object_details`, `list_objects`, `list_custom_model_objects`, `get_object_context`, `compare_objects`, `get_menu_item_info` |\n| **Relations & Impact** | 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` |\n| **Quality & Analysis** | 7 | `validate_best_practices`, `detect_performance_issues`, `find_error_patterns`, `fix_best_practice_violations`, `recommend_extension_strategy`, `suggest_edt`, `validate_object_naming` |\n| **Security & Licensing** | 4 | `trace_security_chain`, `trace_role_license_tree`, `get_security_coverage_for_object`, `generate_security_report` |\n| **Code Generation** | 8 | `generate_unit_test`, `suggest_refactoring`, `generate_diagram`, `generate_query`, `create_aot_object`, `generate_data_entity`, `generate_xpp_form`, `generate_xpp_template` |\n| **Functional Domain** | 2 | `generate_fdd`, `explain_workflow` |\n| **Differentiators** | 2 | `analyze_upgrade_impact`, `map_business_process` |\n| **Upgrade & Release Notes** | 6 | `resolve_client_profile`, `save_client_profile`, `list_release_note_inputs`, `prepare_release_note_context`, `generate_release_note_document`, `diff_model_versions` |\n| **Live Environment** | 5 | `d365fo_set_connection`, `d365fo_clear_connection`, `odata_export_entity`, `odata_upsert_rows`, `get_data_entity_info` |\n| **Data Migration** | 7 | `dmf`, `dmf_create_data_project`, `dmf_apply_entity_filter`, `dmf_import_file`, `dmf_export_package`, `dmf_get_job_status`, `dmf_transform_excel` |\n| **Performance Diagnostics** | 4 | `appinsights_set_connection`, `appinsights_clear_connection`, `appinsights_query`, `appinsights_diagnose_slowness` |\n| **Orchestration & Reporting** | 6 | `plan_and_execute`, `summarize_for_stakeholder`, `resolve_workspace_roots`, `resync_devops_index`, `healthcheck`, `get_output_page` |\n| **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` |\n\nBeyond code search, the notable capabilities are:\n\n- **Upgrade impact** - compare two D365 versions against *your own* customisations and\n  produce the regression report as Word and PowerPoint.\n- **Live environment** - connect to a running environment, read and write real records\n  over OData, run Data Management projects.\n- **Performance diagnostics** - query Application Insights telemetry and get a ranked\n  diagnosis of what is actually slow.\n- **Azure DevOps** - work items, pull requests, wiki, from analysis to review.\n\nFull reference with parameters and example prompts: <https://www.almxpp.com/docs>\n\n---\n\n## What is in this repository\n\nThis repository holds the **client side only** — the `npx` launcher published to\nnpm as [`almxppmcp`](https://www.npmjs.com/package/almxppmcp):\n\n| Path | Purpose |\n|---|---|\n| `bin/almxppmcp.js` | Resolves the API key and server URL, then bridges your client's stdio to the Cloud MCP over HTTP -- no third-party package involved |\n| `server.json` | MCP registry manifest |\n\nThe Cloud MCP itself — index, retrieval, the 90 tools and the licensing layer — is\nclosed source and runs at `https://api.almxpp.com/mcp`. The launcher never sees\nyour code: it forwards requests over HTTPS with the token you provide.\n\n---\n\n## License\n\nMIT\n",
  "bytes": 13101,
  "sha": "1687e5e00a1e9144e002032f340f8563566fcfd44ca83bca535ca3d3dd020091",
  "repo_slug": "alimbenhelal-pro/alm-xpp-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_alimbenhelal_pro_alm_xpp_mcp_9c04c007/readme"
}