/platform-lsp-integrate

name: platform-lsp-integrate
description: "Reference/contract for the Salesforce LSP MCP tools and unavailability handling. Use when asking how to use the LSP, which tools exist, what apex.diagnostics / validate_soql / complete_soql do, why a tool errors with lsp_disabled, no_apex_workspace, or no_org_connected, or how to debug/disable it. DO NOT TRIGGER for editing Apex/LWC/metadata (platform-apex-generate), deploys (platform-metadata-deploy), or SOQL authoring (platform-soql-query); scoped to LSP-layer/MCP-tool questions only."
allowed-tools: Bash Read mcp__plugin_salesforce-development_salesforce-lsp__lsp_health
metadata:
  mcpTools:
    # Native salesforce-lsp server tool ID (the bundled LSP host registers it
    # dotted as lsp.health). In allowed-tools it appears in Claude Code's
    # sanitized form: mcp__plugin_salesforce-development_salesforce-lsp__lsp_health.
    salesforce-lsp:
      tools: ["lsp.health"]
      semver: ">=0.1.0"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"
  relatedSkills:
    - "platform-apex-generate"
    - "platform-metadata-deploy"
    - "platform-soql-query"

Using the Salesforce LSP

The `salesforce-development` plugin hosts a local MCP server named **`salesforce-lsp`** that lazily spawns Salesforce Language Server children and exposes their semantic capabilities as MCP tools. This skill is the **contract** other skills follow when they call those tools, and the answer to "how do I use the Salesforce LSP?" — what each tool does, how to read its result, what every error code means, and how to fall back when the host is absent.

This is a documentation/reference skill. It does not author or deploy code; it tells you (and other skills) how to drive the LSP tools correctly.

> **This plugin build vendors Apex + SOQL only.** The `salesforce-lsp` host > ships the Apex language server (`@salesforce/apex-ls`) and the SOQL language > server. The **LWC** language server is intentionally **not** bundled in this > plugin — the `lwc.*` tools are registered by the host but will always return > an `unavailable`-class envelope here. Treat any `lwc.*` call as unavailable > and use the fallback (read the component source / deploy-compile).

When to Use This Skill

• A user asks how to use the Salesforce LSP, or which LSP/MCP tools are available.
• A user asks what a specific tool does (`apex.diagnostics`, `validate_soql`,

`complete_soql`, etc.) or how to read its output.

• An LSP tool returned an error envelope (`lsp_disabled`, `spawn_timeout`,

`circuit_open`, `no_apex_workspace`, `no_org_connected`) and you need to know what it means and how to recover.

• You're authoring or reviewing another skill that calls an LSP tool and need the

canonical call/fallback pattern.

• The LSP seems broken and you need to debug it (`lsp.health`,

`${CLAUDE_PLUGIN_ROOT}/bin/lsp-doctor`, the kill switch).

The Tools

All tools are served by the MCP server **`salesforce-lsp`** (invoke names follow the plugin-prefixed pattern: `mcp__plugin_salesforce-development_salesforce-lsp__<tool_name>`, where dots in tool names become underscores — e.g. `apex.diagnostics` becomes `mcp__plugin_salesforce-development_salesforce-lsp__apex_diagnostics`). Spawning is lazy: a tool that needs a language server brings the child up on first call (a one-time cold start of a few seconds for Apex), then reuses it. The pure static-analysis tools never spawn anything.

Apex (spawns the Apex LSP)

| Tool | Purpose | Key input | Key output | |---|---|---|---| | `apex.diagnostics` | Compile-check a `.cls`/`.trigger`; surface errors/warnings | `{ filePath }` | `{ ok, diagnostics: [{ line, column, severity, message }] }` | | `apex.hover` | Type/signature at a position | `{ filePath, line, character }` | hover markdown | | `apex.documentSymbol` | Outline of a file's symbols | `{ filePath }` | symbol tree | | `apex.completion` | Code-completion at a position | `{ filePath, line, character }` | completion items |

SOQL

| Tool | Purpose | Spawns? | Key output | |---|---|---|---| | `validate_soql` | Parse a SOQL string for **syntax** errors | SOQL LSP | `{ ok, diagnostics: [{ line, column, severity, message }] }` | | `complete_soql` | Schema-aware completion at a cursor (SObjects, fields, picklist values resolved against the org) | SOQL LSP | `{ ok, items, expanded, unresolved, hint? }` | | `extract_soql_from_apex` | Statically pull every inline `[SELECT …]` out of Apex | **No** (pure static) | `{ ok, totalQueries, totalDynamic, files }` | | `check_soql_selectivity` | Selectivity heuristics (optional org LIMIT-0 probe) | **No** by default | selectivity report | | `refresh_org_schema` | Invalidate the cached org describe so completion re-fetches | **No** | `{ ok, removed }` |

> **Just deployed a field/object and it won't resolve?** When a SOQL or Apex > reference to a *freshly-deployed* field fails (e.g. `No such column 'Foo__c'`, > or `complete_soql` doesn't offer it) right after a deploy, the cached org > describe is stale — call **`refresh_org_schema`** to invalidate it, then re-run > the check before assuming a code error or renaming anything. This is the lever > for post-deploy schema lag; reach for it *before* treating the failure as a bug > in your query/class. (It only clears the local cache; it can't speed up > server-side propagation, so if the org itself hasn't finished publishing the > field, re-running after a moment is the fallback.)

LWC — not available in this build

The `lwc.*` tools (`lwc.diagnostics`, `lwc.hover`, `lwc.definition`, `lwc.completion`, `lwc.workspace_symbols`) are registered by the host but the LWC language server is **not vendored** in this plugin. Every `lwc.*` call returns an unavailable envelope. For LWC work, fall back to reading the component source/templates directly or deploy-compiling and reading the CLI errors.

Diagnostics / health

| Tool | Purpose | Spawns? | |---|---|---| | `lsp.health` | Read-only view of kill-switch mode, worksp