Qe

Standalone MCP server for QE Framework expert-library guidance.

This repository holds the large optional expert corpus outside @inho-team/qe-framework so framework installs stay small. The server exposes compact search and recommendation by default, then returns full expert content only after an explicit MCP tool or prompt call.

Migrating 0.3 → 0.4

0.4.0 exposes qe_run_openai_compat_agent as an experiment-only, env-gated standalone runner for OpenAI-compatible endpoints. It is not a qe_delegate_agent target and does not change the frozen CLI delegation contract (claude, codex).

• Configure it with QE_OPENAI_COMPAT_BASE_URL, QE_OPENAI_COMPAT_API_KEY, and QE_OPENAI_COMPAT_MODEL.
• API keys are env-only. Passing key-like fields in tool arguments is rejected.
• If QE_OPENAI_COMPAT_BASE_URL is unset, the tool returns structured not_installed without making a network call.

Migrating 0.2 → 0.3 (breaking)

0.3.0 splits the expert library into a shipped core pack (25 experts) and an optional extra pack (@inho-team/qe-experts-extra, 61 experts). By default qe-mcp now loads only the core-25 — the install payload dropped to ~1.55 MB.

• To restore the full expert set, install the extra pack: qe-mcp packs install extra-experts (deploys to ~/.qe/mcp/packs/extra-experts/, auto-detected), or point QE_EXTRA_EXPERTS_ROOT at a checkout.
• The MCP surface was also slimmed to 10 tools in earlier 0.2.x work; qe_read_expert now takes format and section params (the old qe_expert_prompt tool is gone).
• Check installed packs with qe-mcp packs status.

Install

npm install -g @inho-team/qe-mcp

qe-mcp is the MCP companion for qe-framework. Install the framework plugin first, then connect this MCP package to the clients you use:

# 1. Install the QE Framework Claude/Codex plugin
claude plugin marketplace add inho-team/qe-framework
claude plugin install qe-framework@inho-team-qe-framework

# 2. Install the companion MCP package
npm install -g @inho-team/qe-mcp

# 3. Register the MCP server for local AI clients
qe-mcp init-registry
qe-mcp sync --client claude
qe-mcp sync --client codex

Run qe-mcp sync --dry-run --client claude or qe-mcp sync --dry-run --client codex first if you want to inspect the config file writes before applying them.

For local development:

git clone https://github.com/inho-team/qe-mcp.git
cd qe-mcp
npm run selftest

MCP Server

Direct stdio launch:

qe-mcp-server

Local source launch:

node scripts/qe_mcp_server.mjs

Registry Sync

Initialize a local registry:

qe-mcp init-registry

Preview client config writes:

qe-mcp sync --dry-run --client codex

Apply:

qe-mcp sync --client codex
qe-mcp sync --client claude
qe-mcp sync --client gemini

The default registry writes a qeExpertLibrary MCP server entry pointing at this package's scripts/qe_mcp_server.mjs.

qe-framework and qe-mcp are intended to run as twins:

• qe-framework installs the workflow skills, agents, hooks, and Codex assets.
• qe-mcp installs the external expert-library MCP server and cross-agent runner tools.
• Without qe-mcp, the core QE workflows still load, but expert-library MCP calls and cross-agent runner tools are unavailable.

Maintainers may also connect the separate admin MCP package, qe-admin-mcp, for release, bump, skill-test, audit, and migration workflows. That admin MCP is not required for normal framework usage.

Local Setup Check

After installing and syncing, restart Claude Code or Codex, then verify:

qe-mcp doctor
qe-mcp-server

In the client, the MCP tool list should include qeExpertLibrary tools such as qe_search_experts, qe_read_expert, qe_run_codex_agent, qe_run_claude_agent, qe_delegate_agent, qe_agent_run_status, qe_agent_run_read, qe_run_openai_compat_agent, and qe_cross_agent_help.

Tools

• qe_search_experts: compact metadata search
• qe_recommend_expert: task-based expert recommendation
• qe_read_expert: explicit bounded expert read
• qe_read_methodology: explicit bounded methodology/reference read
• qe_run_codex_agent: bounded local Codex CLI runner with capped timeout/output and default read-only posture
• qe_run_claude_agent: bounded local Claude CLI runner with capped timeout/output and fixed plan-mode posture
• qe_delegate_agent: generic bounded local delegation tool for target_engine: "codex" or "claude"
• qe_agent_run_status: read a compact lifecycle status projection by run_id
• qe_agent_run_read: read a bounded, redacted lifecycle/result projection by run_id
• qe_run_openai_compat_agent: experiment-only OpenAI-compatible endpoint runner, env-gated and standalone
• qe_cross_agent_help: passive local runner contract and CLI capability summary

