Inistate

Colegas de IA com trilhas de auditoria

Documentação

Servidor MCP Inistate

Servidor MCP para a plataforma Inistate — descoberta de módulos, gerenciamento de entradas e envio de atividades.

Configuração

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
`INISTATE_API_TOKEN`	Sim	—	Token Bearer para autenticação na API do Inistate
`INISTATE_API_BASE`	Não	`https://api.inistate.com`	URL base da API
`INISTATE_MCP_MODE`	Não	`configure`	Modo inicial: `runtime`, `configure` ou `frontend` (veja Modos)
`INISTATE_MCP_NO_SETUP`	Não	—	Defina como `1` para forçar o modo servidor a partir de um terminal (pule o assistente interativo)
`INISTATE_DEBUG_FILE`	Não	—	Defina como `1` para registrar chamadas de ferramentas do caminho de escrita em `./debug.log`, ou para um caminho para registrar lá. Desativado por padrão; registra apenas identificadores, nunca valores de campos

Instalar via npm (recomendado)

Não é necessário clonar ou compilar — npx buscará e executará o pacote publicado sob demanda:

npx -y inistate-mcp

Ou instale globalmente:

npm install -g inistate-mcp
inistate-mcp

Configuração interativa (recomendada)

Execute o binário em um terminal sem cliente MCP anexado e ele o guiará pela inserção do seu token de API e escolherá o arquivo de configuração correto para o seu cliente:

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

Clientes suportados: Claude Desktop, Claude Code (global ou .mcp.json local do projeto), Cursor, Windsurf, Codex CLI, VS Code (perfil de usuário ou .vscode/mcp.json do workspace), Cline, Gemini CLI (global ou workspace). Escolha "Apenas imprimir configuração" para obter um bloco JSON para colar em qualquer outro lugar.

O assistente só é executado quando stdin é um TTY (ou seja, você o iniciou manualmente). Quando um cliente MCP inicia o binário via stdio canalizado, ele pula o assistente e executa como um servidor MCP normal — defina INISTATE_MCP_NO_SETUP=1 se precisar forçar o modo servidor a partir de um terminal.

Configuração do Claude Desktop

Adicione ao seu claude_desktop_config.json:

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

Configuração do Claude Code

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

Instalar a partir da fonte

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

Em seguida, aponte seu cliente MCP para node /absolute/path/to/inistate-mcp/build/index.js.

Ferramentas

Ferramentas marcadas como (configurar) são expostas apenas no modo de configuração — veja Modos. Ferramentas que o backend ativo não pode atender (por exemplo, scaffold_module na Plataforma hospedada) permanecem registradas, mas retornam uma mensagem de capacidade estruturada em vez de falhar silenciosamente.

Ferramenta	Descrição
`list_workspaces`	Listar workspaces aos quais o usuário tem acesso
`set_workspace`	Definir o workspace ativo
`list_modules`	Listar todos os módulos descobríveis no workspace
`get_module_schema`	Obter o esquema do canvas (nível básico ou estendido) — disponível em todos os modos
`get_module_canvas`	Obter definição completa do módulo com IDs estáveis (compatível com ida e volta) (configurar)
`list_entries`	Consultar entradas com filtros, ordenação e paginação
`get_entry`	Ler uma única entrada por ID
`get_form`	Obter campos de formulário e padrões para uma atividade
`submit_activity`	Criar, editar, excluir ou executar atividades personalizadas
`submit_activities`	Variante em lote — mesma atividade aplicada a até 100 entradas em uma única chamada
`get_entry_history`	Obter trilha de auditoria e comentários da entrada
`request_upload_url`	Caminho de upload padrão — obter uma URL S3 pré-assinada para enviar bytes de arquivo
`confirm_upload`	Confirmar que um upload pré-assinado foi concluído; retorna o caminho do campo Arquivo/Imagem
`upload_file`	Upload alternativo via base64/multipart (use apenas se o fluxo pré-assinado falhar)
`download_file`	Baixar um arquivo (retorna URL pré-assinada)
`design_workflow`	Gerar um modelo de módulo estruturado a partir de uma descrição (configurar)
`validate_design`	Validar um esquema de módulo antes de criar ou atualizar (configurar)
`create_module`	Criar um novo módulo com esquema (configurar)
`update_module`	Atualizar o esquema de um módulo existente (configurar)
`scaffold_module`	Elaborar um esquema de módulo a partir de dados existentes (tabela SQLite, Notion ou Airtable) (configurar) — servido pelo runtime local (inistate-core); no backend da Plataforma hospedada, retorna uma mensagem de capacidade apontando para `design_workflow`
`switch_mode`	Alternar o modo ativo (runtime / configurar / frontend)

Recursos

URI	Descrição
`inistate://modules`	Listar todos os módulos
`inistate://modules/{name}/canvas`	Esquema básico do módulo (campos + estados)
`inistate://modules/{name}/canvas/extended`	Esquema estendido com atividades e fluxos
`inistate://guardrails`	Regras de `submit_activity` impostas pelo servidor (lidas uma vez por sessão)
`inistate://schema/runtime`	Esquema de runtime — tipos de entrada/atividade/arquivo e operadores de filtro (padrão)
`inistate://schema/configure`	Esquema de design de módulo — formato de escrita, tipos de campo, cores (configurar)
`inistate://design-guide`	Guia de Design de Módulo FACTS (configurar)
`inistate://frontend-guide`	Referência da API REST para UIs escritas manualmente (frontend)

