Fluent (ServiceNow SDK)

Gerencie metadados, módulos, registros e testes do ServiceNow usando o Fluent, um DSL declarativo baseado em TypeScript. Suporta todos os comandos da CLI do SDK do ServiceNow.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP Fluent

Um servidor MCP que traz as capacidades do ServiceNow Fluent SDK para ambientes de desenvolvimento assistidos por IA. Permite interação em linguagem natural com comandos do ServiceNow SDK, especificações de API, trechos de código e recursos de desenvolvimento.

Construído para @servicenow/sdk@v4.11.2.

Nota: Desde a v0.6.0, o servidor fala tanto MCP@2026-07-28 quanto MCP@2025-11-25 a partir de um único conjunto de handlers — a entrada stdio inspeciona a mensagem de abertura e atende à era com a qual o cliente abre. v0.5.1 é a última versão construída sobre o MCP SDK v1 (somente 2025-11-25).

Principais Recursos

Ferramentas de Comandos SDK - sdk_info além de ferramentas de comandos do ServiceNow SDK para init, build, install, dependencies, transform, download, clean, pack, explain, query e cicd
Recursos Ricos - Especificações de API, instruções e trechos de código para 70 tipos de metadados do ServiceNow
Consulta de Documentação de API - explain_fluent_api retorna documentação do SDK para qualquer API ou guia Fluent — sem necessidade de projeto
Autenticação Automática Preguiçosa - Detecta e armazena em cache um perfil de autenticação somente quando um comando que exige autenticação ou check_auth_status precisar dele
Contexto de Projeto Explícito - Resolve cada comando de projeto a partir do argumento workingDirectory, da sessão inicializada ou de FLUENT_MCP_WORKING_DIR, e falha com orientação acionável em vez de adivinhar
Pacote MCPB - Gera uma distribuição .mcpb autocontida com o servidor, recursos e dependências de produção
Esquemas Amigáveis ao Cliente - Entradas opcionais anunciam seus tipos de valor canônicos enquanto o esquema aplicado aceita null como uma forma de compatibilidade para valores omitidos

Este servidor MCP implementa a especificação Model Context Protocol com as seguintes capacidades:

Núcleo

Recursos - Mais de 300 recursos em 70 tipos de metadados do ServiceNow (especificações de API, instruções, trechos, prompts)
Ferramentas - 13 ferramentas de comandos do ServiceNow SDK mais 4 ferramentas de recursos/autenticação (17 no total), com validação completa de parâmetros. Ferramentas de leitura (get-api-spec, get-snippet, get-instruct, check_auth_status) declaram um outputSchema e retornam structuredContent para consumidores programáticos
Prompts - Modelos de fluxo de trabalho de desenvolvimento para tarefas comuns do ServiceNow (coding_in_fluent, create_custom_ui)
Registro e Progresso - Logs estruturados são gravados em stderr; notificações de progresso são enviadas para comandos de longa duração (qualquer comando com timeout de 30s ou mais — deploy, build, transform, download, dependencies, query, pack, cicd) quando o cliente fornece um token de progresso

Contexto de Projeto e Sessões

O servidor não exige capacidades do cliente e não emite solicitações servidor→cliente: Roots, Sampling e Elicitation não são usados (MCP 2026-07-28 removeu solicitações iniciadas pelo servidor, e toda entrada chega com os argumentos tools/call). A detecção automática de workspace via Roots foi removida para todos os clientes, incluindo hosts MCPB.

Gerenciamento de Sessão - Rastreia o diretório estabelecido por init_fluent_app para comandos de projeto subsequentes
Resolução de Diretório de Trabalho - Argumento da ferramenta workingDirectory → sessão inicializada → FLUENT_MCP_WORKING_DIR → falha acionável. Caminhos aceitos são caminhos absolutos não vazios, diferentes da raiz do sistema de arquivos. O servidor nunca adivinha a partir do diretório de trabalho do processo ou do diretório do pacote instalado. Os clientes devem passar workingDirectory ou configurar FLUENT_MCP_WORKING_DIR quando não existir um diretório de sessão.
init_fluent_app Não Interativo - Argumentos específicos de intenção devem ser fornecidos na chamada (criação: appName, packageName, scopeName, template; conversão: from); um argumento ausente falha com um erro nomeando exatamente o que está faltando. A ferramenta não solicita nem elicita valores ausentes.
Tratamento de Erros - Mensagens de erro abrangentes com orientação acionável
Segurança de Tipos - Implementação completa em TypeScript com tipagem estrita

Comportamento do Protocolo

