{
  "markdown": "# Inistate MCP Server\n\nMCP server for the [Inistate](https://inistate.com) platform — module discovery, entry management, and activity submission.\n\n## Setup\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `INISTATE_API_TOKEN` | Yes | — | Bearer token for Inistate API authentication |\n| `INISTATE_API_BASE` | No | `https://api.inistate.com` | API base URL |\n| `INISTATE_MCP_MODE` | No | `configure` | Initial mode: `runtime`, `configure`, or `frontend` (see [Modes](#modes)) |\n| `INISTATE_MCP_NO_SETUP` | No | — | Set to `1` to force server mode from a terminal (skip the interactive wizard) |\n| `INISTATE_DEBUG_FILE` | No | — | Set to `1` to log write-path tool calls to `./debug.log`, or to a path to log there. Off by default; logs identifiers only, never field values |\n\n### Install from npm (recommended)\n\nNo clone or build needed — `npx` will fetch and run the published package on demand:\n\n```bash\nnpx -y inistate-mcp\n```\n\nOr install globally:\n\n```bash\nnpm install -g inistate-mcp\ninistate-mcp\n```\n\n### Interactive setup (recommended)\n\nRun 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:\n\n```bash\nnpx -y inistate-mcp\n# or, explicitly:\nnpx -y inistate-mcp setup\n```\n\nSupported 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.\n\nThe 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.\n\n### Claude Desktop Configuration\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"inistate\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"inistate-mcp\"],\n      \"env\": {\n        \"INISTATE_API_TOKEN\": \"your-token-here\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code Configuration\n\n```bash\nclaude mcp add inistate -e INISTATE_API_TOKEN=your-token-here -- npx -y inistate-mcp\n```\n\n### Install from source\n\n```bash\ngit clone https://github.com/Inistate/inistate-mcp.git\ncd inistate-mcp\nnpm install\nnpm run build\n```\n\nThen point your MCP client at `node /absolute/path/to/inistate-mcp/build/index.js`.\n\n## Tools\n\nTools marked **(configure)** are only exposed in configure mode — see [Modes](#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.\n\n| Tool | Description |\n|------|-------------|\n| `list_workspaces` | List workspaces the user has access to |\n| `set_workspace` | Set the active workspace |\n| `list_modules` | List all discoverable modules in the workspace |\n| `get_module_schema` | Get the canvas schema (basic or extended tier) — available in every mode |\n| `get_module_canvas` | Get full module definition with stable IDs (round-trippable) **(configure)** |\n| `list_entries` | Query entries with filters, sorting, and pagination |\n| `get_entry` | Read a single entry by ID |\n| `get_form` | Get form fields and defaults for an activity |\n| `submit_activity` | Create, edit, delete, or run custom activities |\n| `submit_activities` | Bulk variant — same activity applied to up to 100 entries in one call |\n| `get_entry_history` | Get entry audit trail and comments |\n| `request_upload_url` | Default upload path — get a presigned S3 URL to PUT file bytes to |\n| `confirm_upload` | Confirm a presigned upload completed; returns the File/Image field path |\n| `upload_file` | Fallback upload via base64/multipart (use only if the presigned flow fails) |\n| `download_file` | Download a file (returns pre-signed URL) |\n| `design_workflow` | Generate a scaffolded module template from a description **(configure)** |\n| `validate_design` | Validate a module schema before creating or updating **(configure)** |\n| `create_module` | Create a new module with schema **(configure)** |\n| `update_module` | Update an existing module's schema **(configure)** |\n| `scaffold_module` | Draft a module schema from existing data (SQLite, Notion, or Airtable table) **(configure)** — served by the local runtime (inistate-core); on the hosted Platform backend it returns a capability message pointing to `design_workflow` |\n| `switch_mode` | Switch the active mode (runtime / configure / frontend) |\n\n## Resources\n\n| URI | Description |\n|-----|-------------|\n| `inistate://modules` | List all modules |\n| `inistate://modules/{name}/canvas` | Basic module schema (fields + states) |\n| `inistate://modules/{name}/canvas/extended` | Extended schema with activities and flows |\n| `inistate://guardrails` | Server-enforced `submit_activity` rules (read once per session) |\n| `inistate://schema/runtime` | Runtime schema — entry/activity/file types and filter operators (default) |\n| `inistate://schema/configure` | Module-design schema — write format, field types, colors **(configure)** |\n| `inistate://design-guide` | FACTS Module Design Guide **(configure)** |\n| `inistate://frontend-guide` | REST API reference for hand-written UIs **(frontend)** |\n\n## Prompts\n\n| Prompt | Description |\n|--------|-------------|\n| `design_factsops_workflow` | Guide an agent through designing a complete workflow module **(configure)** |\n| `execute_activity` | Guide an agent through executing a specific activity |\n| `diagnose_entry` | Guide an agent through investigating an entry's state and history |\n| `modify_module` | Guide an agent through modifying an existing module's schema **(configure)** |\n\n## Modes\n\nThe 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`).\n\n| Mode | Surface |\n|------|---------|\n| `runtime` | Entry and activity operations only — querying, reading, submitting, files, history. The leanest surface for using existing modules. |\n| `configure` | Everything in `runtime` plus the module-design tools, resources, and prompts (marked **(configure)** above). |\n| `frontend` | Everything in `configure` plus the `inistate://frontend-guide` resource for building hand-written UIs against the REST API. |\n\nTools and resources marked **(configure)** / **(frontend)** are absent from the tool list in narrower modes — switch modes to reveal them.\n\n## Typical Workflow\n\n1. `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)\n2. `get_module_schema` — understand a module's fields, states, and activities\n3. `get_form` — discover required fields before the first submission per (module, activity); reuse its schema for further entries\n4. `submit_activity` — create or update entries (`submit_activities` for bulk)\n5. `list_entries` — query and browse data (use the `fields` parameter to keep payloads small)\n6. `get_entry_history` — review entry history\n\n## Development\n\n```bash\nnpm run watch          # Watch mode for TypeScript compilation\nnpm run inspector      # Test with MCP Inspector\n```\n\n### MCP Setup\n1. Setup\n```bash\ncurl -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/\n```\n\nor\n\n```powershell\n$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\n\n```\n\n2. Verify\n```\nmcp-publisher --help\n```\n\n3. Authenticate\n```\nmcp-publisher login github\n```\n\n4. Publish: see below\n\n### Packaging & Versioning\n```bash\n# Example adding new feature\ngit checkout -b feat/add-user-tool\n\n\n# After coding\nnpx changeset\n\n# Choose:\n# \n# minor\n# Added new user search tool\n\n# Release\nnpm run release\n\n# This does:\n# install dependencies\n# test\n# bump version + update changelog + sync server.json\n# validate MCP server config\n# build (via npm prepare hook)\n# publish to npm\n# publish to MCP registry\n```\n\n## PM2 (Ubuntu/AWS)\n\nRun the HTTP transport in production using PM2:\n\n```bash\nnpm install\nnpm run build\nnpm run pm2:start\nnpx pm2 save\n```\n\nEnable startup on reboot:\n\n```bash\nsudo npx pm2 startup systemd -u ubuntu --hp /home/ubuntu\nnpx pm2 save\n```\n\nCommon operations:\n\n```bash\nnpm run pm2:restart\nnpm run pm2:logs\nnpm run pm2:stop\n```\n\nSet 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.\n\n## Testing\n\n### Run all tests\n\n```bash\nnpm test\n```\n\n### Watch mode (re-runs on file changes)\n\n```bash\nnpm run test:watch\n```\n\n### Test structure\n\nTests are in `src/` alongside the source files and use [Vitest](https://vitest.dev/):\n\n| File | Type | What it covers |\n|------|------|----------------|\n| `src/schema.test.ts` | Unit tests (76) | `designWorkflow`, `validateDesign` (including platform parity and input normalization), helper functions (`isValidFieldType`, `isValidColor`, `isValidActor`, `suggestColorForState`) |\n| `src/activity-guard.test.ts` | Unit tests (42) | `submit_activity` guard rules — human/hybrid actor, state-change confirmation, confidence-inflation, reference-shape validation |\n| `src/tools.schema.test.ts` | Unit tests (19) | Tool input-schema shapes and validation |\n| `src/backend-capabilities.test.ts` | Unit tests (9) | Capability gating — tools the active backend cannot serve return a capability message |\n| `src/flagged-annotation.test.ts` | Integration tests (5) | Flagged-response annotation — suppressed transitions are explained (`flag_reason` + `agent_action`) so agents stop retrying with higher confidence |\n| `src/server.test.ts` | Integration tests (17) | Spins up the MCP server as a child process and exercises it through the official MCP SDK client — mode-gated tool/resource/prompt discovery, `switch_mode`, resource reads, prompt retrieval, and local tool calls |\n\nUnit tests cover:\n- Field type and color validation against the schema\n- State color suggestion logic\n- Design validation: duplicate names, invalid types/colors/actors, initial state rules, flow integrity, unreachable states, unused activities, AI confidence warnings\n- Input normalization: field-type, state-color, and industry aliases; parsing states from a description\n- Workflow design: pattern detection (approval, ticket, pipeline, record list), industry defaults\n\nIntegration tests verify (no API token needed):\n- Mode-gated tool/resource/prompt discovery — runtime mode hides the configure surface, `switch_mode` reveals and collapses it\n- `design_workflow`, `validate_design` work end-to-end through the MCP protocol\n- Static resources (`inistate://schema/runtime`, `inistate://design-guide`) return valid content\n- All 4 prompts return correctly templated messages\n\n### Interactive testing with MCP Inspector\n\n```bash\nINISTATE_API_TOKEN=your-token npm run inspector\n```\n\nOpens a browser UI where you can interactively call tools, inspect schemas, and see responses.\n",
  "bytes": 11724,
  "sha": "c0e4c230a2462583a3947bb58e45f7fb6e7be17220313e77f0a2a36b97948a16",
  "repo_slug": "inistate/inistate-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_inistate_inistate_mcp_a878c954/readme"
}