Resources

• qe://experts/catalog
• qe://experts/<name>
• qe://experts/<name>/references
• qe://expert-packs/<pack>

Prompts

• qe-use-expert
• qe-review-with-expert
• qe-plan-with-expert

Verification

npm run check
npm run selftest
npm run runner:smoke

runner:smoke launches the local MCP server and calls qe_cross_agent_help, qe_run_codex_agent, qe_run_claude_agent, and qe_run_openai_compat_agent through the stdio MCP tool path. Authenticated local CLI runners should return status: "ok". The openai-compat runner returns structured not_installed when no endpoint is configured. Missing local login, missing CLI installs, provider quota limits, or bounded timeouts are reported as structured graceful failures instead of raw crashes.

Trust Boundary

The expert corpus is local passive data. Expert reads do not fetch remote code, do not auto-trust third-party MCP servers, and do not accept raw filesystem paths for expert reads. Expert content was migrated from the deleted optional QE catalog and should be treated as guidance that may need current API verification before implementation.

The cross-agent runner tools are active execution tools, but the public surface is still a bounded local delegation contract rather than a full autonomous multi-turn engine. The Phase 3 surface exposes qe_delegate_agent as the generic engine entry point for target_engine: "codex" or "claude". It records delegation direction, checks target capability before launch, tracks lifecycle state, and builds a standard prompt envelope for the CLI subprocess.

qe_run_codex_agent and qe_run_claude_agent remain public compatibility wrappers for callers that already use the engine-specific tool names. They should route through the same bounded engine contract as qe_delegate_agent; they are not separate permission surfaces.

Codex runner calls default to codex_config_mode: "isolated", which launches Codex with --ignore-user-config --ignore-rules so child runs do not inherit the caller's full ~/.codex/config.toml. When a workflow explicitly needs Codex native agents, skills, and rules, opt in with codex_config_mode: "native". Native mode still keeps the QE runner caps around cwd, timeout, output, sandbox, and recursion, but it allows Codex to load the user's normal Codex configuration. That can include native Codex agents, skills, rules, hooks, and MCP servers already configured for that Codex installation.

qe_agent_run_status and qe_agent_run_read are bounded lifecycle inspection APIs. They accept a run_id, read only the QE-managed lifecycle namespace, and return compact projections such as direction, decision, timestamps, status, transition metadata, and output sizes. They must not return raw full prompt, raw stdout, raw stderr, secret-like environment values, or arbitrary filesystem paths.

Runner tools launch only local CLIs with existing local auth, sanitize inherited environment variables, reject working directories outside this repository, cap timeout/output, and block nested cross-agent recursion by default. Isolated Codex mode rejects child config inheritance by passing --ignore-user-config and --ignore-rules; native Codex mode is explicit opt-in for workflows that need the user's configured Codex agents, skills, rules, hooks, or MCP servers. qe_cross_agent_help is passive and does not launch either runner or read lifecycle records.

Use passive expert tools for guidance-only workflows and routine expert-library lookups. Use qe_run_codex_agent or qe_run_claude_agent when an existing integration needs the legacy engine-specific wrapper. Use qe_delegate_agent when a caller wants the engine-level contract and explicit target selection. Use qe_agent_run_status or qe_agent_run_read after delegation when a caller needs bounded lifecycle inspection without raw capture exposure.

qe_run_openai_compat_agent is separate from delegation. It makes one bounded network call to the configured OpenAI-compatible endpoint and is disabled by default. It never accepts API keys through tool arguments.

Do not use the active runner tools for untrusted prompts, broad autonomous edits, or tasks that require inheriting a user's full MCP configuration.

The QE maintenance tools are explicit orchestration/status surfaces, not a scheduler. They never install timers, background daemons, or hidden recurring jobs inside the stdio MCP server. Time-based execution belongs to an external scheduler such as Qcron, launchd, cron, or CI. Maintenance run-once is limited to predefined read-only/report-only jobs and narrowly approved recoverable-write jobs.

Recoverable-write candidates (qrefresh, qarchive, qsweep) require an explicit preview-bound approval flow:

