Fluent (ServiceNow SDK)

Gestiona metadatos, módulos, registros y pruebas de ServiceNow usando Fluent, un DSL declarativo basado en TypeScript. Soporta todos los comandos CLI del SDK de ServiceNow.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP Fluent

Un servidor MCP que lleva las capacidades del SDK Fluent de ServiceNow a entornos de desarrollo asistidos por IA. Permite la interacción en lenguaje natural con comandos del SDK de ServiceNow, especificaciones de API, fragmentos de código y recursos de desarrollo.

Construido para @servicenow/sdk@v4.11.2.

Nota: Desde la v0.6.0, el servidor habla tanto MCP@2026-07-28 como MCP@2025-11-25 desde un mismo conjunto de manejadores: la entrada stdio inspecciona el mensaje de apertura y atiende la era con la que el cliente se conecta. v0.5.1 es la última versión construida sobre el SDK MCP v1 (solo 2025-11-25).

Características principales

Herramientas de comandos del SDK - sdk_info más herramientas de comandos del SDK de ServiceNow para init, build, install, dependencies, transform, download, clean, pack, explain, query y cicd
Recursos enriquecidos - Especificaciones de API, instrucciones y fragmentos de código para 70 tipos de metadatos de ServiceNow
Consulta de documentación de API - explain_fluent_api devuelve documentación del SDK para cualquier API o guía de Fluent, sin necesidad de un proyecto
Autenticación automática diferida - Detecta y almacena en caché un perfil de autenticación solo cuando un comando que requiere autenticación o check_auth_status lo necesita
Contexto de proyecto explícito - Resuelve cada comando de proyecto desde su argumento workingDirectory, la sesión inicializada o FLUENT_MCP_WORKING_DIR, y falla con orientación accionable en lugar de adivinar
Paquete MCPB - Construye una distribución .mcpb autocontenida con el servidor, los recursos y las dependencias de producción
Esquemas amigables para el cliente - Las entradas opcionales anuncian sus tipos de valor canónicos mientras que el esquema aplicado acepta null como una forma de compatibilidad para valores omitidos

Este servidor MCP implementa la especificación del Protocolo de Contexto de Modelo con las siguientes capacidades:

Núcleo

Recursos - Más de 300 recursos en 70 tipos de metadatos de ServiceNow (especificaciones de API, instrucciones, fragmentos, indicaciones)
Herramientas - 13 herramientas de comandos del SDK de ServiceNow más 4 herramientas de recursos/autenticación (17 en total), con validación completa de parámetros. Las herramientas de lectura (get-api-spec, get-snippet, get-instruct, check_auth_status) declaran un outputSchema y devuelven structuredContent para consumidores programáticos
Indicaciones - Plantillas de flujo de trabajo de desarrollo para tareas comunes de ServiceNow (coding_in_fluent, create_custom_ui)
Registro y progreso - Los registros estructurados se escriben en stderr; se envían notificaciones de progreso para comandos de larga duración (cualquier comando con un tiempo de espera de 30 segundos o más: deploy, build, transform, download, dependencies, query, pack, cicd) cuando el cliente proporciona un token de progreso

Contexto de proyecto y sesiones

El servidor no requiere capacidades del cliente y no emite solicitudes servidor→cliente: no se utilizan Roots, Sampling ni Elicitation (MCP 2026-07-28 eliminó las solicitudes iniciadas por el servidor, y toda la entrada llega con los argumentos tools/call). La detección automática del espacio de trabajo mediante Roots ya no está disponible para ningún cliente, incluidos los hosts MCPB.

Gestión de sesiones - Realiza un seguimiento del directorio establecido por init_fluent_app para comandos de proyecto posteriores
Resolución del directorio de trabajo - Argumento de herramienta workingDirectory → sesión inicializada → FLUENT_MCP_WORKING_DIR → fallo accionable. Las rutas aceptadas son rutas absolutas no vacías distintas de la raíz del sistema de archivos. El servidor nunca adivina desde su cwd de proceso o el directorio del paquete instalado. Los clientes deben pasar workingDirectory o configurar FLUENT_MCP_WORKING_DIR cuando no exista un directorio de sesión.
init_fluent_app no interactivo - Los argumentos específicos de la intención deben proporcionarse con la llamada (creación: appName, packageName, scopeName, template; conversión: from); un argumento faltante falla con un error que nombra exactamente lo que falta. La herramienta no solicita ni obtiene valores faltantes.
Manejo de errores - Mensajes de error completos con orientación accionable
Seguridad de tipos - Implementación completa en TypeScript con tipado estricto

Comportamiento del protocolo

