Inistate

Servidor MCP de Inistate

Servidor MCP para la plataforma Inistate: descubrimiento de módulos, gestión de entradas y envío de actividades.

Configuración

Variables de entorno

Variable	Requerida	Predeterminado	Descripción
INISTATE_API_TOKEN	Sí	—	Token Bearer para la autenticación de la API de Inistate
INISTATE_API_BASE	No	https://api.inistate.com	URL base de la API
INISTATE_MCP_MODE	No	configure	Modo inicial: runtime, configure o frontend (consulta Modos)
INISTATE_MCP_NO_SETUP	No	—	Establécelo en 1 para forzar el modo servidor desde una terminal (omite el asistente interactivo)
INISTATE_DEBUG_FILE	No	—	Establécelo en 1 para registrar las llamadas a herramientas de la ruta de escritura en ./debug.log, o en una ruta para registrarlas allí. Desactivado por defecto; registra solo identificadores, nunca valores de campos

Instalación desde npm (recomendada)

No se necesita clonar ni compilar: npx obtendrá y ejecutará el paquete publicado bajo demanda:

npx -y inistate-mcp

O instálalo globalmente:

npm install -g inistate-mcp
inistate-mcp

Configuración interactiva (recomendada)

Ejecuta el binario en una terminal sin un cliente MCP conectado y te guiará para ingresar tu token de API y elegirá el archivo de configuración correcto para tu cliente:

npx -y inistate-mcp
# or, explicitly:
npx -y inistate-mcp setup

Clientes compatibles: Claude Desktop, Claude Code (global o local al proyecto .mcp.json), Cursor, Windsurf, Codex CLI, VS Code (perfil de usuario o espacio de trabajo .vscode/mcp.json), Cline, Gemini CLI (global o espacio de trabajo). Elige "Imprimir solo configuración" para obtener un bloque JSON que puedes pegar en cualquier otro lugar.

El asistente solo se ejecuta cuando la entrada estándar es una TTY (es decir, lo lanzaste tú mismo). Cuando un cliente MCP inicia el binario mediante stdio canalizado, omite el asistente y se ejecuta como un servidor MCP normal: establece INISTATE_MCP_NO_SETUP=1 si necesitas forzar el modo servidor desde una terminal.

Configuración de Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "inistate": {
      "command": "npx",
      "args": ["-y", "inistate-mcp"],
      "env": {
        "INISTATE_API_TOKEN": "your-token-here"
      }
    }
  }
}

Configuración de Claude Code

claude mcp add inistate -e INISTATE_API_TOKEN=your-token-here -- npx -y inistate-mcp

Instalación desde el código fuente

git clone https://github.com/Inistate/inistate-mcp.git
cd inistate-mcp
npm install
npm run build

Luego apunta tu cliente MCP a node /absolute/path/to/inistate-mcp/build/index.js.

Herramientas

Las herramientas marcadas con (configurar) solo se exponen en el modo de configuración; consulta Modos. Las herramientas que el backend activo no puede servir (por ejemplo, scaffold_module en la Plataforma alojada) permanecen registradas pero devuelven un mensaje estructurado de capacidad en lugar de fallar silenciosamente.

Herramienta	Descripción
list_workspaces	Lista los espacios de trabajo a los que el usuario tiene acceso
set_workspace	Establece el espacio de trabajo activo
list_modules	Lista todos los módulos descubribles en el espacio de trabajo
get_module_schema	Obtiene el esquema del lienzo (nivel básico o extendido): disponible en todos los modos
get_module_canvas	Obtiene la definición completa del módulo con IDs estables (con capacidad de ida y vuelta) (configurar)
list_entries	Consulta entradas con filtros, ordenamiento y paginación
get_entry	Lee una sola entrada por ID
get_form	Obtiene los campos de formulario y los valores predeterminados para una actividad
submit_activity	Crea, edita, elimina o ejecuta actividades personalizadas
submit_activities	Variante masiva: la misma actividad aplicada a hasta 100 entradas en una sola llamada
get_entry_history	Obtiene el historial de auditoría y los comentarios de una entrada
request_upload_url	Ruta de carga predeterminada: obtiene una URL S3 prefirmada para enviar los bytes del archivo mediante PUT
confirm_upload	Confirma que una carga prefirmada se completó; devuelve la ruta del campo Archivo/Imagen
upload_file	Carga de respaldo mediante base64/multipart (úsala solo si el flujo prefirmado falla)
download_file	Descarga un archivo (devuelve una URL prefirmada)
design_workflow	Genera una plantilla de módulo estructurada a partir de una descripción (configurar)
validate_design	Valida un esquema de módulo antes de crearlo o actualizarlo (configurar)
create_module	Crea un nuevo módulo con esquema (configurar)
update_module	Actualiza el esquema de un módulo existente (configurar)
scaffold_module	Redacta un esquema de módulo a partir de datos existentes (tabla de SQLite, Notion o Airtable) (configurar) — servido por el runtime local (inistate-core); en el backend de la Plataforma alojada devuelve un mensaje de capacidad que apunta a design_workflow
switch_mode	Cambia el modo activo (runtime / configurar / frontend)