1. Call qe_run_maintenance_job with mode: "dry-run".
2. Inspect changed_paths_preview, recovery_strategy, and approval_fingerprint.
3. Call qe_run_maintenance_job with mode: "run-once", confirm_recoverable_write: true, and the matching approval_fingerprint.
4. Inspect changed_paths, recovery_manifest, status, and logs.

The approval fingerprint is bound to job_id, mode, workspace_root, changed_paths_preview, and permission_profile; mismatches fail closed with policy_denied. Recoverable-write execution is restricted to .qe/state maintenance paths and still denies source writes, config writes, secrets/env access, runner delegation, recursion, and internal scheduling.

The QE supervisor tools are also status/control surfaces, not a resident scheduler. They read .qe/state/supervisor or optional ~/.qe/daemon state, return bounded event/status/spec projections, and allow only explicit ack state writes. CLI install is dry-run only in this phase:

qe-mcp supervisor status --json
qe-mcp supervisor events --json
qe-mcp supervisor specs --json
qe-mcp supervisor install --dry-run --json

qe-mcp supervisor install without --dry-run fails closed and does not write service files, launch agents, cron entries, or start daemons.

Active Runner Examples

Use qe_cross_agent_help first when deciding whether local Codex or Claude is available. It is passive and does not launch either runner.

Minimal Codex runner call:

{
  "name": "qe_run_codex_agent",
  "arguments": {
    "prompt": "Summarize the current repository constraints.",
    "timeout_ms": 60000,
    "max_output_bytes": 24000,
    "allow_writes": false
  }
}

Codex native-config runner call:

{
  "name": "qe_run_codex_agent",
  "arguments": {
    "prompt": "Use the registered Ecode-reviewer agent to review the current diff.",
    "codex_config_mode": "native",
    "timeout_ms": 60000,
    "max_output_bytes": 24000,
    "allow_writes": false
  }
}

Minimal Claude runner call:

{
  "name": "qe_run_claude_agent",
  "arguments": {
    "prompt": "Review the runner policy boundary.",
    "permission_mode": "plan",
    "timeout_ms": 60000,
    "max_output_bytes": 24000,
    "allow_writes": false
  }
}

Minimal generic delegation call:

{
  "name": "qe_delegate_agent",
  "arguments": {
    "target_engine": "codex",
    "intent": "inspect-repository-constraints",
    "prompt": "Summarize the current repository constraints.",
    "timeout_ms": 60000,
    "max_output_bytes": 24000,
    "policy": {
      "allow_writes": false,
      "mcp_policy": "none",
      "max_concurrent_runs": 1
    },
    "output_contract": {
      "output_mode": "jsonl",
      "max_output_bytes": 24000
    }
  }
}

Minimal lifecycle status/read calls:

{
  "name": "qe_agent_run_status",
  "arguments": {
    "run_id": "example-run-id"
  }
}

{
  "name": "qe_agent_run_read",
  "arguments": {
    "run_id": "example-run-id",
    "include_transitions": true
  }
}

Write-capable runs require an explicit write policy. Codex requires allow_writes: true plus sandbox_mode: "workspace-write". Unsafe sandbox or permission modes such as danger-full-access and bypassPermissions are rejected. Recursive runner calls are blocked by default with recursion_blocked.

Compatibility and policy notes:

• prompt is the canonical input field. The legacy task alias is still accepted by the legacy runner wrappers. qe_delegate_agent uses prompt as its canonical input so new callers do not depend on wrapper aliases.
• Existing bounded runner tools are compatibility wrappers over the public delegation engine route. Help may expose engine metadata and lifecycle read boundaries, but it must not imply unrestricted swarms or multi-turn continuation.
• Delegation direction, target capabilities, lifecycle state, and prompt envelope construction are internal semantics used to make the bounded runner behavior inspectable and consistent.
• qe_agent_run_status and qe_agent_run_read are read-only projections over QE lifecycle records, not arbitrary file readers.
• Claude runner execution currently supports only permission_mode: "plan"; other permission modes fail closed instead of being accepted and ignored.
• mcp_policy currently supports only "none" because child MCP config inheritance is outside this trust boundary.
• max_concurrent_runs is capped at 1 per server process.

Troubleshooting:

• auth_missing: log in to the local provider CLI, then retry the same MCP tool call.
• not_installed: install the missing local codex or claude CLI.
• timeout or prompt_stalled: reduce prompt scope or raise timeout_ms within the schema maximum.
• budget_exceeded: reduce prompt scope or retry after provider quota resets.
• policy_denied: check cwd, write policy, output cap, recursion depth, and MCP config policy.