stdio de dupla era: uma abertura 2026-07-28 (envelope _meta por solicitação, server/discover) e um initialize 2025-11-25 são ambos atendidos pelo mesmo conjunto de handlers; o ponto de entrada do SDK fixa uma era por conexão.
Os seis resultados armazenáveis em cache de 2026-07-28 (tools/list, prompts/list, resources/list, resources/templates/list, resources/read, server/discover) anunciam ttlMs: 3600000 / cacheScope: 'public' — tudo o que retornam é estático durante a vida útil do processo.
O servidor anuncia instruções durante a inicialização; tools/list é uma leitura sem efeitos colaterais que retorna ferramentas em ordem determinística de nome.
Argumentos opcionais de ferramentas anunciam seus tipos JSON canônicos para que os clientes renderizem campos de formulário normais. O esquema de chamada aplicado também aceita null como valor omitido; workingDirectory também trata uma string vazia como omitida antes de aplicar a cadeia de fallback.
Logs estruturados vão para stderr, mantendo stdout reservado para tráfego do protocolo MCP. logging/setLevel e notifications/message em tempo de execução não são usados.
Falhas de recursos usam o código padrão invalid-params do JSON-RPC (-32602).

Início Rápido

# Test with MCP Inspector
npx @modelcontextprotocol/inspector npx @modesty/fluent-mcp

# Build the optional self-contained MCPB distribution
npm run bundle

# Or use in your MCP client (see Configuration below)

Distribuição MCPB

O comando opcional npm run bundle produz fluent-mcp-<version>.mcpb. O pacote contém dist/, res/ e dependências de produção, e seu manifest.json declara todas as 17 ferramentas. Os hosts MCPB expõem estes valores configuráveis pelo usuário ao servidor:

FLUENT_MCP_WORKING_DIR — diretório de projeto padrão opcional; caso contrário, passe workingDirectory em chamadas de ferramentas cientes de projeto
SN_INSTANCE_URL — URL de instância opcional para validação de autenticação preguiçosa
SN_AUTH_TYPE — tipo de autenticação (basic ou oauth, padrão oauth)

O pacote npm continua sendo o canal de distribuição principal. O MCPB não restaura a detecção de workspace baseada em Roots nem a solicitação interativa de init_fluent_app.

Exemplo de prompt:

Create a new Fluent app in ~/projects/time-off-tracker to manage employee PTO requests

Ferramentas Disponíveis

Ferramentas de Comandos SDK (13)

Ferramenta	Descrição	Parâmetros Principais
`sdk_info`	Obter versão do SDK ou ajuda	`flag` (-v/-h), `command` (opcional para -h)
`explain_fluent_api`	Consultar documentação do Fluent SDK para qualquer API ou guia. Nenhum projeto Fluent necessário.	`topic` (nome de API/guia opcional ou palavra-chave de tag — obrigatório a menos que `list=true`), `list` (booleano — listar tópicos), `peek` (booleano — resumo breve), `format` (`pretty`\|`raw`), `source` (caminho de projeto opcional para substituição), `debug` (opcional)
`init_fluent_app`	Inicializar ou converter um aplicativo ServiceNow. Não interativo: argumentos específicos de intenção ausentes falham com um erro nomeando-os.	`intent`, `from` (conversão), `appName`/`packageName`/`scopeName`/`template` (criação), `auth`, `workingDirectory` (obrigatório), `debug`
`build_fluent_app`	Compilar o aplicativo	`workingDirectory`, `debug` (opcional)
`deploy_fluent_app`	Implantar em uma instância ServiceNow. A ativação do fluxo do SDK pode ser ignorada.	`workingDirectory`, `auth` (injetado automaticamente), `skipFlowActivation`, `debug`
`fluent_transform`	Converter XML ou metadados de instância para Fluent TypeScript. Caminhos locais não exigem autenticação; transformações de instância exigem.	`workingDirectory`, `from`, `directory`, `auth` (injetado automaticamente), `table`, `id`, `debug`
`download_fluent_dependencies`	Baixar dependências e definições de tipos	`workingDirectory`, `auth` (injetado automaticamente), `debug`
`download_fluent_app`	Baixar metadados de uma instância	`workingDirectory`, `directory` (obrigatório), `source`, `auth` (injetado automaticamente), `incremental`, `debug`
`clean_fluent_app`	Limpar diretório de saída	`workingDirectory`, `source` (opcional), `debug`
`pack_fluent_app`	Criar um artefato instalável	`workingDirectory`, `source` (opcional), `debug`
`query_fluent_records`	Consulta REST de Tabela somente leitura contra uma instância; retorna um envelope JSON	`workingDirectory`, `table` (obrigatório), `query` (consulta codificada obrigatória), `fields`, `limit`, `offset`, `displayValue`, `view`, `queryCategory`, `excludeReferenceLink`, `noCount`, `queryNoDomain`, `timeout`, `select`, `auth` (injetado automaticamente), `debug`
`cicd_fluent_app`	Instalar, publicar ou reverter um aplicativo via API CI/CD do ServiceNow (`sn_cicd`). Altera o estado da instância.	`workingDirectory`, `action` (obrigatório: `install`\|`publish`\|`rollback`), `scope`\|`appSysId`, `appVersion` (obrigatório para reversão, e para instalação/publicação fora de um projeto Fluent), `baseAppVersion`, `autoUpgradeBaseApp`, `devNotes`, `wait`, `pollTimeout`, `auth` (injetado automaticamente), `output` (`json`\|`raw`), `select`, `debug`
`cicd_fluent_test`	Executar, monitorar ou buscar resultados para suítes e testes ATF via API CI/CD. `run` executa etapas ATF reais na instância. Nenhum projeto Fluent necessário (e nenhum aceito).	`target` (obrigatório: `testsuite`\|`test`), `action` (obrigatório: `run`\|`watch`\|`result`), `testSuiteSysId`\|`testSuiteName`, `testSysId`\|`testName`, `progressId` (monitorar), `resultId` (resultado), `browserName`, `browserVersion`, `osName`, `osVersion`, `runInCloud`, `isPerformanceRun`, `captureNodeLogs`, `wait`, `pollTimeout`, `auth` (injetado automaticamente), `output` (`json`\|`raw`), `select`, `debug`