stdio de doble era: una apertura de 2026-07-28 (envoltura _meta por solicitud, server/discover) y un initialize de 2025-11-25 se atienden desde el mismo conjunto de manejadores; el punto de entrada del SDK fija una era por conexión.
Los seis resultados almacenables en caché de 2026-07-28 (tools/list, prompts/list, resources/list, resources/templates/list, resources/read, server/discover) anuncian ttlMs: 3600000 / cacheScope: 'public': todo lo que devuelven es estático durante la vida del proceso.
El servidor anuncia instrucciones durante la inicialización; tools/list es una lectura sin efectos secundarios que devuelve herramientas en orden determinista de nombres.
Los argumentos opcionales de las herramientas anuncian sus tipos JSON canónicos para que los clientes rendericen campos de formulario normales. El esquema de llamada aplicado además acepta null como valor omitido; workingDirectory también trata una cadena vacía como omitida antes de aplicar la cadena de respaldo.
Los registros estructurados van a stderr, manteniendo stdout reservado para el tráfico del protocolo MCP. No se utilizan logging/setLevel ni notifications/message en tiempo de ejecución.
Las fallas de recursos usan el código estándar de parámetros no válidos de JSON-RPC (-32602).

Inicio 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)

Distribución MCPB

El comando opcional npm run bundle produce fluent-mcp-<version>.mcpb. El paquete contiene dist/, res/ y las dependencias de producción, y su manifest.json declara las 17 herramientas. Los hosts MCPB exponen estos valores configurables por el usuario al servidor:

FLUENT_MCP_WORKING_DIR — directorio de proyecto predeterminado opcional; de lo contrario, pase workingDirectory en llamadas de herramientas conscientes del proyecto
SN_INSTANCE_URL — URL de instancia opcional para la validación de autenticación diferida
SN_AUTH_TYPE — tipo de autenticación (basic o oauth, predeterminado oauth)

El paquete npm sigue siendo el canal de distribución principal. MCPB no restaura la detección del espacio de trabajo basada en Roots ni la solicitud interactiva de init_fluent_app.

Ejemplo de indicación:

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

Herramientas disponibles

Herramientas de comandos del SDK (13)

Herramienta	Descripción	Parámetros clave
`sdk_info`	Obtener versión del SDK o ayuda	`flag` (-v/-h), `command` (opcional para -h)
`explain_fluent_api`	Consultar documentación del SDK de Fluent para cualquier API o guía. No se requiere un proyecto Fluent.	`topic` (nombre de API/guía opcional o palabra clave de etiqueta: requerido a menos que `list=true`), `list` (booleano: listar temas), `peek` (booleano: resumen breve), `format` (`pretty`\|`raw`), `source` (anulación de ruta de proyecto opcional), `debug` (opcional)
`init_fluent_app`	Inicializar o convertir una aplicación de ServiceNow. No interactivo: los argumentos faltantes específicos de la intención fallan con un error que los nombra.	`intent`, `from` (conversión), `appName`/`packageName`/`scopeName`/`template` (creación), `auth`, `workingDirectory` (requerido), `debug`
`build_fluent_app`	Compilar la aplicación	`workingDirectory`, `debug` (opcional)
`deploy_fluent_app`	Desplegar en una instancia de ServiceNow. La activación del flujo del SDK se puede omitir.	`workingDirectory`, `auth` (inyección automática), `skipFlowActivation`, `debug`
`fluent_transform`	Convertir XML o metadatos de instancia a TypeScript de Fluent. Las rutas locales no requieren autenticación; las transformaciones de instancia sí.	`workingDirectory`, `from`, `directory`, `auth` (inyección automática), `table`, `id`, `debug`
`download_fluent_dependencies`	Descargar dependencias y definiciones de tipos	`workingDirectory`, `auth` (inyección automática), `debug`
`download_fluent_app`	Descargar metadatos de una instancia	`workingDirectory`, `directory` (requerido), `source`, `auth` (inyección automática), `incremental`, `debug`
`clean_fluent_app`	Limpiar el directorio de salida	`workingDirectory`, `source` (opcional), `debug`
`pack_fluent_app`	Crear un artefacto instalable	`workingDirectory`, `source` (opcional), `debug`
`query_fluent_records`	Consulta REST de tabla de solo lectura contra una instancia; devuelve un envoltorio JSON	`workingDirectory`, `table` (requerido), `query` (consulta codificada requerida), `fields`, `limit`, `offset`, `displayValue`, `view`, `queryCategory`, `excludeReferenceLink`, `noCount`, `queryNoDomain`, `timeout`, `select`, `auth` (inyección automática), `debug`
`cicd_fluent_app`	Instalar, publicar o revertir una aplicación mediante la API de CI/CD de ServiceNow (`sn_cicd`). Cambia el estado de la instancia.	`workingDirectory`, `action` (requerido: `install`\|`publish`\|`rollback`), `scope`\|`appSysId`, `appVersion` (requerido para revertir, y para instalar/publicar fuera de un proyecto Fluent), `baseAppVersion`, `autoUpgradeBaseApp`, `devNotes`, `wait`, `pollTimeout`, `auth` (inyección automática), `output` (`json`\|`raw`), `select`, `debug`
`cicd_fluent_test`	Ejecutar, supervisar u obtener resultados de suites y pruebas ATF mediante la API de CI/CD. `run` ejecuta pasos ATF reales en la instancia. No se requiere un proyecto Fluent (ni se acepta).	`target` (requerido: `testsuite`\|`test`), `action` (requerido: `run`\|`watch`\|`result`), `testSuiteSysId`\|`testSuiteName`, `testSysId`\|`testName`, `progressId` (supervisar), `resultId` (resultado), `browserName`, `browserVersion`, `osName`, `osVersion`, `runInCloud`, `isPerformanceRun`, `captureNodeLogs`, `wait`, `pollTimeout`, `auth` (inyección automática), `output` (`json`\|`raw`), `select`, `debug`

