Agent-System/scripts/mcp/README.md

MCP servers (stdio)

Zero-dependency Node MCP wrappers used by Cursor (see .cursor/mcp.json).

Server	Script	Purpose
agentctl	agentctl-mcp.mjs	Lease / docs apply / validate / queue
jev	jev-mcp.mjs	Typed decide/health against local or remote jev-service
pi-subagents	pi-subagents-mcp.mjs	Local PI subagent roles/run/result (engineering tool; not product Runner)

# from repo root
node scripts/mcp/agentctl-mcp.mjs
node scripts/mcp/jev-mcp.mjs
node scripts/mcp/pi-subagents-mcp.mjs

pi-subagents

Markdown model config is the sole editable source: .doc/ops/2026-09-24-subagent-model-config.md.

Tool	Behavior
pi_subagent_roles	Read-only catalog; never invokes PI; executor binary from this server's INSTALL_ROOT
pi_subagent_run	Non-blocking; request JSON in OS tmp; wraps discovered main worktree scripts/agentctl.py with (governance SSOT lease entry) + INSTALL_ROOT scripts/pi_subagents.py run
pi_subagent_result	Read-only receipt; running is not isError; terminal failure/UNKNOWN_REQUEST after a settled supervisor rejection surfaces the child's typed error (ROLE_DISABLED, LEASE_REQUIRED, …)

Install vs main: When the MCP server lives in a linked task worktree, INSTALL_ROOT may differ from the repo main tip. Cross-repo worktrees (different git-common-dir) are refused. Optional config is worktree-relative registered model config only. request.config_path is rejected (use tool config).

CLI:

python3 -B scripts/pi_subagents.py roles --config .doc/ops/2026-09-24-subagent-model-config.md
python3 -B scripts/agentctl.py with --task <id> \
  --resource path:.doc/test-reports/assets/pi-subagents/<id>/<request_id> -- \
  python3 -B scripts/pi_subagents.py run --request /path/to/req.json \
  --config .doc/ops/2026-09-24-subagent-model-config.md
python3 -B scripts/pi_subagents.py result --task <id> --request-id <request_id>

The executor resolves agentctl helpers from the git main worktree scripts directory (not a stale colocated copy beside itself when running from a feature worktree).

Scoped reads: scripts/pi-subagent-readonly.ts — builtin path only; @/~ denied; directory walks must contain only allowlisted regular files. Approved tests use a separate snapshot; model evidence stays pristine.

Cursor CLI compatibility (pi-subagents)

Real Cursor CLI 2026.09.18 (and 2026.09.23 verified here) does not expand ${workspaceFolder} in MCP args. The pi-subagents entry therefore uses workspace-relative args: ["scripts/mcp/pi-subagents-mcp.mjs"] with type: "stdio" / command: "node". Absolute ${workspaceFolder}/… paths fail with Cannot find module '…/${workspaceFolder}/scripts/mcp/pi-subagents-mcp.mjs'. After agent mcp enable pi-subagents, agent mcp list-tools pi-subagents must report exactly three tools: pi_subagent_roles, pi_subagent_run, pi_subagent_result. Older agentctl / jev entries may still use ${workspaceFolder} until separately corrected.

Limitations (v1)

• No shared environment ops (SHARED_ENV_UNSUPPORTED).
• Process-group governance, not an OS sandbox.
• Unit suite uses fake PI; Cursor UI MCP connectivity requires reload after checkout and host smoke.
• Host owns live paid-model checks.

jev credentials (not in git)

• ~/.secrets/jev/api.key (chmod 600) or env JEV_API_KEY
• ~/.secrets/jev/base-url or env JEV_BASE_URL (default http://127.0.0.1:8767)

Reload MCP after checkout. See skill .cursor/skills/jev-decide/SKILL.md.

lease_run / validate take command as an argv array (no shell). Set AGENTCTL_REPO only when the agentctl script is not under the repo tree.