ALM X++ MCP

npx add-mcp 'https://api.almxpp.com/mcp'

almxppmcp

Lançador npx para o ALM XPP Cloud MCP - um agente de IA para Dynamics 365 Finance & Operations expondo 90 ferramentas via MCP.

Publicado no registro oficial de MCP como io.github.alimbenhelal-pro/alm-xpp-mcp.

O servidor responde a partir de um índice pré-construído do código padrão do D365 F&O: mais de 200 mil objetos AOT, mais de 1,3 milhão de blocos de código, mais de 25 milhões de referências cruzadas e mais de 24 milhões de traduções de rótulos -- 392 mil IDs de rótulos renderizados em 74 idiomas.

Por que um índice em vez de um modelo de propósito geral

Um modelo geral responde a perguntas sobre X++ com base no que memorizou durante o treinamento. Este servidor responde a partir de uma cópia específica e versionada do código padrão do D365:

	O que isso significa na prática
Uma versão conhecida	O Cloud MCP responde a partir da versão que o servidor indexou, não da sua. A versão atualmente carregada é informada por GET /mcp -- verifique antes de confiar em uma resposta sensível à versão
Sua própria versão	Indexar a compilação exata do seu ambiente é a função do Local MCP: ele roda ao lado do seu SDK do D365 e indexa o PackagesLocalDirectory nessa máquina. O Cloud MCP não pode fazer isso -- ele nunca vê os binários da sua plataforma
Rastreável	Cada resultado traz o objeto AOT e o modelo de onde veio, para que você possa abri-lo no Visual Studio e verificar
Suas extensões	Aponte D365-Custom-Model-Path para seus metadados, ou deixe-o indexar seu repositório do Azure DevOps, e seu próprio código será pesquisado junto com o código padrão
Sem treinamento com seu código	Seus metadados são indexados por sessão e usados para responder às suas chamadas. Eles não são usados para treinar nada

Três servidores, três papéis

Três servidores MCP diferentes aparecem em torno do D365 F&O. Este README sempre os chama por estes nomes:

Nome	O que é	Como obter
Cloud MCP	O servidor ALM XPP hospedado: 90 ferramentas sobre o código D365 indexado	este pacote -- npx almxppmcp
Local MCP	Roda na sua própria máquina de desenvolvimento, ao lado do SDK do D365: 121 ferramentas, 36 das quais gravam arquivos AOT, compilam X++, sincronizam o banco de dados. Também é o único que pode indexar a compilação exata da sua plataforma, lendo o PackagesLocalDirectory nessa máquina	componente licenciado separadamente, contate alim@almxpp.com
Environment MCP	O servidor MCP do Dynamics 365 ERP da própria Microsoft, exposto pelo seu ambiente F&O, servindo dados ao vivo	habilitado dentro do D365FO e depois conectado diretamente do VS Code

Este pacote npm cobre apenas o Cloud MCP. O Local MCP é licenciado separadamente, e o Environment MCP é da Microsoft -- seu cliente se conecta a ele por conta própria.

Requisitos

• Um token de API -- obtenha um no painel
• Node.js >= 18, apenas se você usar o lançador npx descrito abaixo

---

Configuração do Cliente MCP

O Cloud MCP é um servidor MCP HTTP transmissível em https://api.almxpp.com/mcp, autenticado com o cabeçalho X-API-Key. Qualquer cliente que fale HTTP conecta-se diretamente a ele -- sem Node.js, sem lançador.

As chamadas de ferramentas são atendidas apenas em api.almxpp.com. almxpp.com e www.almxpp.com hospedam o site; um POST JSON-RPC enviado para lá é recusado com uma mensagem indicando a URL correta. Apenas o host muda -- sua chave de API e cabeçalhos permanecem os mesmos.

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

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

Cabeçalhos

X-API-Key é o único cabeçalho obrigatório. Os demais desbloqueiam as ferramentas que precisam do seu próprio contexto -- sem eles, essas ferramentas simplesmente informam que não estão configuradas.

Cabeçalho	Desbloqueia
X-API-Key	Obrigatório. Seu token de API. Authorization: Bearer <token> também funciona.
D365-Custom-Model-Path	Caminho absoluto para seus próprios metadados de extensão / ISV na máquina chamadora. As ferramentas de análise leem daqui
D365-Standard-Model-Path	Caminho absoluto para PackagesLocalDirectory, usado como referência somente leitura para objetos padrão
DEVOPS_ORG_URL	Organização do Azure DevOps, ex.: https://dev.azure.com/MyOrg
DEVOPS_PROJECT	Nome do projeto no Azure DevOps. Obrigatório junto com DEVOPS_ORG_URL.
DEVOPS_PAT	Token do Azure DevOps. Indexa seus próprios metadados X++ do repositório e lê itens de trabalho.
DEVOPS_REPO	Repositório que contém os metadados, quando o projeto tem vários
DEVOPS_BRANCH	Ramo a indexar, padrão main
DEVOPS_METADATA_PATH	Pasta dentro do repositório que contém o XML do AOT, padrão Metadata
D365FO-Url	URL base do ambiente ao vivo, para as ferramentas odata_* e dmf_*
D365FO-Tenant-Id	Locatário Entra desse ambiente
D365FO-Client-Id	Aplicativo Entra registrado no D365FO em Aplicativos Microsoft Entra
D365FO-Client-Secret	Segredo desse aplicativo
AppInsights-Workspace-Id	Workspace do Log Analytics, para as ferramentas appinsights_*
AppInsights-Tenant-Id	Locatário Entra desse workspace
AppInsights-Client-Id	Aplicativo Entra com Log Analytics Reader no workspace
AppInsights-Client-Secret	Segredo desse aplicativo