Herramientas de recursos y autenticación (4)

Herramienta	Descripción	Parámetros clave
`get-api-spec`	Obtener una especificación de API o listar todos los tipos de metadatos disponibles	`metadataType` (opcional; omitir para listar todos)
`get-snippet`	Obtener un fragmento de código de Fluent; sin `id`, devuelve el primer fragmento disponible y cualquier ID de fragmento adicional	`metadataType` (requerido), `id` (opcional)
`get-instruct`	Obtener orientación de autoría, convenciones y errores comunes para un tipo de metadatos	`metadataType` (requerido)
`check_auth_status`	Validar de forma diferida la autenticación de ServiceNow configurada y devolver información de estado estructurada	Sin argumentos

Nota: La autenticación se valida de forma diferida en el primer comando que requiere autenticación o check_auth_status, y luego se almacena en caché para la sesión. Use init_fluent_app para establecer el contexto del proyecto, pase workingDirectory por llamada o configure FLUENT_MCP_WORKING_DIR. Cualquier argumento opcional enviado como null se trata como omitido; workingDirectory también trata una cadena vacía como omitida y continúa con la siguiente fuente.

Consulta de APIs de Fluent con `explain_fluent_api`

explain_fluent_api envuelve now-sdk explain y devuelve documentación del SDK para cualquier clase de API de Fluent o guía temática. Funciona desde cualquier directorio: no se requiere un proyecto Fluent.

Invocación	Resultado
`explain_fluent_api({ topic: 'BusinessRule' })`	Referencia completa de la API para `BusinessRule`
`explain_fluent_api({ topic: 'BusinessRule', peek: true })`	Resumen breve de `BusinessRule`
`explain_fluent_api({ topic: 'BusinessRule', format: 'raw' })`	Referencia completa de la API como markdown plano (útil para canalizar a otras herramientas)
`explain_fluent_api({ list: true })`	Índice completo de temas (todas las APIs y guías)
`explain_fluent_api({ list: true, topic: 'atf' })`	Índice de temas filtrado a entradas que coinciden con `atf`
`topic` coincide con un nombre de API (p. ej. `BusinessRule`, `Acl`), un nombre de guía (p. ej. `business-rule-guide`, `atf-guide`) o una palabra clave de etiqueta (p. ej. `flow`, `atf`, `email`). El SDK resuelve primero por nombre exacto y luego por etiqueta.

Recursos

Patrones de URI estandarizados según la especificación MCP:

Tipo de recurso	Patrón de URI	Ejemplo	Propósito
Especificaciones de API	`sn-spec://{type}`	`sn-spec://business-rule`	Documentación y parámetros de API
Instrucciones	`sn-instruct://{type}`	`sn-instruct://script-include`	Prácticas recomendadas y orientación
Fragmentos de código	`sn-snippet://{type}/{id}`	`sn-snippet://acl/0001`	Ejemplos prácticos de código
Indicaciones	`sn-prompt://{id}`	`sn-prompt://coding_in_fluent`	Guías de desarrollo

Tipos de metadatos admitidos

71 tipos de metadatos en las siguientes categorías:

Tipos principales: 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 tabla: column, column-generic

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

Correo electrónico: email-notification, inbound-email-action