Ferramentas de Recursos e Autenticação (4)

Ferramenta	Descrição	Parâmetros Principais
`get-api-spec`	Obter uma especificação de API ou listar todos os tipos de metadados disponíveis	`metadataType` (opcional; omita para listar todos)
`get-snippet`	Obter um trecho de código Fluent; sem `id`, retorna o primeiro trecho disponível e quaisquer IDs de trechos adicionais	`metadataType` (obrigatório), `id` (opcional)
`get-instruct`	Obter orientação de autoria, convenções e armadilhas comuns para um tipo de metadados	`metadataType` (obrigatório)
`check_auth_status`	Validar preguiçosamente a autenticação ServiceNow configurada e retornar informações de status estruturadas	Sem argumentos

Nota: A autenticação é validada preguiçosamente no primeiro comando que exige autenticação ou check_auth_status, e depois armazenada em cache para a sessão. Use init_fluent_app para estabelecer contexto de projeto, passe workingDirectory por chamada ou defina FLUENT_MCP_WORKING_DIR. Qualquer argumento opcional enviado como null é tratado como omitido; workingDirectory também trata uma string vazia como omitida e recorre à próxima fonte.

Consultando APIs Fluent com `explain_fluent_api`

explain_fluent_api encapsula now-sdk explain e retorna documentação do SDK para qualquer classe de API Fluent ou guia de tópicos. Funciona a partir de qualquer diretório — nenhum projeto Fluent necessário.

Invocação	Resultado
`explain_fluent_api({ topic: 'BusinessRule' })`	Referência completa da API para `BusinessRule`
`explain_fluent_api({ topic: 'BusinessRule', peek: true })`	Resumo breve de `BusinessRule`
`explain_fluent_api({ topic: 'BusinessRule', format: 'raw' })`	Referência completa da API como markdown simples (bom para canalizar para outras ferramentas)
`explain_fluent_api({ list: true })`	Índice completo de tópicos (todas as APIs e guias)
`explain_fluent_api({ list: true, topic: 'atf' })`	Índice de tópicos filtrado para entradas correspondentes a `atf`
`topic` corresponde a um nome de API (ex.: `BusinessRule`, `Acl`), um nome de guia (ex.: `business-rule-guide`, `atf-guide`) ou uma palavra-chave de tag (ex.: `flow`, `atf`, `email`). O SDK resolve primeiro por nome exato e depois por tag.

Recursos

Padrões de URI padronizados seguindo a especificação MCP:

Tipo de Recurso	Padrão de URI	Exemplo	Finalidade
Especificações de API	`sn-spec://{type}`	`sn-spec://business-rule`	Documentação e parâmetros de API
Instruções	`sn-instruct://{type}`	`sn-instruct://script-include`	Práticas recomendadas e orientações
Trechos de Código	`sn-snippet://{type}/{id}`	`sn-snippet://acl/0001`	Exemplos práticos de código
Prompts	`sn-prompt://{id}`	`sn-prompt://coding_in_fluent`	Guias de desenvolvimento

Tipos de Metadados Suportados

71 tipos de metadados nas seguintes categorias:

Tipos Principais: acl, application-menu, business-rule, client-script, cross-scope-privilege, data-policy, field-style, form, import-set, instance-scan, list, property, role, scheduled-script, script-action, script-include, scripted-rest, sla, state-model, table, ui-action, ui-page, ui-policy, user-preference

Tipos de Tabela: column, column-generic

