MCP Hooks and AgentTarget

MCP, Hooks, and AgentTarget Design

Language: English · 简体中文

LWC connects to Agent hosts through one read-only MCP server, bounded lifecycle Hooks, owned Instructions and Skills, and 12 handwritten AgentTarget adapters. Every target is a strong adapter: it installs every stable official file-based surface available for that host and scope, then reports official gaps instead of inventing private formats.

MCP standardizes runtime messages. It does not standardize configuration paths, Skills, Hooks, Instructions, plugins, or permissions, so host compatibility must remain explicit.

Integration architecture

Agent host
   |-- MCP config / extension bridge --> lwc serve --mcp --> lwc_explore
   |-- lifecycle event ---------------> lwc agent hook --> bounded readiness
   |-- Skill --------------------------> when and how to use LWC
   `-- Instructions -------------------> durable host guidance
                                              |
                                              v
                                  AgentTarget adapter + receipt

MCP stays identical across native hosts: one server named lwc, one read-only tool, and no hidden mutation. Host-specific work is confined to adapters that know official locations and formats.

Shared AgentTarget contract

Every adapter implements the same lifecycle and capability contract:

trait AgentTarget {
    fn id(&self) -> &'static str;
    fn adaptation(&self) -> &'static str;
    fn mcp_mode(&self, location: AgentLocation) -> &'static str;
    fn permissions_mode(&self, location: AgentLocation) -> &'static str;
    fn instructions_mode(&self, location: AgentLocation) -> &'static str;
    fn skills_mode(&self, location: AgentLocation) -> &'static str;
    fn lifecycle_mode(&self, location: AgentLocation) -> &'static str;
    fn supports_location(&self, location: AgentLocation) -> bool;
    fn detect(&self, environment: &TargetEnvironment) -> DetectionResult;
    fn install(&self, environment: &TargetEnvironment, options: InstallOptions) -> Result<WriteResult>;
    fn uninstall(&self, environment: &TargetEnvironment) -> Result<WriteResult>;
    fn print_config(&self, location: AgentLocation) -> String;
    fn describe_paths(&self, environment: &TargetEnvironment) -> Vec<PathBuf>;
}

The registry holds one handwritten implementation per host. Shared orchestration handles selection, status, receipts, refresh, and partial failure; adapters handle only official host differences.

Ownership and idempotence

Install snapshots the original content and records the post-install hash for every owned path. Marker-bounded prose lets LWC replace only its own Instructions. Structured MCP and Hook fragments are removed only when they still match LWC ownership.

refresh reuses the same adapter and receipt rather than layering duplicate entries. uninstall restores original content or removes exact owned fragments, and refuses ambiguous foreign conflicts. --print-config renders without creating a receipt or writing a host file.

Supported targets

claude             Claude Code
cursor             Cursor
codex              Codex
opencode           OpenCode
hermes             Hermes Agent
gemini             Gemini CLI
antigravity        Antigravity
kiro               Kiro
copilot-vscode     VS Code with GitHub Copilot Chat
copilot-cli        GitHub Copilot CLI
copilot-jetbrains  JetBrains IDEs with GitHub Copilot
pi                 Pi Agent

Capability modes

Mode	Meaning
installed	LWC wrote the official stable surface and tracks ownership
extension_bridge	The host lacks built-in MCP configuration; an official extension mechanism bridges LWC
configured_preview	LWC wrote a documented preview or version-gated surface; host activation still requires verification
user_managed	The host owns the setting through UI or has no stable file path
unsupported	The selected host location has no official surface
not_applicable	The capability does not exist for that host model

adaptation=strong does not mean every cell is installed. It means the adapter encodes the host's actual official capability and refuses to fake missing support.

Current matrix

Each cell is global / local.

Target	MCP	Skill	Instructions	Hook	Permissions
Claude Code	installed / installed	installed / installed	installed / installed	installed / installed	installed / installed
Cursor	installed / installed	installed / installed	user_managed / installed	installed / installed	not_applicable / not_applicable
Codex	installed / installed	installed / installed	installed / installed	installed / installed	not_applicable / not_applicable
OpenCode	installed / installed	installed / installed	installed / installed	installed / installed	not_applicable / not_applicable
Hermes Agent	installed / unsupported	installed / unsupported	installed / installed	installed / unsupported	not_applicable / not_applicable
Gemini CLI	installed / installed	installed / installed	installed / installed	installed / installed	not_applicable / not_applicable
Antigravity	installed / installed	installed / installed	installed / installed	installed / installed	not_applicable / not_applicable
Kiro	installed / installed	installed / installed	installed / installed	configured_preview / configured_preview	user_managed / user_managed
Copilot VS Code	installed / installed	installed / installed	user_managed / installed	unsupported / configured_preview	user_managed / user_managed
Copilot CLI	installed / installed	installed / installed	installed / installed	installed / installed	user_managed / user_managed
Copilot JetBrains	installed / user_managed	configured_preview / configured_preview	user_managed / configured_preview	unsupported / unsupported	user_managed / user_managed
Pi Agent	extension_bridge / extension_bridge	installed / installed	installed / installed	installed / installed	not_applicable / not_applicable

configured_preview cells require a host release that exposes the documented preview surface. LWC status reports the configured state; it does not claim the host loaded it without an actual host-level check.

Unified Agent-facing MCP

Every native MCP adapter registers one server named lwc:

lwc serve --mcp

CodeGraph is fused behind lwc_explore; it is not registered as a second codegraph MCP server. The runtime exposes one read-only tool with memory, code, and combined modes.

Pi has no built-in MCP configuration and therefore uses its official extension bridge. That difference is reported, not hidden.

Global and local are host locations

• Global configures the current user's Agent installation.
• Local configures the current project through that host's repository surfaces.

These locations do not select LWC Wiki scope and do not enable project graph capabilities. A globally installed Agent integration can still operate on the current project's Wiki through normal project discovery.

Some hosts intentionally have partial local support. Hermes has no separate local root for MCP, Skill, or Shell Hook, while JetBrains keeps local MCP UI-managed. Their supported local Instructions or preview Skills remain installable.

Permissions

Permissions are host-private and have no cross-Agent standard.

Claude Code supports an official allow-list for LWC's read-only MCP tool. LWC installs only the narrow owned entries. Other hosts may expose trust prompts or UI-owned permissions; adapters report user_managed and never grant broad tool or shell access on the user's behalf.

Detect and review

lwc agent status --target auto --location global
lwc agent install --print-config codex --location global

Detection means the host appears installed. It is not consent to mutate its files. Interactive install preselects detected targets; --yes accepts detected defaults, not all targets.

--print-config performs no write and is the correct path for managed environments or review before installation.

Installation acceptance

For each intended target:

1. run install at the chosen location;
2. require adaptation=strong and inspect every capability mode;
3. verify the host loads the Skill and marker-bounded Instructions;
4. invoke one real lifecycle Hook envelope and inspect bounded readiness;
5. initialize MCP, list exactly one lwc_explore tool, and make a read-only call;
6. run refresh and confirm no-drift byte idempotence;
7. test uninstall in an isolated host profile and confirm foreign content survives.

Do not mark the target broken because an official cell is user_managed or unsupported. Mark it broken when the adapter misreports that boundary, writes an unofficial surface, or fails an officially supported one.

Official-source policy

Agent hosts change faster than LWC's core Store. Compatibility changes require:

• current official host documentation for every written path or format;
• a source-linked capability matrix update;
• global and local install/status/refresh/uninstall tests;
• real host-level acceptance for lifecycle and MCP behavior where available;
• no maintainer-local tools, paths, or files in the adapter.

Community examples can reveal a gap, but they do not authorize a new integration format without official evidence.

No private environment assumptions

All users need only:

• a compatible global lwc on PATH;
• the Agent's official directories and configuration support;
• the project directory for local installation.

AMC, a maintainer's HOME layout, absolute private binary variables, and copied local plugin caches are not dependencies.

For paths, lifecycle commands, ownership receipts, refresh, and uninstall behavior, continue with AgentTarget installation and integration.