Automatización y flujos de trabajo: flow, custom-action, playbook

Integración y conexiones: alias, alias-template, retry-policy, rest-message, data-lookup, graphql-api

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

Portal de servicios: service-portal, sp-header-footer, sp-page-route-map

Espacio de trabajo y análisis: workspace, dashboard

ATF (Marco de pruebas automatizadas): atf (el contenedor Test() y el punto de entrada de la familia: comience aquí y luego enrute a un subtipo de paso), 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

Novedades en 4.11.2

Esta versión del servidor MCP sigue a @servicenow/sdk 4.11.2 y cubre las adiciones a la superficie de creación publicadas en 4.11.0 y 4.11.2 (4.11.1 nunca se publicó en npm, y 4.11.2 no incluyó notas de versión; su superficie se estableció comparando el paquete instalado):

Nuevo tipo de metadatos: test-suite — la API TestSuite agrupa registros ATF Test() existentes en una suite con nombre, ordenable y opcionalmente anidada, escribiendo sys_atf_test_suite más una fila de membresía sys_atf_test_suite_test por entrada. El orden de ejecución proviene de la posición en el arreglo, no de un campo creado. Es solo de creación: nunca activa ni programa una ejecución; use la interfaz de ATF, el programador o cicd_fluent_test.
Nuevo tipo de metadatos: graphql-api — la API GraphQLApi define una API GraphQL con script (sys_graphql_schema) con sus resolvers, resolvers de tipo y seguridad de dos niveles: ACL de puerta de esquema en toda la API más ACL de ruta Acl({ type: 'graphql' }) independientes a nivel de campo. Los paths de resolver usan Type:field; los nombres de ACL usan la ruta de consulta en tiempo de ejecución separada por barras.
Nuevo tipo de metadatos: field-style — sys_ui_style ahora es una tabla Record() admitida, lo que hace que el estilo condicional de campos de listas y formularios se pueda crear en Fluent (no hay constructor FieldStyle()). style acepta cualquier propiedad CSS, por lo que también es el mecanismo para el width y el text-align de columnas de listas.
Bucle do-while en Flow — wfa.flowLogic.doTheFollowing({ $id, label?, annotation? }, () => { ... }) repite un cuerpo hasta que wfa.flowLogic.until('<condition>'), llamado como la última instrucción del cuerpo, se cumpla. El cuerpo siempre se ejecuta al menos una vez y la condición puede hacer referencia a salidas de acciones dentro del mismo cuerpo, lo que lo convierte en la construcción adecuada para sondeos y reintentos.
Ejecución bajo demanda de playbooks — executionType se amplió a 'record_driven' | 'on_demand'. Un playbook independiente debe omitir triggers por completo, no puede establecer parentTable ni hacer referencia a params.parentRecord, puede finalmente establecer allowAsNested: true y debe otorgar launch: true en al menos un conjunto de permisos o la compilación falla.
Permisos de playbook — nuevo permissions en el argumento 2 (una devolución de llamada, para que las píldoras puedan alcanzar params.parentRecord) y en cada LaneConfig (un objeto simple), cada uno agrupando users/userGroups/roles/userCriterias. En un playbook, view es obligatorio y controla todas las demás banderas; en un carril, las cuatro banderas son independientes. wfa.playbook.activityRef(Now.ID['x']) alcanza las salidas de una actividad desde dentro de un bloque de permisos.
Actividades opcionales de playbook — startRule: wfa.playbook.run.Manually() declara una actividad que un usuario inicia manualmente. Devuelve un ManualActivityReference sin salidas que está deliberadamente fuera de la unión de dependencias: como puede que nunca se ejecute, nada puede esperarlo con run.After().
Lanzador y salidas de playbook — launcherTitle, launcherDescription y launcherInputs configuran el lanzador bajo demanda; los campos de formulario de registro (launcherShowRecordForm, launcherRecordFormView, launcherTemplateFields) pertenecen a playbooks impulsados por registros. La nueva actividad OOB ActivityDefinitions.Core.SetPlaybookOutputs escribe el outputs declarado por el propio playbook.
Actividades de agente de IA en playbooks — la configuración del agente de IA se expone en las cuatro definiciones OOB que optaron por participar (RecordForm, AutocompletingRecordForm, NewRecordForm, EmailForm). aiAgentObjective se vuelve obligatorio una vez que enableAiAgent es verdadero. El SDK no valida ningún requisito previo de plataforma (sn_genai_platform instalado, sn_pa_designer.enable_agentic_playbooks verdadero).
Entradas de registros dependientes — UpdateRecord/CreateNewRecord ahora verifican el tipo de una píldora record contra la entrada table_name hermana, y Action() lleva rawInputs para el mismo propósito, por lo que una píldora de tabla incorrecta es un error de compilación en lugar de una sorpresa en tiempo de ejecución.
Table.sizeClass y List.domain — Table acepta sizeClass?: number; List acepta domain?: string (el sys_domain aplicado a la lista, con valor predeterminado 'global').
17 nuevas tablas direccionables por Record() (176 → 193), incluidas sys_ui_style, cmn_schedule_span (entradas de programación), business_calendar_span, cmdb, sysrule_view_workspace y sysevent_script_action.