Catálogo de Serviços: catalog-item, catalog-item-record-producer, catalog-ui-policy, catalog-client-script, catalog-variable, variable-set

E-mail: email-notification, inbound-email-action

Automação e Fluxo de Trabalho: flow, custom-action, playbook

Integração e Conexões: alias, alias-template, retry-policy, rest-message, data-lookup, graphql-api

IA e Now Assist: ai-agent, ai-agent-workflow, now-assist-skill-config

Portal de Serviços: service-portal, sp-header-footer, sp-page-route-map

Workspace e Analytics: workspace, dashboard

ATF (Estrutura de Teste Automatizado): atf (o contêiner Test() e o ponto de entrada da família — comece aqui e depois roteie para um subtipo de etapa), atf-appnav, atf-catalog-action, atf-catalog-validation, atf-catalog-variable, atf-email, atf-form, atf-form-action, atf-form-declarative-action, atf-form-field, atf-form-sp, atf-list, atf-reporting, atf-rest-api, atf-rest-assert-payload, atf-server, atf-server-catalog-item, atf-server-record, atf-ui-test-script, test-suite

Novidades na versão 4.11.2

Esta versão do servidor MCP acompanha o @servicenow/sdk 4.11.2, cobrindo as adições à superfície de autoria lançadas nas versões 4.11.0 e 4.11.2 (a 4.11.1 nunca foi publicada no npm, e a 4.11.2 não trouxe notas de versão — sua superfície foi estabelecida por comparação do pacote instalado):

Novo tipo de metadados: test-suite — a API TestSuite agrupa registros ATF Test() existentes em uma suíte nomeada, ordenável e opcionalmente aninhada, gravando sys_atf_test_suite mais uma linha de associação sys_atf_test_suite_test por entrada. A ordem de execução vem da posição no array, não de um campo de autoria. É somente de autoria: nunca dispara ou agenda uma execução — use a interface/scheduler do ATF ou cicd_fluent_test.
Novo tipo de metadados: graphql-api — a API GraphQLApi define uma API GraphQL com script (sys_graphql_schema) com seus resolvers, type resolvers e segurança em duas camadas: ACLs de gate de esquema em toda a API, além de ACLs de caminho Acl({ type: 'graphql' }) independentes em nível de campo. Os paths de resolver usam Type:field; os nomes de ACL usam o caminho de consulta em tempo de execução separado por barras.
Novo tipo de metadados: field-style — sys_ui_style agora é uma tabela Record() suportada, tornando a estilização condicional de campos de lista/formulário autorável no Fluent (não há construtor FieldStyle()). style aceita qualquer propriedade CSS, então este também é o mecanismo para width e text-align de colunas de lista.
Loop do-while em Flow — wfa.flowLogic.doTheFollowing({ $id, label?, annotation? }, () => { ... }) repete um corpo até que wfa.flowLogic.until('<condition>'), chamado como a última instrução do corpo, seja satisfeito. O corpo sempre é executado pelo menos uma vez e a condição pode referenciar saídas de ações dentro do mesmo corpo, o que o torna a construção ideal para polling e tentativas.
Execução sob demanda de playbooks — executionType foi ampliado para 'record_driven' | 'on_demand'. Um playbook independente deve omitir triggers completamente, não pode definir parentTable nem referenciar params.parentRecord, pode finalmente definir allowAsNested: true e deve conceder launch: true em pelo menos um conjunto de permissões ou a compilação falha.
Permissões de playbook — novo permissions no argumento 2 (um callback, para que pills possam alcançar params.parentRecord) e em cada LaneConfig (um objeto simples), cada um agrupando users/userGroups/roles/userCriterias. Em um playbook, view é obrigatório e controla todas as outras flags; em um lane, as quatro flags são independentes. wfa.playbook.activityRef(Now.ID['x']) alcança as saídas de uma atividade de dentro de um bloco de permissões.
Atividades opcionais de playbook — startRule: wfa.playbook.run.Manually() declara uma atividade que o usuário inicia manualmente. Ela retorna um ManualActivityReference sem saídas que está deliberadamente fora da união de dependências: como pode nunca ser executada, nada pode aguardá-la com run.After().
Launcher e saídas de playbook — launcherTitle, launcherDescription e launcherInputs configuram o launcher sob demanda; os campos de formulário de registro (launcherShowRecordForm, launcherRecordFormView, launcherTemplateFields) pertencem a playbooks orientados a registro. A nova atividade OOB ActivityDefinitions.Core.SetPlaybookOutputs grava o outputs declarado do próprio playbook.
Atividades de agente de IA em playbooks — a configuração do agente de IA é exposta nas quatro definições OOB que optaram por isso (RecordForm, AutocompletingRecordForm, NewRecordForm, EmailForm). aiAgentObjective torna-se obrigatório quando enableAiAgent é verdadeiro. O SDK não valida nenhum pré-requisito de plataforma (sn_genai_platform instalado, sn_pa_designer.enable_agentic_playbooks verdadeiro).
Entradas de registro dependentes — UpdateRecord/CreateNewRecord agora verificam o tipo de uma pill record contra a entrada table_name irmã, e Action() carrega rawInputs para o mesmo propósito, então uma pill de tabela errada é um erro de compilação em vez de uma surpresa em tempo de execução.
Table.sizeClass e List.domain — Table aceita sizeClass?: number; List aceita domain?: string (o sys_domain aplicado à lista, com padrão 'global').
17 novas tabelas endereçáveis por Record() (176 → 193), incluindo sys_ui_style, cmn_schedule_span (entradas de agendamento), business_calendar_span, cmdb, sysrule_view_workspace e sysevent_script_action.

