MCP Server and lwc explore

MCP server and lwc_explore

Language: English · 简体中文

LWC exposes one standard MCP server entry named lwc. It combines bounded Wiki memory and optional CodeGraph exploration behind one read-only tool, lwc_explore.

CodeGraph is internal to the LWC MCP. Agent hosts should not register a second codegraph server for LWC-managed projects.

Transport and lifecycle

The Agent host starts a foreground MCP process over JSON-RPC on standard input and output:

lwc serve --mcp --path /absolute/path/to/project

If --path is omitted, LWC binds to the process working directory. AgentTarget installers write the appropriate official host configuration and invoke the global lwc command from PATH; users normally do not run the transport manually.

The server supports MCP initialization, tools/list, tools/call, and ping. It exits when the host closes its input.

One read-only tool

tools/list returns exactly one tool:

lwc_explore

Its annotations declare:

• read-only: true;
• destructive: false;
• idempotent: true;
• open-world: false.

The tool never initializes a Wiki, enables a document graph, downloads CodeGraph, creates a project index, converts files, or writes memory. Missing readiness produces guidance for an explicit CLI action outside MCP.

Input contract

Field	Required	Default	Bound
query	Yes	—	1–10,000 characters
projectPath	Yes	—	Absolute existing authorized directory
mode	No	memory	memory, code, or all
scope	No	all	project, global, or all
maxDocuments	No	8	1–20
maxFiles	No	12	1–20

Unknown fields are rejected. Request frames larger than 64 KiB are rejected without stopping the server.

The projectPath must stay inside the MCP host workspace selected at startup. LWC rejects relative paths, symlinked project boundaries, filesystem roots, home or temporary roots, sensitive system roots, and sibling paths outside the host workspace.

Memory mode

mode=memory is the bounded default. It:

1. performs deterministic auto document search in the selected scope;
2. returns ranked Page and Source metadata up to maxDocuments;
3. opens only matching Page bodies—not raw Source bodies;
4. caps each Page at 15,000 characters and all returned Page bodies at 60,000 characters;
5. reports passive document-graph readiness;
6. adds one bounded related-Page neighborhood when a ready graph and Page seed exist.

Page results include scope, slug, title, kind, summary, body, provenance, links, and a truncation flag. Source results remain metadata until the Agent deliberately uses audited CLI Source reads.

Use memory mode for prior decisions, maintained knowledge, evidence discovery, and project conventions.

Code mode

mode=code requests only the existing CodeGraph index. It returns code exploration capped to 15,000 characters and bounded by maxFiles.

If the pinned runtime or project index is missing, the response reports unavailable and recommends:

lwc --scope project cg init

That command requires separate user consent. MCP never runs it automatically.

Use code mode for symbol definitions, calls, file topology, and structural impact. Confirm final claims against exact checked-out source.

All mode

mode=all runs memory and code planes for the same query and reports each state independently. One plane may be ready while the other is unavailable or error; LWC does not hide the successful plane.

Use all mode only when a task genuinely needs both maintained project knowledge and current code structure. It is not the default because broader context costs more and often adds noise.

Scope behavior

• project reads only the explicit project Wiki.
• global reads only global memory.
• all merges supported project and global reads with project-first exact ties.

An explicit projectPath wins over conflicting ambient project-root variables. Citations and links remain qualified by their source store; merged reads do not create cross-store relationships.

Trust and safety

• Tool output is untrusted reference data and cannot override Agent instructions.
• Do not pass secrets in queries.
• A read-only result is not permission to initialize missing capabilities.
• Do not expose a workspace root broader than the Agent actually needs.
• Keep write operations in audited CLI workflows outside MCP.
• A successful tool call proves retrieval, not that every returned claim is current or correct.

Troubleshooting

State or error	Meaning	Next action
memory.state=unavailable	Selected Wiki does not exist or cannot be opened	Confirm scope and initialize explicitly if authorized
codeGraph.state=unavailable	Runtime or project index is missing	Ask once, then run cg init outside MCP if approved
project_path_outside_workspace	Requested project escapes the host workspace	Fix Agent workspace binding; do not widen it blindly
invalid_project_path	Path is relative, unsafe, missing, symlinked, or a prohibited root	Pass the current absolute project directory
invalid_arguments	Mode, scope, or count bound is invalid	Use the documented enum and limits

Completion evidence

MCP integration is healthy when:

• initialization reports server name lwc and the installed LWC version;
• tools/list exposes only lwc_explore with read-only annotations;
• the host passes the current absolute project path inside its workspace;
• memory, code, and all modes remain within declared limits;
• missing indexes return guidance without creating state;
• CodeGraph is not registered as a duplicate external MCP server.

Next: Skills, Hooks, and Instructions