Nota sobre la fuente de verdad: cinco afirmaciones de las notas de versión no están corroboradas por el paquete instalado y se trataron como correcciones. doTheFollowingUntil no fue "reelaborado": ese identificador no existe ni en 4.10.1 ni en 4.11.2; la construcción es nueva y se crea como doTheFollowing + until. enforceAcl no es un booleano seguro por defecto: es un arreglo de referencia de ACL con valor predeterminado vacío, es decir, sin puerta de esquema (solo los tres booleanos requires* y contextualAclMaxDepth son seguros por defecto). La afirmación sobre nuevas tablas está subestimada: se agregaron 17 tablas, no 2. Un script de resolver GraphQL no puede ser un literal de función en línea aunque el tipo acepte una función. Y los campos de formulario de registro launcher* están prohibidos en executionType: 'on_demand', lo contrario de lo que sugiere "Configuraciones del lanzador bajo demanda". Por separado, el elemento "Decimal dentro de FlowObject/FlowArray" es una corrección de la canalización de compilación, no un cambio de tipo: FlowTypes.d.ts y db/types/Decimal.d.ts son byte-idénticos a 4.10.1. Consulte .mosey/upgrade-sdk-4.11.2.md.

Anteriormente (4.10.x)

Adiciones a la superficie de creación publicadas en @servicenow/sdk 4.10.0 y 4.10.1:

Nuevo tipo de metadatos: state-model — la API StateModel define la máquina de estados de una tabla (estados, transiciones y las condiciones que las controlan) en una sola llamada, escribiendo registros sttrm_model/sttrm_state/sttrm_state_transition/sttrm_transition_condition, o la subclase chg_model/prb_model/prb_task_model seleccionada automáticamente desde table. También puede editar modelos estándar en su lugar haciendo referencia a sus sys_ids reales.
Nuevo tipo de metadatos: atf-list — los pasos ATF atf.list.* (relatedListVisibility, applyFilterToList, recordPresentInList, openRecordInList, listUIActionVisibility, clickListUIAction) ejercitan el comportamiento de la interfaz de listas y listas relacionadas.
Nuevas herramientas: cicd_fluent_app (instalar/publicar/revertir una aplicación a través de la API sn_cicd — cambia el estado de la instancia) y cicd_fluent_test (ejecutar, observar u obtener resultados de suites y pruebas ATF), que envuelven el nuevo comando now-sdk cicd. query_fluent_records gana select para el nuevo extractor de rutas --select.
$meta.useEsLatest — nueva bandera transversal que ejecuta los campos de script de un registro en la versión más reciente de ECMAScript que admite la plataforma. Alcanza las API cuyo tipo lleva $meta (rutas BusinessRule, Acl, ScriptInclude, ScriptAction, ScheduledScript, UiPage, RestApi, SPWidget, SPMenu y otras) — no todas las API con un campo de script del lado del servidor: las condiciones de transición StateModel son scripts del lado del servidor cuyo tipo no acepta ningún $meta (consulte la nota sobre la fuente de verdad a continuación).
Forma de objeto de tabla actions — actions ahora acepta la forma exportada TableActionAccess { read?, update?, delete?, create? }, donde cada acción tiene tres estados. La forma de arreglo está en desuso: es una enumeración completa, por lo que actions: ['read'] también escribe los otros tres como false. El SDK ya no deriva valores predeterminados para actions, allowClientScripts, allowNewFields, allowUiActions, allowWebServiceAccess o maxLength.
Columna de referencia mtom — crea una relación de muchos a muchos. Observe la división semántica: referenceKey ya no significa muchos a muchos y ahora almacena un campo de la tabla referenciada en lugar de sys_id.
Iconos de acciones de interfaz — los objetos form y list de UiAction aceptan iconName y showIconOnly.
Form $meta — Form ahora respeta $meta.installMethod para enrutar su carpeta de salida (antes se aceptaba pero era inerte).
timerSchedule de playbook — startWithDelay puede evaluar su retraso contra un registro cmn_schedule en lugar del tiempo de reloj transcurrido, en las tres variantes.
Valores predeterminados dinámicos de catálogo — el dependentQuestion de una variable se amplió para aceptar un ReferenceVariable/RequestedForVariable además de una cadena de nombre; las acciones CatalogUiPolicy aceptan variable y CatalogClientScript acepta order.
$override en campos sys_* — $override puede establecer sys_domain y la mayoría de las otras columnas sys_* en cualquier tabla; sys_id, sys_scope, sys_update_name y sys_domainpath siguen siendo administrados por el marco y generan error si se sobrescriben.
Portal de servicios — los campos CSS de widgets/páginas/instancias aceptan SCSS o CSS, widgetParameters ahora serializa correctamente un objeto simple, las propiedades de marcador de posición de SPInstance son funcionales en lugar de ignoradas y urlSuffix acepta guiones. La especificación service-portal también ganó la API ServicePortal() (sp_portal) previamente no documentada.