Nota sobre a fonte da verdade: cinco alegações das notas de versão não são corroboradas pelo pacote instalado e foram tratadas como correções. doTheFollowingUntil não foi "reformulado" — esse identificador não existe nem na 4.10.1 nem na 4.11.2; a construção é nova e é criada como doTheFollowing + until. enforceAcl não é um booleano seguro por padrão — é um array de referência de ACL com padrão vazio, ou seja, sem gate de esquema (apenas os três booleanos requires* e contextualAclMaxDepth são seguros por padrão). A alegação de novas tabelas está subnotificada: 17 tabelas foram adicionadas, não 2. Um resolver GraphQL script não pode ser um literal de função inline, mesmo que o tipo aceite uma função. E os campos de formulário de registro launcher* são proibidos em executionType: 'on_demand', o oposto do que "configurações de launcher sob demanda" sugere. Separadamente, o item "Decimal dentro de FlowObject/FlowArray" é uma correção do pipeline de build, não uma mudança de tipo — FlowTypes.d.ts e db/types/Decimal.d.ts são byte idênticos à 4.10.1. Veja .mosey/upgrade-sdk-4.11.2.md.

Anteriormente (4.10.x)

Adições à superfície de autoria lançadas nas versões @servicenow/sdk 4.10.0 e 4.10.1:

Novo tipo de metadados: state-model — a API StateModel define a máquina de estados de uma tabela (estados, transições e as condições que as controlam) em uma única chamada, gravando registros sttrm_model/sttrm_state/sttrm_state_transition/sttrm_transition_condition, ou a subclasse chg_model/prb_model/prb_task_model selecionada automaticamente a partir de table. Também pode editar modelos prontos no local referenciando seus sys_ids reais.
Novo tipo de metadados: atf-list — as etapas ATF atf.list.* (relatedListVisibility, applyFilterToList, recordPresentInList, openRecordInList, listUIActionVisibility, clickListUIAction) exercitam o comportamento de UI de listas e listas relacionadas.
Novas ferramentas: cicd_fluent_app (instalar/publicar/reverter um aplicativo pela API sn_cicd — altera o estado da instância) e cicd_fluent_test (executar, acompanhar ou buscar resultados de suítes e testes ATF), envolvendo o novo comando now-sdk cicd. query_fluent_records ganha select para o novo extrator de caminho --select.
$meta.useEsLatest — nova flag transversal que executa o(s) campo(s) de script de um registro na versão mais recente de ECMAScript suportada pela plataforma. Alcança as APIs cujo tipo carrega $meta (rotas BusinessRule, Acl, ScriptInclude, ScriptAction, ScheduledScript, UiPage, RestApi, SPWidget, SPMenu e outras) — não toda API com campo de script no servidor: as condições de transição StateModel são scripts no servidor cujo tipo não aceita $meta (veja a nota sobre a fonte da verdade abaixo).
Forma de objeto da tabela actions — actions agora aceita a forma exportada TableActionAccess { read?, update?, delete?, create? }, onde cada ação tem três estados. A forma de array está obsoleta: é uma enumeração completa, então actions: ['read'] também grava as outras três como false. O SDK também não deriva mais padrões para actions, allowClientScripts, allowNewFields, allowUiActions, allowWebServiceAccess ou maxLength.
Coluna de referência mtom — cria um relacionamento muitos-para-muitos. Observe a divisão semântica: referenceKey não significa mais muitos-para-muitos e agora armazena um campo da tabela referenciada no lugar de sys_id.
Ícones de Ação de UI — os objetos form e list de UiAction aceitam iconName e showIconOnly.
Form $meta — Form agora honra $meta.installMethod para rotear sua pasta de saída (antes aceito, mas inerte).
Playbook timerSchedule — startWithDelay pode avaliar seu atraso contra um registro cmn_schedule em vez do tempo de relógio decorrido, em todas as três variantes.
Valores padrão dinâmicos de catálogo — o dependentQuestion de uma variável foi ampliado para aceitar um ReferenceVariable/RequestedForVariable além de uma string de nome; ações CatalogUiPolicy aceitam variable, e CatalogClientScript aceita order.
$override em campos sys_* — $override pode definir sys_domain e a maioria das outras colunas sys_* em qualquer tabela; sys_id, sys_scope, sys_update_name e sys_domainpath permanecem gerenciados pela estrutura e geram erro se sobrescritos.
Portal de Serviços — campos CSS de widget/página/instância aceitam SCSS ou CSS, widgetParameters agora serializa corretamente um objeto simples, as propriedades de placeholder de SPInstance são funcionais em vez de ignoradas, e urlSuffix aceita hífens. A especificação service-portal também ganhou a API ServicePortal() (sp_portal) anteriormente não documentada.

