Ink Dev MCP

Local stdio-only MCP server for inspecting, exercising and debugging React/Ink terminal applications.

Install

Requires Node.js 24.11+ and a native build toolchain for node-pty (Python, make, C/C++ compiler).

npm install
npm run build

Configure your MCP client to spawn the server over stdio:

{
  "mcpServers": {
    "ink-dev": {
      "command": "node",
      "args": ["/absolute/path/to/ink-mcp/dist/index.js"],
      "env": {
        "INK_MCP_WORKSPACE_ROOT": "/absolute/path/to/workspace",
        "INK_MCP_ALLOW_EXECUTION": "1"
      }
    }
  }
}

This is not an HTTP service. It does not listen on a port and must not print diagnostics to stdout.

Related MCP server: ptywright

MCP tools

Example development loop

1. Call ink_project_inspect with projectRoot ".".

2. Call ink_run_start with projectRoot ".", executable "node" and args ["dist/cli.js"].

3. Use ink_run_wait with condition "text_present" and the expected prompt.

4. Send keys with ink_run_keys (for example ["ArrowDown", "Enter"]).

5. Inspect the current screen with ink_run_screen, and verify the expected result.

6. Stop the process with ink_run_stop.

Run handles persist across MCP calls until explicitly stopped or until the server disconnects. The screen snapshot is the current terminal viewport, not raw output with ANSI stripped.

Local execution safety

PTY code execution is disabled by default. Set INK_MCP_ALLOW_EXECUTION=1 to enable it. INK_MCP_WORKSPACE_ROOT defaults to the server working directory and restricts project paths. The server bounds simultaneous processes, history, terminal dimensions, user input and waits.

Local code execution is not sandboxed. A trusted project's executable has the user's permissions. Do not use this server to execute untrusted projects. Do not expose the stdio process through a network bridge without separately designing isolation and authentication.

ESM and CommonJS

The published @xterm/headless package has a CommonJS entry point that may fail when imported with ESM named exports on Node 24. The runtime uses createRequire(import.meta.url) to load it and node-pty, and Vite leaves both dependencies external.

Development

npm run lint
npm run format:check
npm run build
npm run test:ci
npm run test:smoke
npm run verify:skill-package

The smoke test launches the compiled dist/index.js over MCP stdio and checks tool discovery. This protects against type-check-passing but runtime-failing ESM import regressions.

Use MCP Inspector to exercise the server:

npx @modelcontextprotocol/inspector node ./dist/index.js

Documentation guidance is bundled and indicative. Verify API details against the exact Ink version installed in the target project.

Repo structure

• src/index.ts — stdio entry point

• src/tools.ts — MCP tool registration and validated schemas

• src/runtime/registry.ts — PTY lifecycle and headless terminal screen

• src/runtime/project.ts — project analysis and curated documentation

• src/skills.ts and skills/ — agent skill publishing

• scripts/smoke-stdio.mts — compiled entry-point integration test