Nota sobre la fuente de verdad: varias afirmaciones de las notas de versión no están corroboradas por el paquete instalado y se trataron como correcciones — las "preguntas dependientes" son un valor predeterminado dinámico, no un control de visibilidad u opciones (y la propiedad no es nueva, solo se amplió su tipo); runServerSideScript "soporte de superficie" ya se incluyó en 4.9.0; y el cambio de inferencia de add_message es una corrección interna de transformación sin cambios en la superficie de autoría. La guía general también enumera StateModel, AliasTemplate, InboundEmailAction, CatalogItem, CatalogItemRecordProducer y las comprobaciones de escaneo de instancias como aceptando $meta.useEsLatest, pero sus declaraciones no incluyen $meta. Ver .mosey/upgrade-sdk-4.10.1.md.

Anteriormente (4.9.x)

Esta versión del servidor MCP sigue a @servicenow/sdk 4.9.0 — una versión de mantenimiento y corrección de errores (confiabilidad de Flow, ClientScript, ImportSet, transformación/construcción de SLA) con adiciones selectivas a la superficie de autoría:

Nuevo tipo de metadatos: atf-ui-test-script — el paso ATF atf.uiTestScript.runTest() ejecuta un cuerpo de prueba TestingLibrary en el ejecutor de pruebas del cliente para probar componentes de UI personalizados (widgets Angular/React, SPAs embebidas, espacios de trabajo personalizados, componentes web now-*) que los pasos estándar atf.form.* / atf.catalog.* no pueden alcanzar.
Etiquetas de opción multilingües — el valor choices de un campo de opción puede ser un arreglo de objetos ChoiceConfig, cada uno con una clave language (BCP 47), produciendo un registro sys_choice traducido por idioma.
protectionPolicy en AI Agent y AI Agentic Workflow — AiAgent y AiAgenticWorkflow aceptan protectionPolicy: 'read' | 'protected' para control de acceso posterior a la instalación.
Role.federatedId — identificador opcional para hacer coincidir un rol con un rol federado externamente durante la federación de identidades.
Columnas de plataforma de índice de tabla — la entrada index de una tabla puede hacer referencia a columnas predeterminadas de la plataforma en su element (por ejemplo, sys_created_on).
Proveedores de Now Assist Skill Kit — nuevos proveedores de LLM seleccionables por nombre: Now LLM LTS Generic, Google Cloud Vertex AI, Amazon Bedrock.

Nota sobre la fuente de verdad: dos afirmaciones de las notas de versión no están corroboradas por el paquete instalado y se trataron como correcciones — Form table_field.field está documentado como un nombre de columna de esquema (no ampliado a "cualquier cadena"), y las cuatro cadenas de modelo NASK nombradas no aparecen en ningún lugar del paquete (model es una cadena libre). Ver .mosey/upgrade-sdk-4.9.0.md.

Anteriormente (4.8.x)

Esta versión del servidor MCP sigue a @servicenow/sdk 4.8.0 y agrega soporte para las siguientes APIs de Fluent y mejoras del SDK:

Nuevo tipo de metadatos: playbook — la API PlaybookDefinition (sys_pd_process_definition, de @servicenow/sdk/automation) para procesos guiados de múltiples pasos basados en registros con carriles, actividades, disparadores y entradas/salidas.
Nuevo tipo de metadatos: rest-message — la API RestMessage (sys_rest_message) para integraciones HTTP salientes con autenticación/encabezados compartidos y funciones invocables.
Nuevos tipos de metadatos: alias y alias-template — las APIs Alias (sys_alias) y AliasTemplate (sys_alias_templates) para alias de Conexión y Credencial y plantillas reutilizables de configuración de conexiones.
Nuevo tipo de metadatos: retry-policy — la API RetryPolicy (sys_retry_policy) que controla el manejo de fallas transitorias para conexiones (intervalo fijo, retroceso exponencial o Retry-After).
Nuevo tipo de metadatos: data-lookup — la API DataLookup (dl_definition) que copia automáticamente valores de campo de una tabla de coincidencia a un registro fuente.
Eliminación declarativa (Now.del()) — declaración de nivel superior para eliminar registros por claves de coalescencia o sys_id.
Mejoras de tipos — $override en DataPolicy/UserPreference; $meta.installMethod en Record/Acl/Alias/UserPreference; ACL field acepta nombres de campo conocidos, columnas del sistema o '*'; Table accessibleFrom ahora tiene como valor predeterminado 'public'.
Nueva herramienta CLI — query_fluent_records envuelve now-sdk query para consultas REST de Tabla de solo lectura (salida de sobre JSON).

Anteriormente (4.7.x)

Esta versión del servidor MCP siguió a @servicenow/sdk 4.7.x y agregó soporte para las siguientes APIs de Fluent y mejoras del SDK:

Nuevo tipo de metadatos: data-policy — la API DataPolicy (sys_data_policy2) para aplicación obligatoria de campos de solo lectura en el lado del servidor que no se puede eludir mediante API, importación o servicio web.
Manejo de errores y paralelismo en Flow — wfa.flowLogic.tryCatch, wfa.flowLogic.doInParallel y wfa.flowLogic.appendToFlowVariables (agregar a variables de flujo Array.Object).
Etapas de Flow — declarar stages con FlowStage({ label, value, … }) y activarlas en el cuerpo mediante wfa.stage(...) para el seguimiento del progreso.
Aumentos de tabla — agregar columnas a una tabla existente de plataforma/ámbito cruzado mediante Table({ augments: '<table>', schema }); las columnas agregadas deben usar el prefijo de propiedad de la aplicación actual: <scope>_ en un ámbito personalizado nombrado (por ejemplo, x_acme_), o u_ en contextos globales y de aplicaciones de Store.
AI Agent — nuevo agentDescriptor; dataAccess acepta roleMap (nombres de rol) o roleList (sys_ids de rol).
NASK — securityControls acepta roleMap (nombres de rol) junto con roleRestrictions (sys_ids de rol).
Anulación de campo universal ($override) — vía de escape en constructores de Fluent para establecer columnas no modeladas por nombre de columna de base de datos.
Política de protección — protectionPolicy documentado en APIs respaldadas por sys_policy (Action, Subflow, reglas de negocio, REST con script, etc.).
CLI — fluent_transform gana --table/--id (transformar por jerarquía de tabla); init gana la plantilla typescript.vue; OAuth client_credentials para CI/CD mediante variables de entorno SN_SDK_* (ver Configuración).
MCP — las herramientas de lectura ahora devuelven structuredContent (con outputSchema declarado); los comandos de larga duración emiten notificaciones de progreso.

Anteriormente (4.6.0)

Se agregaron los tipos de metadatos custom-action, inbound-email-action, sp-header-footer y sp-page-route-map; la API declarativa Form; subflujo-de-subflujo y acciones personalizadas en flujos; generación automática de ACL de AIAF; mejoras de tipos de salida/entrada de NASK; anulaciones de diccionario Table; y un comando explain sin proyecto con búsqueda de etiquetas, --list, --peek y --format=raw.

Configuración

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

Configuración del Cliente MCP

Agregue a su archivo de configuración del 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"
      }
    }
  }
}

Ubicaciones específicas del cliente:

Claude Desktop / macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
VSCode Copilot: .vscode/mcp.json (use la Paleta de comandos: MCP: Add Server...)
Cursor: Configuración → Funciones → Configuración de MCP
Windsurf: Configuración → Cascade → Servidores MCP → Ver configuración sin procesar
CLI de Gemini: ~/.gemini/settings.json

Nota de VSCode: Para VSCode, la estructura JSON usa "mcp": { "servers": { ... } } en lugar de "mcpServers".

Variables de entorno:

Variable	Descripción	Predeterminado
`FLUENT_MCP_WORKING_DIR`	Ruta absoluta del proyecto Fluent utilizada después de las fuentes por llamada y de sesión inicializada; cuando también está ausente, los comandos de proyecto fallan con orientación procesable	-
`SN_INSTANCE_URL`	URL de la instancia de ServiceNow para validación de autenticación automática	-
`SN_AUTH_TYPE`	Método de autenticación: `basic` o `oauth`	`oauth`
`SN_USER_NAME`	Nombre de usuario para autenticación básica (informativo)	-
`SN_PASSWORD`	Contraseña para autenticación básica (informativa)	-
`FLUENT_MCP_LOG_LEVEL`	Severidad mínima de registro de stderr (`debug`, `info`, `notice`, `warning`, `error`, etc.)	`info`