Nota de fonte da verdade: várias afirmações das notas de versão não são corroboradas pelo pacote instalado e foram tratadas como correções — "perguntas dependentes" são um valor padrão dinâmico, não controle de visibilidade ou opções (e a propriedade não é nova, apenas seu tipo foi ampliado); runServerSideScript "suporte de superfície" já foi entregue na 4.9.0; e a mudança de inferência add_message é uma correção interna de transformação sem mudança na superfície de autoria. O guia de visão geral também lista StateModel, AliasTemplate, InboundEmailAction, CatalogItem, CatalogItemRecordProducer e as verificações de varredura de instância como aceitando $meta.useEsLatest, mas suas declarações não carregam $meta. Consulte .mosey/upgrade-sdk-4.10.1.md.

Anteriormente (4.9.x)

Esta versão do servidor MCP acompanha @servicenow/sdk 4.9.0 — uma versão de manutenção e correção de bugs (confiabilidade de Flow, ClientScript, ImportSet, transform/build de SLA) com adições seletivas na superfície de autoria:

Novo tipo de metadados: atf-ui-test-script — o passo ATF atf.uiTestScript.runTest() executa um corpo de teste TestingLibrary no runner de testes do cliente para testar componentes de UI personalizados (widgets Angular/React, SPAs incorporados, workspaces personalizados, componentes web now-*) que os passos padrão atf.form.* / atf.catalog.* não conseguem alcançar.
Rótulos de escolha multilíngues — o valor choices de um campo de escolha pode ser um array de objetos ChoiceConfig, cada um com uma chave language (BCP 47), produzindo um registro sys_choice traduzido por idioma.
protectionPolicy em AI Agent e AI Agentic Workflow — AiAgent e AiAgenticWorkflow aceitam protectionPolicy: 'read' | 'protected' para controle de acesso pós-instalação.
Role.federatedId — identificador opcional para corresponder uma função a uma função federada externamente durante a federação de identidade.
Colunas de plataforma de índice de tabela — a entrada index de uma tabela pode ter seu element referenciando colunas padrão da plataforma (por exemplo, sys_created_on).
Provedores do Now Assist Skill Kit — novos provedores de LLM selecionáveis por nome: Now LLM LTS Generic, Google Cloud Vertex AI, Amazon Bedrock.

Nota de fonte da verdade: duas afirmações das notas de versão não são corroboradas pelo pacote instalado e foram tratadas como correções — Form table_field.field é documentado como um nome de coluna de esquema (não afrouxado para "qualquer string"), e as quatro strings nomeadas de modelo NASK não aparecem em lugar nenhum no pacote (model é uma string livre). Consulte .mosey/upgrade-sdk-4.9.0.md.

Anteriormente (4.8.x)

Esta versão do servidor MCP acompanha @servicenow/sdk 4.8.0 e adiciona suporte para as seguintes APIs Fluent e melhorias do SDK:

Novo tipo de metadados: playbook — a API PlaybookDefinition (sys_pd_process_definition, de @servicenow/sdk/automation) para processos guiados e orientados por registros em várias etapas, com pistas, atividades, gatilhos e entradas/saídas.
Novo tipo de metadados: rest-message — a API RestMessage (sys_rest_message) para integrações HTTP de saída com autenticação/cabeçalhos compartilhados e funções chamáveis.
Novos tipos de metadados: alias e alias-template — as APIs Alias (sys_alias) e AliasTemplate (sys_alias_templates) para aliases de Connection & Credential e modelos reutilizáveis de configuração de conexão.
Novo tipo de metadados: retry-policy — a API RetryPolicy (sys_retry_policy) que controla o tratamento de falhas transitórias para conexões (intervalo fixo, backoff exponencial ou Retry-After).
Novo tipo de metadados: data-lookup — a API DataLookup (dl_definition) que copia automaticamente valores de campo de uma tabela de correspondência para um registro de origem.
Exclusão declarativa (Now.del()) — instrução de nível superior para remover registros por chaves de coalescência ou sys_id.
Melhorias de tipo — $override em DataPolicy/UserPreference; $meta.installMethod em Record/Acl/Alias/UserPreference; ACL field aceita nomes de campos conhecidos, colunas do sistema ou '*'; Table accessibleFrom agora tem como padrão 'public'.
Nova ferramenta CLI — query_fluent_records encapsula now-sdk query para consultas REST de Tabela somente leitura (saída de envelope JSON).