Recursos

URI	Descripción
inistate://modules	Lista todos los módulos
inistate://modules/{name}/canvas	Esquema básico del módulo (campos + estados)
inistate://modules/{name}/canvas/extended	Esquema extendido con actividades y flujos
inistate://guardrails	Reglas de submit_activity aplicadas por el servidor (se leen una vez por sesión)
inistate://schema/runtime	Esquema del runtime: tipos de entrada/actividad/archivo y operadores de filtro (predeterminado)
inistate://schema/configure	Esquema de diseño de módulos: formato de escritura, tipos de campo, colores (configurar)
inistate://design-guide	Guía de diseño de módulos FACTS (configurar)
inistate://frontend-guide	Referencia de la API REST para interfaces de usuario escritas a mano (frontend)

Prompts

Prompt	Descripción
design_factsops_workflow	Guía a un agente para diseñar un módulo de flujo de trabajo completo (configurar)
execute_activity	Guía a un agente para ejecutar una actividad específica
diagnose_entry	Guía a un agente para investigar el estado y el historial de una entrada
modify_module	Guía a un agente para modificar el esquema de un módulo existente (configurar)

Modos

El servidor expone una superficie enfocada de herramientas/recursos según el modo activo, manteniendo el contexto del agente ligero. Usa switch_mode para cambiarlo, o establece el modo inicial mediante la variable de entorno INISTATE_MCP_MODE (predeterminado: configure).

Modo	Superficie
runtime	Solo operaciones de entrada y actividad: consulta, lectura, envío, archivos, historial. La superficie más ligera para usar módulos existentes.
configure	Todo lo de runtime más las herramientas, recursos y prompts de diseño de módulos (marcados (configurar) arriba).
frontend	Todo lo de configure más el recurso inistate://frontend-guide para construir interfaces de usuario escritas a mano contra la API REST.

Las herramientas y recursos marcados (configurar) / (frontend) están ausentes de la lista de herramientas en modos más restringidos: cambia de modo para revelarlos.

Flujo de trabajo típico

1. list_workspaces → set_workspace — selecciona un espacio de trabajo (se selecciona automáticamente cuando coincide exactamente uno; ambos devuelven la lista de módulos del espacio de trabajo, por lo que list_modules solo se necesita para actualizar)
2. get_module_schema — comprende los campos, estados y actividades de un módulo
3. get_form — descubre los campos obligatorios antes del primer envío por (módulo, actividad); reutiliza su esquema para entradas posteriores
4. submit_activity — crea o actualiza entradas (submit_activities para operaciones masivas)
5. list_entries — consulta y navega por los datos (usa el parámetro fields para mantener los payloads pequeños)
6. get_entry_history — revisa el historial de entradas

Desarrollo

npm run watch          # Watch mode for TypeScript compilation
npm run inspector      # Test with MCP Inspector

Configuración de MCP

1. Configuración

curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/

o

$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }; Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz"; tar xf mcp-publisher.tar.gz mcp-publisher.exe; rm mcp-publisher.tar.gz

2. Verificación

mcp-publisher --help

3. Autenticación

mcp-publisher login github

4. Publicación: consulta a continuación

Empaquetado y versionado

# Example adding new feature
git checkout -b feat/add-user-tool


# After coding
npx changeset

# Choose:
# 
# minor
# Added new user search tool

# Release — see it first, then do it
npm run release:dry   # runs every check, publishes nothing
npm run release