Prompts

Prompt	Descrição
`design_factsops_workflow`	Guiar um agente no design de um módulo de fluxo de trabalho completo (configurar)
`execute_activity`	Guiar um agente na execução de uma atividade específica
`diagnose_entry`	Guiar um agente na investigação do estado e histórico de uma entrada
`modify_module`	Guiar um agente na modificação do esquema de um módulo existente (configurar)

Modos

O servidor expõe uma superfície focada de ferramentas/recursos dependendo do modo ativo, mantendo o contexto do agente enxuto. Use switch_mode para alterá-lo, ou defina o modo inicial via variável de ambiente INISTATE_MCP_MODE (padrão: configure).

Modo	Superfície
`runtime`	Apenas operações de entrada e atividade — consulta, leitura, envio, arquivos, histórico. A superfície mais enxuta para usar módulos existentes.
`configure`	Tudo em `runtime` mais as ferramentas, recursos e prompts de design de módulo (marcados como (configurar) acima).
`frontend`	Tudo em `configure` mais o recurso `inistate://frontend-guide` para construir UIs escritas manualmente contra a API REST.

Ferramentas e recursos marcados como (configurar) / (frontend) estão ausentes da lista de ferramentas em modos mais restritos — alterne os modos para revelá-los.

Fluxo de Trabalho Típico

list_workspaces → set_workspace — selecione um workspace (selecionado automaticamente quando exatamente um corresponde; ambos retornam a lista de módulos do workspace, então list_modules só é necessário para atualizar)
get_module_schema — entenda os campos, estados e atividades de um módulo
get_form — descubra campos obrigatórios antes do primeiro envio por (módulo, atividade); reutilize seu esquema para entradas adicionais
submit_activity — crie ou atualize entradas (submit_activities para lote)
list_entries — consulte e navegue pelos dados (use o parâmetro fields para manter os payloads pequenos)
get_entry_history — revise o histórico de entradas

Desenvolvimento

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

Configuração MCP

Configuração

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/

$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

Verificar

mcp-publisher --help

Autenticar

mcp-publisher login github

Publicar: veja abaixo

Empacotamento e Versionamento

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

Execute o transporte HTTP em produção usando PM2:

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

Habilite a inicialização na reinicialização:

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

Operações comuns:

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

Defina as variáveis de ambiente necessárias (INISTATE_API_TOKEN, e opcionalmente INISTATE_API_BASE, INISTATE_WORKSPACE_ID, OAUTH_ISSUER_URL, INISTATE_APP_URL) no seu shell, no ecossistema PM2 env ou no gerenciador de segredos de implantação antes de iniciar.

Testes

Executar todos os testes

npm test

Modo de observação (executa novamente em alterações de arquivo)

npm run test:watch

Estrutura de testes

Os testes estão em src/ junto com os arquivos de origem e usam Vitest:

Arquivo	Tipo	O que cobre
`src/schema.test.ts`	Testes unitários (76)	`designWorkflow`, `validateDesign` (incluindo paridade de plataforma e normalização de entrada), funções auxiliares (`isValidFieldType`, `isValidColor`, `isValidActor`, `suggestColorForState`)
`src/activity-guard.test.ts`	Testes unitários (42)	Regras de proteção `submit_activity` — ator humano/híbrido, confirmação de mudança de estado, inflação de confiança, validação de forma de referência
`src/tools.schema.test.ts`	Testes unitários (19)	Formas de esquema de entrada de ferramentas e validação
`src/backend-capabilities.test.ts`	Testes unitários (9)	Controle de capacidade — ferramentas que o backend ativo não pode atender retornam uma mensagem de capacidade
`src/flagged-annotation.test.ts`	Testes de integração (5)	Anotação de resposta sinalizada — transições suprimidas são explicadas (`flag_reason` + `agent_action`) para que os agentes parem de tentar novamente com maior confiança
`src/server.test.ts`	Testes de integração (17)	Inicia o servidor MCP como um processo filho e o exercita através do SDK oficial do cliente MCP — descoberta de ferramentas/recursos/prompts limitada por modo, `switch_mode`, leituras de recursos, recuperação de prompts e chamadas locais de ferramentas

Testes unitários cobrem:

Validação de tipo de campo e cor contra o esquema
Lógica de sugestão de cor de estado
Validação de design: nomes duplicados, tipos/cores/atores inválidos, regras de estado inicial, integridade de fluxo, estados inalcançáveis, atividades não utilizadas, avisos de confiança de IA
Normalização de entrada: aliases de tipo de campo, cor de estado e indústria; análise de estados a partir de uma descrição
Design de fluxo de trabalho: detecção de padrões (aprovação, ticket, pipeline, lista de registros), padrões de indústria

Testes de integração verificam (nenhum token de API necessário):

Descoberta de ferramentas/recursos/prompts limitada por modo — o modo runtime oculta a superfície de configuração, switch_mode revela e a recolhe
design_workflow, validate_design funcionam de ponta a ponta através do protocolo MCP
Recursos estáticos (inistate://schema/runtime, inistate://design-guide) retornam conteúdo válido
Todos os 4 prompts retornam mensagens modeladas corretamente

Testes interativos com o MCP Inspector

INISTATE_API_TOKEN=your-token npm run inspector

Abre uma interface de navegador onde você pode chamar ferramentas interativamente, inspecionar esquemas e ver respostas.