Anteriormente (4.7.x)

Esta versão do servidor MCP acompanhou @servicenow/sdk 4.7.x e adicionou suporte para as seguintes APIs Fluent e melhorias do SDK:

Novo tipo de metadados: data-policy — a API DataPolicy (sys_data_policy2) para aplicação obrigatória/somente leitura de campos no lado do servidor que não pode ser contornada via API, importação ou serviço web.
Tratamento de erros e paralelismo em Flow — wfa.flowLogic.tryCatch, wfa.flowLogic.doInParallel e wfa.flowLogic.appendToFlowVariables (anexar a variáveis de fluxo Array.Object).
Estágios de Flow — declare stages com FlowStage({ label, value, … }) e ative-os no corpo via wfa.stage(...) para rastreamento de progresso.
Aumentos de tabela — adicione colunas a uma tabela existente de plataforma/escopo cruzado via Table({ augments: '<table>', schema }); colunas adicionadas devem usar o prefixo de propriedade do aplicativo atual: <scope>_ em um escopo personalizado nomeado (por exemplo, x_acme_), ou u_ em contextos global e de aplicativos da Store.
AI Agent — novo agentDescriptor; dataAccess aceita roleMap (nomes de funções) ou roleList (sys_ids de funções).
NASK — securityControls aceita roleMap (nomes de funções) junto com roleRestrictions (sys_ids de funções).
Substituição universal de campo ($override) — saída de escape em construtores Fluent para definir colunas não modeladas pelo nome da coluna do banco de dados.
Política de proteção — protectionPolicy documentado em APIs baseadas em sys_policy (Action, Subflow, regras de negócio, REST com script, etc.).
CLI — fluent_transform ganha --table/--id (transformar por hierarquia de tabela); init ganha o modelo typescript.vue; OAuth client_credentials para CI/CD via variáveis de ambiente SN_SDK_* (consulte Configuração).
MCP — ferramentas de leitura agora retornam structuredContent (com outputSchema declarado); comandos de longa duração emitem notificações de progresso.

Anteriormente (4.6.0)

Adicionados tipos de metadados custom-action, inbound-email-action, sp-header-footer e sp-page-route-map; a API declarativa Form; subflow-de-subflow e ações personalizadas em flows; geração automática de ACL AIAF; melhorias de tipo de saída/entrada NASK; substituições de dicionário Table; e um comando explain sem projeto com pesquisa de tags, --list, --peek e --format=raw.

Configuração

Requisitos: Node.js 20.18.0+, npm 11.4.1+, @servicenow/sdk 4.11.2

Configuração do Cliente MCP

Adicione ao seu arquivo de configuração do cliente MCP:

{
  "mcpServers": {
    "fluent-mcp": {
      "command": "npx",
      "args": ["-y", "@modesty/fluent-mcp"],
      "env": {
        "FLUENT_MCP_WORKING_DIR": "/absolute/path/to/your/fluent-project",
        "SN_INSTANCE_URL": "https://your-instance.service-now.com",
        "SN_AUTH_TYPE": "basic",
        "SN_USER_NAME": "local-username",
        "SN_PASSWORD": "local-password"
      }
    }
  }
}

Locais Específicos do Cliente:

Claude Desktop / macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
VSCode Copilot: .vscode/mcp.json (use a Paleta de Comandos: MCP: Add Server...)
Cursor: Configurações → Recursos → Configurações MCP
Windsurf: Configurações → Cascade → Servidores MCP → Ver configuração bruta
Gemini CLI: ~/.gemini/settings.json

Nota do VSCode: Para VSCode, a estrutura JSON usa "mcp": { "servers": { ... } } em vez de "mcpServers".

Variáveis de Ambiente:

Variável	Descrição	Padrão
`FLUENT_MCP_WORKING_DIR`	Caminho absoluto do projeto Fluent usado após as fontes por chamada e sessão inicializada; quando também ausente, comandos de projeto falham com orientação acionável	-
`SN_INSTANCE_URL`	URL da instância ServiceNow para validação de autenticação automática	-
`SN_AUTH_TYPE`	Método de autenticação: `basic` ou `oauth`	`oauth`
`SN_USER_NAME`	Nome de usuário para autenticação básica (informativo)	-
`SN_PASSWORD`	Senha para autenticação básica (informativa)	-
`FLUENT_MCP_LOG_LEVEL`	Severidade mínima de log em stderr (`debug`, `info`, `notice`, `warning`, `error`, etc.)	`info`