# `npm run release` does, in this order:
#   refuse to start from a dirty working tree, or with no changesets to release
#   npm ci (exactly the lockfile) -> build -> test
#   changeset version: bump + changelog + sync server.json, then check the two agree
#   git commit + tag v<version>
#   npm publish                      <- the first irreversible step
#   confirm npm really serves that version
#   mcp-publisher validate / login / publish
#   git push --follow-tags
#
# The npm-before-registry order is the point, not a preference: server.json names an npm package AND
# version, so a registry entry published first tells every client to install something that 404s.
# The registry step refuses to run until `npm view` confirms the version is live.
#
# npm run release:npm   publishes to npm and stops (no registry)

PM2 (Ubuntu/AWS)

Ejecuta el transporte HTTP en producción usando PM2:

npm install
npm run build
npm run pm2:start
npx pm2 save

Habilita el inicio al reiniciar:

sudo npx pm2 startup systemd -u ubuntu --hp /home/ubuntu
npx pm2 save

Operaciones comunes:

npm run pm2:restart
npm run pm2:logs
npm run pm2:stop

Establece las variables de entorno requeridas (INISTATE_API_TOKEN, y opcionalmente INISTATE_API_BASE, INISTATE_WORKSPACE_ID, OAUTH_ISSUER_URL, INISTATE_APP_URL) en tu shell, en el ecosistema PM2 env o en el administrador de secretos de implementación antes de iniciar.

Pruebas

Ejecutar todas las pruebas

npm test

Modo de observación (se vuelve a ejecutar al cambiar archivos)

npm run test:watch

Estructura de pruebas

Las pruebas están en src/ junto a los archivos fuente y usan Vitest:

Archivo	Tipo	Qué cubre
src/schema.test.ts	Pruebas unitarias (76)	designWorkflow, validateDesign (incluida la paridad de plataforma y la normalización de entradas), funciones auxiliares (isValidFieldType, isValidColor, isValidActor, suggestColorForState)
src/activity-guard.test.ts	Pruebas unitarias (42)	Reglas de protección de submit_activity: actor humano/híbrido, confirmación de cambio de estado, inflado de confianza, validación de forma de referencia
src/tools.schema.test.ts	Pruebas unitarias (19)	Formas de esquema de entrada de herramientas y validación
src/backend-capabilities.test.ts	Pruebas unitarias (9)	Control de capacidades: las herramientas que el backend activo no puede servir devuelven un mensaje de capacidad
src/flagged-annotation.test.ts	Pruebas de integración (5)	Anotación de respuestas marcadas: las transiciones suprimidas se explican (flag_reason + agent_action) para que los agentes dejen de reintentar con mayor confianza
src/server.test.ts	Pruebas de integración (17)	Inicia el servidor MCP como proceso hijo y lo ejercita mediante el cliente oficial del SDK de MCP: descubrimiento de herramientas/recursos/prompts limitado por modo, switch_mode, lecturas de recursos, recuperación de prompts y llamadas a herramientas locales

Las pruebas unitarias cubren:

• Validación de tipos de campo y colores contra el esquema
• Lógica de sugerencia de color de estado
• Validación de diseño: nombres duplicados, tipos/colores/actores inválidos, reglas de estado inicial, integridad de flujo, estados inalcanzables, actividades no utilizadas, advertencias de confianza de IA
• Normalización de entradas: alias de tipo de campo, color de estado e industria; análisis de estados a partir de una descripción
• Diseño de flujos de trabajo: detección de patrones (aprobación, ticket, pipeline, lista de registros), valores predeterminados por industria

Las pruebas de integración verifican (no se necesita token de API):

• Descubrimiento de herramientas/recursos/prompts limitado por modo: el modo runtime oculta la superficie de configuración, switch_mode la revela y la colapsa
• design_workflow, validate_design funcionan de extremo a extremo mediante el protocolo MCP
• Los recursos estáticos (inistate://schema/runtime, inistate://design-guide) devuelven contenido válido
• Los 4 prompts devuelven mensajes con plantillas correctas

Pruebas interactivas con MCP Inspector

INISTATE_API_TOKEN=your-token npm run inspector

Abre una interfaz de navegador donde puedes llamar herramientas de forma interactiva, inspeccionar esquemas y ver respuestas.