Nota: En el primer comando que requiere autenticación (o check_auth_status), el servidor detecta un perfil de autenticación existente que coincida con SN_INSTANCE_URL, lo almacena en la sesión y lo inyecta automáticamente. Las primeras llamadas concurrentes comparten una promesa de validación. Se agrega un nuevo perfil automáticamente solo cuando la configuración puede completarse de forma no interactiva (autenticación básica con SN_USER_NAME/SN_USERNAME + SN_PASSWORD); de lo contrario, el servidor emite un solo aviso con el comando manual auth --add para ejecutar.

Registro

El servidor escribe su flujo completo de registros estructurados en stderr para que stdout permanezca reservado para el tráfico del protocolo MCP. Configure la severidad mínima antes del lanzamiento con FLUENT_MCP_LOG_LEVEL (predeterminado info; use debug para incluir salida sin procesar del CLI del SDK). logging/setLevel y notifications/message en tiempo de ejecución no se usan intencionalmente.

Autenticación CI/CD (no interactiva) — SDK v4.7.0+

Para canalizaciones sin cabeza, el CLI del SDK de ServiceNow lee las credenciales directamente de las variables de entorno SN_SDK_* (el servidor MCP hereda y las pasa a los comandos generados — no se necesita configuración adicional). Establezca SN_SDK_NODE_ENV=SN_SDK_CI_INSTALL para habilitar el modo CI, luego:

Variable	Requerida	Valor
`SN_SDK_NODE_ENV`	sí	`SN_SDK_CI_INSTALL`
`SN_SDK_AUTH_TYPE`	para oauth	`basic` (predeterminado) o `oauth`
`SN_SDK_INSTANCE_URL`	sí	URL completa de la instancia
`SN_SDK_USER` / `SN_SDK_USER_PWD`	básico	Nombre de usuario / contraseña
`SN_SDK_OAUTH_CLIENT_ID` / `SN_SDK_OAUTH_CLIENT_SECRET`	oauth	Credenciales de la aplicación `client_credentials` de OAuth

OAuth usa la concesión client_credentials contra /oauth_token.do. Consulte la guía ci-integration del SDK (mediante explain_fluent_api) para obtener detalles de configuración de la instancia.

Ejemplos de Uso

Flujo de Trabajo Típico

Inicializar Proyecto

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

Desarrollar con Recursos

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

Construir e Implementar

Build the app with debug output, then deploy it

Nota: La autenticación se valida de forma diferida usando SN_INSTANCE_URL y SN_AUTH_TYPE; esas configuraciones no reemplazan un perfil de autenticación del SDK a menos que la configuración no interactiva pueda completarse. Si necesita configurar un nuevo perfil, ejecute: npx @servicenow/sdk auth --add <instance-url> --type <basic|oauth> --alias <alias>

Pruebas con MCP Inspector

El MCP Inspector proporciona una interfaz web para probar servidores MCP.

Iniciar 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

Qué verificar

La pestaña Herramientas muestra las 17 herramientas en orden de nombre determinista.
Los parámetros opcionales se muestran con sus tipos normales en lugar de formas de unión anulables.
Los registros estructurados del servidor aparecen en la salida de stderr/terminal del proceso del servidor; stdout permanece reservado para el tráfico del protocolo MCP.

Escenarios de Prueba

Escenario 1: Explorar Recursos de Reglas de Negocio

Objetivo: Acceder a especificaciones de API y fragmentos de código para reglas de negocio

Pasos:

Inicie Inspector y espere la conexión del servidor
Navegue a la pestaña Recursos
Encuentre y haga clic en sn-spec://business-rule en la lista de recursos
Revise la especificación de API que muestra todos los métodos y parámetros disponibles
Regrese y busque sn-snippet://business-rule/0001
Haga clic en el fragmento para ver un ejemplo completo de TypeScript
Verifique que el contenido incluya importaciones adecuadas y siga los patrones de Fluent

Resultados Esperados:

La especificación de API muestra documentación estructurada con firmas de métodos
El fragmento muestra código TypeScript ejecutable con patrones de metadatos de ServiceNow
El contenido está correctamente formateado y es legible

Escenario 2: Probar el Comando de Información del SDK

Objetivo: Verificar la versión del SDK y la recuperación de información de ayuda