Inistate MCP Server

MCP server for the Inistate platform — module discovery, entry management, and activity submission.

Setup

Environment Variables

Install from npm (recommended)

No clone or build needed — npx will fetch and run the published package on demand:

npx -y inistate-mcp

Or install globally:

npm install -g inistate-mcp
inistate-mcp

Interactive setup (recommended)

Run the binary in a terminal with no MCP client attached and it walks you through entering your API token and picks the right config file for your client:

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

Supported clients: Claude Desktop, Claude Code (global or project-local .mcp.json), Cursor, Windsurf, Codex CLI, VS Code (user profile or workspace .vscode/mcp.json), Cline, Gemini CLI (global or workspace). Pick "Print config only" to get a JSON block to paste anywhere else.

The wizard only runs when stdin is a TTY (i.e., you launched it yourself). When an MCP client spawns the binary via piped stdio, it skips the wizard and runs as a normal MCP server — set INISTATE_MCP_NO_SETUP=1 if you need to force server mode from a terminal.

Claude Desktop Configuration

Add to your claude_desktop_config.json:

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

Claude Code Configuration

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

Install from source

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

Then point your MCP client at node /absolute/path/to/inistate-mcp/build/index.js.

Tools

Tools marked (configure) are only exposed in configure mode — see Modes. Tools the active backend cannot serve (e.g. scaffold_module on the hosted Platform) stay registered but return a structured capability message instead of failing silently.

Resources

Prompts

Modes

The server exposes a focused tool/resource surface depending on the active mode, keeping agent context lean. Use switch_mode to change it, or set the initial mode via the INISTATE_MCP_MODE env var (default: configure).

Tools and resources marked (configure) / (frontend) are absent from the tool list in narrower modes — switch modes to reveal them.

Typical Workflow

1. list_workspaces → set_workspace — select a workspace (auto-selected when exactly one matches; both return the workspace's module list, so list_modules is only needed to refresh)
2. get_module_schema — understand a module's fields, states, and activities
3. get_form — discover required fields before the first submission per (module, activity); reuse its schema for further entries
4. submit_activity — create or update entries (submit_activities for bulk)
5. list_entries — query and browse data (use the fields parameter to keep payloads small)
6. get_entry_history — review entry history

Development

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

MCP Setup

1. Setup

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/

or

$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. Verify

mcp-publisher --help

3. Authenticate

mcp-publisher login github

4. Publish: see below

Packaging & Versioning

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

Run the HTTP transport in production using PM2:

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

Enable startup on reboot:

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

Common operations:

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

Set required environment variables (INISTATE_API_TOKEN, and optionally INISTATE_API_BASE, INISTATE_WORKSPACE_ID, OAUTH_ISSUER_URL, INISTATE_APP_URL) in your shell, PM2 ecosystem env, or deployment secret manager before starting.

Testing

Run all tests

npm test

Watch mode (re-runs on file changes)

npm run test:watch

Test structure

Tests are in src/ alongside the source files and use Vitest:

Unit tests cover:

• Field type and color validation against the schema
• State color suggestion logic
• Design validation: duplicate names, invalid types/colors/actors, initial state rules, flow integrity, unreachable states, unused activities, AI confidence warnings
• Input normalization: field-type, state-color, and industry aliases; parsing states from a description
• Workflow design: pattern detection (approval, ticket, pipeline, record list), industry defaults

Integration tests verify (no API token needed):

• Mode-gated tool/resource/prompt discovery — runtime mode hides the configure surface, switch_mode reveals and collapses it
• design_workflow, validate_design work end-to-end through the MCP protocol
• Static resources (inistate://schema/runtime, inistate://design-guide) return valid content
• All 4 prompts return correctly templated messages

Interactive testing with MCP Inspector

INISTATE_API_TOKEN=your-token npm run inspector

Opens a browser UI where you can interactively call tools, inspect schemas, and see responses.