As credenciais de ambiente ao vivo e telemetria também podem ser definidas para a sessão com d365fo_set_connection e appinsights_set_connection, para que nunca fiquem em um arquivo de configuração.

examples/vscode-mcp.full-headers.json reúne tudo isso e mantém todos os segredos fora do arquivo, solicitando-os por meio do inputs do VS Code.

---

O lançador npx

Alguns clientes só falam stdio. O comando almxppmcp cobre esse caso: ele lê seu token, envia-o como o cabeçalho X-API-Key e retransmite o tráfego para o Cloud MCP via stdio. Ele não tem dependências -- apenas um arquivo, além do que o Node 18 já fornece.

npx almxppmcp --api-key YOUR_TOKEN

ou defina a variável de ambiente:

export ALMXPPMCP_API_KEY=YOUR_TOKEN
npx almxppmcp

--api-key e ALMXPPMCP_API_KEY são as duas formas de fornecer o token ao lançador. De qualquer forma, ele chega ao destino como o cabeçalho HTTP X-API-Key -- mesmo token, camada diferente.

VS Code, se você preferir o lançador -- .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"]
    }
  }
}

Dica: substitua YOUR_TOKEN pelo token mostrado no seu painel. Defina-o como uma variável de ambiente para evitar codificá-lo (a chave raiz é mcpServers para Cursor e Claude Desktop, servers para VS Code):

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

---

Variáveis de Ambiente

Variável	Descrição
ALMXPPMCP_API_KEY	Seu token de API (alternativa a --api-key)
ALMXPPMCP_SERVER_URL	Substitui o endpoint do MCP (padrão: https://api.almxpp.com/mcp)

---

Quais ferramentas estão disponíveis?

O Cloud MCP expõe 90 ferramentas em 14 categorias, listadas abaixo.

O Local MCP carrega as 85 delas que não dependem do índice na nuvem, além de mais 36 que precisam rodar ao lado do seu ambiente D365 (build, implantação, sincronização de banco de dados, gravações no workspace) -- 121 ferramentas nesse lado. Entre os dois servidores, a caixa de ferramentas tem 126 ferramentas distintas.

Categoria	Ferramentas	Nomes
Pesquisa	5	search_d365_code, search_labels, batch_search, federated_search, search_context_docs
Recuperação	6	get_object_details, list_objects, list_custom_model_objects, get_object_context, compare_objects, get_menu_item_info
Relações e Impacto	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
Qualidade e Análise	7	validate_best_practices, detect_performance_issues, find_error_patterns, fix_best_practice_violations, recommend_extension_strategy, suggest_edt, validate_object_naming
Segurança e Licenciamento	4	trace_security_chain, trace_role_license_tree, get_security_coverage_for_object, generate_security_report
Geração de Código	8	generate_unit_test, suggest_refactoring, generate_diagram, generate_query, create_aot_object, generate_data_entity, generate_xpp_form, generate_xpp_template
Domínio Funcional	2	generate_fdd, explain_workflow
Diferenciais	2	analyze_upgrade_impact, map_business_process
Atualização e Notas de Versão	6	resolve_client_profile, save_client_profile, list_release_note_inputs, prepare_release_note_context, generate_release_note_document, diff_model_versions
Ambiente ao Vivo	5	d365fo_set_connection, d365fo_clear_connection, odata_export_entity, odata_upsert_rows, get_data_entity_info
Migração de Dados	7	dmf, dmf_create_data_project, dmf_apply_entity_filter, dmf_import_file, dmf_export_package, dmf_get_job_status, dmf_transform_excel
Diagnóstico de Desempenho	4	appinsights_set_connection, appinsights_clear_connection, appinsights_query, appinsights_diagnose_slowness
Orquestração e Relatórios	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

Além da pesquisa de código, os recursos notáveis são:

• Impacto de atualização - compare duas versões do D365 com suas próprias personalizações e produza o relatório de regressão como Word e PowerPoint.
• Ambiente ao vivo - conecte-se a um ambiente em execução, leia e grave registros reais via OData, execute projetos de gerenciamento de dados.
• Diagnóstico de desempenho - consulte a telemetria do Application Insights e obtenha um diagnóstico classificado do que está realmente lento.
• Azure DevOps - itens de trabalho, pull requests, wiki, da análise à revisão.

Referência completa com parâmetros e exemplos de prompts: https://www.almxpp.com/docs

---

O que há neste repositório

Este repositório contém apenas o lado do cliente -- o lançador npx publicado no npm como almxppmcp:

Caminho	Finalidade
bin/almxppmcp.js	Resolve a chave de API e a URL do servidor e, em seguida, faz a ponte entre o stdio do seu cliente e o Cloud MCP via HTTP -- sem pacotes de terceiros
server.json	Manifesto do registro MCP

O próprio Cloud MCP -- índice, recuperação, as 90 ferramentas e a camada de licenciamento -- é código fechado e roda em https://api.almxpp.com/mcp. O lançador nunca vê seu código: ele encaminha solicitações via HTTPS com o token que você fornece.

---

Licença

MIT