Nota: No primeiro comando que exige autenticação (ou check_auth_status), o servidor detecta um perfil de autenticação existente correspondente a SN_INSTANCE_URL, armazena-o na sessão e o injeta automaticamente. Chamadas iniciais concorrentes compartilham uma promessa de validação. Um novo perfil é adicionado automaticamente apenas quando a configuração pode ser concluída de forma não interativa (autenticação básica com SN_USER_NAME/SN_USERNAME + SN_PASSWORD); caso contrário, o servidor emite um único aviso com o comando manual auth --add para executar.

Registro de Logs

O servidor grava seu fluxo completo de logs estruturados em stderr para que stdout permaneça reservado para o tráfego do protocolo MCP. Configure a severidade mínima antes do lançamento com FLUENT_MCP_LOG_LEVEL (padrão info; use debug para incluir saída bruta do CLI do SDK). logging/setLevel e notifications/message em tempo de execução não são usados intencionalmente.

Autenticação CI/CD (não interativa) — SDK v4.7.0+

Para pipelines headless, o CLI do SDK ServiceNow lê credenciais diretamente das variáveis de ambiente SN_SDK_* (o servidor MCP herda e repassa essas variáveis para comandos gerados — nenhuma configuração extra necessária). Defina SN_SDK_NODE_ENV=SN_SDK_CI_INSTALL para habilitar o modo CI, então:

Variável	Obrigatória	Valor
`SN_SDK_NODE_ENV`	sim	`SN_SDK_CI_INSTALL`
`SN_SDK_AUTH_TYPE`	para oauth	`basic` (padrão) ou `oauth`
`SN_SDK_INSTANCE_URL`	sim	URL completa da instância
`SN_SDK_USER` / `SN_SDK_USER_PWD`	básico	Nome de usuário / senha
`SN_SDK_OAUTH_CLIENT_ID` / `SN_SDK_OAUTH_CLIENT_SECRET`	oauth	Credenciais do aplicativo OAuth `client_credentials`

OAuth usa a concessão client_credentials contra /oauth_token.do. Consulte o guia ci-integration do SDK (via explain_fluent_api) para detalhes de configuração da instância.

Exemplos de Uso

Fluxo de Trabalho Típico

Inicializar Projeto

Create a new Fluent app in ~/projects/asset-tracker for IT asset management

Desenvolver com Recursos

Show me the business-rule API specification and provide an example snippet

Compilar e Implantar

Build the app with debug output, then deploy it

Nota: A autenticação é validada de forma preguiçosa usando SN_INSTANCE_URL e SN_AUTH_TYPE; essas configurações não substituem um perfil de autenticação do SDK, a menos que a configuração não interativa possa ser concluída. Se você precisar configurar um novo perfil, execute: npx @servicenow/sdk auth --add <instance-url> --type <basic|oauth> --alias <alias>

Testando com o MCP Inspector

O MCP Inspector fornece uma interface web para testar servidores MCP.

Iniciar o Inspector

# Test published package
npx @modelcontextprotocol/inspector npx @modesty/fluent-mcp

# Or for local development (built server)
npm run build && npm run inspect

# Or against the TypeScript entry point, no build required
npm run inspect:dev

O que verificar

A aba Ferramentas mostra todas as 17 ferramentas em ordem de nome determinística.
Parâmetros opcionais são renderizados com seus tipos normais, em vez de formas de união anuláveis.
Logs estruturados do servidor aparecem na saída stderr/terminal do processo do servidor; stdout permanece reservado para o tráfego do protocolo MCP.

Cenários de Teste

Cenário 1: Explorar Recursos de Regras de Negócio

Objetivo: Acessar especificações de API e trechos de código para regras de negócio

Passos:

Inicie o Inspector e aguarde a conexão do servidor
Navegue até a aba Recursos
Encontre e clique em sn-spec://business-rule na lista de recursos
Revise a especificação da API mostrando todos os métodos e parâmetros disponíveis
Volte e pesquise por sn-snippet://business-rule/0001
Clique no trecho para visualizar um exemplo completo em TypeScript
Verifique se o conteúdo inclui importações adequadas e segue os padrões Fluent

Resultados Esperados:

A especificação da API exibe documentação estruturada com assinaturas de métodos
O trecho mostra código TypeScript executável com padrões de metadados ServiceNow
O conteúdo está formatado corretamente e legível

Cenário 2: Testar Comando de Informações do SDK

Objetivo: Verificar a versão do SDK e a recuperação de informações de ajuda