/platform-lsp-integrate

name: platform-lsp-integrate
description: "Reference for how to call the Salesforce LSP MCP tools and what to do when they are unavailable. Use when the user asks how to use the Salesforce LSP, which LSP/MCP tools exist, what apex.diagnostics / validate_soql / complete_soql do, why an LSP tool returned an error like lsp_disabled or no_apex_workspace or no_org_connected, how to debug the LSP host, or how to turn the LSP off. Also the contract other skills follow when they call an LSP tool: which tool to prefer, how to read its result, and the fallback when the LSP host is absent. DO NOT TRIGGER for generating or editing Apex/LWC/metadata (use platform-apex-generate), running deploys (use platform-metadata-deploy), or SOQL authoring (use platform-soql-query); this skill is a reference and contract document — use it only when the question is specifically about the LSP layer or its MCP tools."
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