lsp-format-code

Files (1)

• SKILL.md

SKILL.md (first lines)

> Requires the agent-lsp MCP server.

# lsp-format-code

Format a file or selection using the language server's formatter — the same
formatting engine your IDE uses. Applies language-specific rules (gofmt, prettier,
rustfmt, black) without requiring those tools to be on PATH separately.

## When to use

- Before committing: ensure consistent style across edited files
- After generating code: clean up AI-generated indentation and spacing
- After a refactor that shifted indentation levels
- When a linter flags style violations fixable by the formatter

Use `/lsp-safe-edit` instead when you are making a logic change and want
before/after diagnostic comparison alongside the edit.

---

## Workflow

### Step 1 — Check formatting is supported (optional)

If unsure whether the language server supports formatting for this file, check
capabilities first:

```
mcp__lsp__get_server_capabilities({ "file_path": "<file>" })
```

Look for `documentFormattingProvider` (full-file) and
`documentRangeFormattingProvider` (range). If neither is present, the server
does not support formatting — stop and report.

Skip this step if you know the language supports formatting (Go, TypeScript,
Rust, Python all do via their standard servers).

### Step 2 — Open the file

```
mcp__lsp__open_document({ "file_path": "/abs/path/to/file.go", "language_id": "go" })
```

### Step 3 — Request formatting edits

**Full file:**
```
mcp__lsp__format_document({ "file_path": "/abs/path/to/file.go" })
```

**Selection only:**
```
mcp__lsp__format_range({
  "file_path": "/abs/path/to/file.go",
  "start_line": <N>,
  "end_line": <M>
})
```

Both return `TextEdit[]` — a list of replacements to apply. They do **not**
write to disk. If the list is empty, the file is already correctly formatted.

### Step 4 — Apply the edits

Pass the `TextEdit[]` from Step 3 to `apply_edit`:

```
mcp__lsp__apply_edit({ "workspace_edit": <TextEdit[] from Step 3> })
```

This writes the formatting changes to disk.

### Step 5 — Verify (optional but recommended)

Call `get_diagnostics` to confirm formatting did not introduce any errors:

```
mcp__lsp__get_diagnostics({ "file_path": "/abs/path/to/file.go" })
```

Formatting should never introduce errors — if it does, report immediately
without committing.

---

## Output format

```
## Format result: <filename>

Changes applied: N edits
Lines affected: <range or "whole file">
Formatter: <gopls | typescript-language-server | rust-analyzer | ...>

Status: FORMATTED ✓
```

If no edits were returned:
```
Status: ALREADY FORMATTED — no changes needed
```

If formatting is not supported:
```
Status: NOT SUPPORTED — <server> does not expose documentFormattingProvider
Fallback: run the formatter directly (gofmt, prettier, rustfmt, etc.)
```

---

## Multi-file formatting

For formatting multiple files (e.g. all files changed in a PR):

1. Call `format_document` for each file — these can run in parallel.
2. Collect all `TextEdit[]` responses.
3. Apply each file's edits via `apply_edit` sequentially.
4. Report total edits across all files.

From blackwell-systems/agent-lsp, MIT.

More from blackwell-systems/agent-lsp