@loft-902-co/subagents-mcp

v1.4.4

Published

7 months ago

TypeScript MCP server exposing a single delegate tool to run task-specific sub-agents (review, debugger, security) via explicit CLI wrappers.

0High
0Medium
0Low

jmloft

mcp mcp-server model-context-protocol codex codex-cli subagents sub-agents anthropic claude tools

subagents-mcp — Model Context Protocol server for task-specific sub‑agents

Minimal TypeScript MCP server that exposes a focused tool surface to run task‑specific sub‑agents (review, debugger, security, etc.) via explicit CLI wrappers (Codex or Cursor). Agent personas are loaded from simple files in an agents/ directory (Markdown or JSON), so you can add or tweak sub‑agents without changing code.

Features

Minimal, auditable MCP server implemented in TypeScript (stdout is JSON only)
Single responsibility tool surface: delegate, delegate_batch, list_agents, validate_agents
Zero-code agent authoring: drop agents/*.md|json to register personas and metadata
Profile-aware execution: calls into Codex or Cursor with the agent’s selected profile
Optional workspace isolation: mirror repo or use a git worktree for larger codebases
Orchestrated execution with token gating and per-request state under orchestration/<request_id>/
Works with Node ≥ 18

Quickstart

Run via npx (no local build required)

npx -y @loft-902-co/subagents-mcp --version

Alternatively: build locally:

npm install
npm run build

Point your client (Codex or Cursor) at the MCP server (explicit wrapper required)

Codex CLI wiring

Add this to your ~/.codex/config.toml and adjust as needed:

[mcp_servers.subagents]
command = "npx"
args    = ["-y", "@loft-902-co/subagents-mcp", "--agents-dir", "/ABS/PATH/TO/agents"]

[profiles.review]
model = "gpt-5"
approval_policy = "on-request"
sandbox_mode    = "read-only"

[profiles.debugger]
model = "o3"
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

[profiles.security]
model = "gpt-5"
approval_policy = "never"
sandbox_mode    = "workspace-write"

Verify the connection by launching Codex and running /mcp.

Cursor CLI wiring

[mcp_servers.subagents]
command = "npx"
args    = ["-y", "@loft-902-co/subagents-mcp", "--client", "cursor", "--agents-dir", "/ABS/PATH/TO/agents"]

Selection is explicit; there is no default client. Use the Codex or Cursor wrapper.

Usage

Built-in tools

These MCP tools are exposed:

delegate(args): run a single sub‑agent
delegate_batch({ items, token? }): run multiple sub‑agents in parallel
list_agents(): list built‑in and disk‑loaded agents
validate_agents({ dir? }): validate agent registry files
start_orchestration({ goal?, cwd?, mirror_repo? }): boot the orchestrator and run *help or *plan {goal}

Minimal examples (from a client that can call MCP tools):

{ "name": "list_agents" }

{
  "name": "delegate",
  "arguments": { "agent": "review", "task": "Review the last commit for readability" }
}

To keep the main context clean in your workflow, prefer calling these tools directly instead of lengthy in‑thread analysis when a sub‑agent fits the task. If your project maintains an AGENTS.md, add suggested call patterns there.

Custom agents registry

The server loads agent definitions from disk and merges them with a few built‑ins. You can point to a registry directory via a CLI arg or env var, or rely on auto‑discovery.

Preferred: --agents-dir /abs/path/to/agents or set SUBAGENTS_AGENTS_DIR=/abs/path/to/agents
Auto‑discovery candidates (in order): ./agents, ./.<client-id>-subagents/agents (e.g., ./.codex-subagents/agents), and the repo’s bundled dist/../agents

Markdown agent (agents/<name>.md):

---
profile: debugger
approval_policy: on-request   # never | on-request | on-failure | untrusted
sandbox_mode: workspace-write # read-only | workspace-write | danger-full-access
---
You are a pragmatic performance analyst. Identify hotspots, propose minimal, measurable fixes,
and outline validation steps with lightweight metrics.

JSON agent (agents/<name>.json):

{
  "profile": "debugger",
  "persona": "You plan and validate safe DB migrations with rollbacks.",
  "approval_policy": "on-request",
  "sandbox_mode": "workspace-write"
}

Validate and list your registry:

{ "name": "validate_agents" }

{ "name": "list_agents" }

Start orchestration quickly (shows *help by default or plans a goal):

{ "name": "start_orchestration", "arguments": { "goal": "Plan sprint for onboarding flow" } }

Tips:

Keep personas short, specific, and action‑biased (task checklists beat philosophy)
Align approval_policy and sandbox_mode with your client profiles in ~/.codex/config.toml

Orchestration model

All work is routed through an orchestrator agent. Calls like:

{
  "name": "delegate",
  "arguments": { "agent": "security", "task": "Scan for secrets and unsafe shell exec" }
}

are transparently rewritten to the orchestrator with an envelope. The server injects available_agents into the envelope so the orchestrator knows what it can delegate to. Token gating ensures only the orchestrator can delegate further. Each request creates a state folder:

orchestration/<request_id>/
  ├─ todo.json           # request lifecycle, steps, status
  └─ steps/<step-id>/
       ├─ stdout.txt
       └─ stderr.txt

Parallelism: use delegate_batch for independent items; results preserve input ordering.

Isolation: set mirror_repo=true to copy your workspace into the ephemeral workdir, or prefer a git worktree for large repos.

Environment variables

Client selection and arguments (explicit configuration required):

SUBAGENTS_CLIENT — client identifier (no default)
SUBAGENTS_CLIENT_ID — identifier used in paths and defaults
SUBAGENTS_SERVER_NAME — MCP server name in handshake
SUBAGENTS_WORKDIR_PREFIX — prefix for temporary workdirs
SUBAGENTS_CLIENT_ARGS_BEFORE_TASK — JSON array or space‑separated templates overriding CLI args; templates support {profile} and {task}
SUBAGENTS_CLIENT_ARGS_AFTER_TASK — JSON array or space‑separated templates overriding CLI args; templates support {profile} and {task}
SUBAGENTS_CLIENT_CONFIG — JSON object to override multiple fields at once

Registry and behavior:

SUBAGENTS_AGENTS_DIR — absolute path to your agents registry
SUBAGENTS_MIRROR_ALL=1 — include normally skipped paths when mirroring (e.g., .git, .env, node_modules)
DEBUG_MCP=1 — timestamped handshake and tool call debug logs to stderr (stdout remains JSON‑only)

Your client (e.g., Codex CLI) may also require additional env like OPENAI_API_KEY to run real model calls.

Expose planning/tasks as @tasks

Some workflows reference a @tasks/ alias for planning artifacts (e.g., planning/tasks/). You can expose this directory to the client process in two ways:

Option A — Mirror the repo when delegating so the tasks are readable at their native path:
- Pass mirror_repo: true to delegate(...) when you want agents to read planning/tasks/ directly in the temp workdir.
Option B — Mount an alias via client args (recommended if your client supports context/resource flags):
- Use the env passthrough to add client‑specific flags before the task. Example with a hypothetical --context flag:

POSIX shells:

export SUBAGENTS_CLIENT_ARGS_BEFORE_TASK='exec --profile {profile} --context @tasks=/ABS/PATH/TO/planning/tasks'

Windows PowerShell:

$env:SUBAGENTS_CLIENT_ARGS_BEFORE_TASK = 'exec --profile {profile} --context @tasks=C:\ABS\PATH\planning\tasks'

Notes:

The exact flag name depends on your client (e.g., --context, --resource, or similar). The server simply forwards these args.
If your client lacks such a flag, use Option A (mirror_repo=true) and reference planning/tasks/ paths directly.
Bundling: on build, agents/ and planning/ are copied into dist/ (see scripts/copy-static.js) and both are published to npm. Consumers can reference these packaged paths directly.

NPM installs — packaged paths

Local project install (recommended):

# map @tasks to the package-bundled tasks directory
export SUBAGENTS_CLIENT_ARGS_BEFORE_TASK='exec --profile {profile} --context @tasks=./node_modules/@loft-902-co/subagents-mcp/dist/planning/tasks'

Global install (POSIX):

export SUBAGENTS_CLIENT_ARGS_BEFORE_TASK="exec --profile {profile} --context @tasks=$(npm root -g)/@loft-902-co/subagents-mcp/dist/planning/tasks"

Windows PowerShell (local install):

$env:SUBAGENTS_CLIENT_ARGS_BEFORE_TASK = 'exec --profile {profile} --context @tasks=.\nnode_modules
a loft-902-co
subagents-mcp
dist
planning
tasks' -replace "\n","\\"

Agents registry (from npm package):

You can also point --agents-dir (or CODEX_SUBAGENTS_DIR) to ./node_modules/@loft-902-co/subagents-mcp/dist/agents if you want to use the packaged example agents.

Operations

Common commands:

Build: npm run build
Start (Codex server): npm run start:codex → node dist/codex/codex-subagents.mcp.js
Start (Cursor server): npm run start:cursor → node dist/cursor/cursor-subagents.mcp.js
Dev (tsx): npm run dev:codex or npm run dev:cursor
Lint: npm run lint
Tests: npm test
End‑to‑End: npm run e2e (requires codex on PATH and configured profiles)

Troubleshooting highlights:

MCP handshake stalls: ensure stdout emits only newline‑delimited JSON; use DEBUG_MCP=1
Unknown tool: confirm you are executing the built JS from dist/
Agents not found: set --agents-dir or SUBAGENTS_AGENTS_DIR, or create ./agents
Timeouts on large repos: prefer git worktree over full mirroring

See docs/OPERATIONS.md for details.

Security

This server runs outside the client sandbox and inherits your user permissions. Keep the tool surface minimal and review agent registries regularly.

Trust boundaries and least‑privilege guidance:

Narrow tool surface: delegate, delegate_batch, list_agents, validate_agents
Align approval_policy/sandbox_mode with client profiles to gate write access and approvals
Prefer read-only for reviewers; use approvals for higher‑risk work
Avoid mirroring secrets; prefer git worktree for sensitive/large repos
Keep stdout clean (JSON‑only); debug to stderr with DEBUG_MCP=1

See docs/SECURITY.md for a fuller risk/mitigation list and auditing pointers.

Development

Language: TypeScript (compiled to CommonJS)
Node: ≥ 18
Dependencies: minimal (runtime: zod)
MCP protocol: 2024-11-05

Scripts:

{
  "build": "tsc -p tsconfig.json",
  "dev": "tsx src/codex/codex-subagents.mcp.ts",
  "dev:cursor": "tsx src/cursor/cursor-subagents.mcp.ts",
  "start": "node dist/codex/codex-subagents.mcp.js",
  "start:cursor": "node dist/cursor/cursor-subagents.mcp.js",
  "lint": "eslint . --ext .ts",
  "test": "vitest run"
}

Project layout (high level):

src/
  codex/
    codex-subagents.mcp.ts   # main MCP server (Codex)
  cursor/                    # Cursor variant wrapper
  orchestration.ts           # token gating + request lifecycle
docs/                        # integration, operations, security, orchestration
agents/                      # example agents registry (load from disk)
dist/                        # compiled outputs for MCP wiring

FAQ

How do I point the server at my agents directory?

Pass --agents-dir /abs/path/to/agents or set SUBAGENTS_AGENTS_DIR=/abs/path/to/agents. If unspecified, the server auto‑detects ./agents, ./.<client-id>-subagents/agents (e.g., ./.codex-subagents/agents), then a bundled fallback.

Can I run multiple steps in parallel?

Yes. Use delegate_batch({ items }). The orchestrator processes independent items concurrently and returns ordered results.

Where can I see logs and lifecycle state?

For each request, see orchestration/<request_id>/todo.json and per‑step stdout.txt/stderr.txt under steps/<step-id>/.

What if I don’t want to copy the whole repo?

Leave mirror_repo as false (default) and prefer git worktree when you need isolation without heavy copies.

Changelog

See CHANGELOG.md for notable changes. Releases follow SemVer.

License

Related docs

Project AGENTS.md — optional repo guide for usage hints (distinct from runtime SUBAGENTS_PERSONA.md)
docs/INTEGRATION.md — client wiring and configuration
docs/OPERATIONS.md — running, logs, environment, troubleshooting
docs/ORCHESTRATION.md — router, token gating, batch, lifecycle
docs/SECURITY.md — risks, mitigations, defaults, auditing

Rules file (orchestrator)

You can run Codex directly with the orchestrator persona as a rules file so it greets and prints the command list (*help) on activation.

POSIX:

npx -y codex exec --profile default --rules ./node_modules/@loft-902-co/subagents-mcp/dist/agents/orchestrator.md "Initialize and show available commands"