# Carve MCP server

Give MCP-compatible assistants the same Carve parser, linter, formatter, and
renderers used by the JavaScript implementation. Filesystem access is absent by
default and can be enabled for explicitly configured document roots.

## Tools

- `carve_lint` checks a document and returns precise, structured warnings.
- `carve_diagnose_and_fix` previews safe fixes, applies selected fix IDs, and returns an undo patch; ambiguous repairs remain writer-review items.
- `carve_format` produces canonical Carve and reports rendering losses.
- `carve_render` renders HTML, Markdown, plain text, or ANSI.
- `carve_check_targets` compares publishing compatibility across HTML, Markdown, plain text, ANSI, GitHub, WordPress, and PDF-stage profiles.
- `carve_parse` returns the resolved, position-aware interchange AST.
- `carve_create_ast_patch` compares two interchange ASTs and returns a
  position-independent patch.
- `carve_apply_ast_patch` validates and previews a patch as both an AST and
  canonical Carve source without changing files.
- `carve_select_ast_nodes` finds any block or inline node by its `{#id}`,
  headings, footnotes, node types, or a current AST path without making an
  ambiguous selection for the caller.
- `carve_get_block` returns the exact source text of the nodes a selector
  matches, or a heading's whole section, with UTF-8 byte offsets and the
  source sha256. It reads a workspace file by path when a root is configured.
- `carve_replace_source` splices new Carve text over the exact bytes of one
  selected node or heading section and leaves every other byte alone. It
  refuses edits that change the node's kind, change how the rest of the
  document parses, or add lint findings, returns forward and undo patches, and
  can write the result through the hash-guarded workspace write.
- `carve_plan_ast_edit` turns one or more exact semantic matches and small edit
  intents into one explained, reversible source patch for approval.
- `carve_create_reversible_ast_patch` adds inverse operations and semantic
  stale-edit fingerprints.
- `carve_apply_reversible_ast_patch` safely previews forward or undo operations
  as a guarded UTF-8 source edit. The patched AST is returned only with
  `includeAst: true`.
- `carve_migrate` converts HTML, Markdown, Djot, or BBCode and reports version 2 migration fidelity.
- `carve_reference_graph` indexes cross-document headings, footnotes, abbreviations, links, and images, including broken edges and orphaned definitions (when workspace access is enabled).

Tools return concise text for readers alongside schema-validated structured
results for clients. Six optional prompts guide common review, conversion, and
publishing workflows without replacing the writer's judgment.

Use `--tool-profile review`, `convert`, `structure`, or `workspace` to expose
only the tools needed for that job and reduce model context. The default `all`
profile preserves the complete tool surface.

Raw HTML passthrough is disabled by default because MCP inputs are untrusted.
The server has no filesystem access unless you explicitly give it a workspace
root. That also governs `{{ path }}` includes, which stay literal until a call
names a configured root. See [Include expansion](docs/development.md#include-expansion).

### Compatibility assessment scope

`carve_check_targets` reports render losses and table-preservation
diagnostics separately. A target is `lossy` if either assessment finds a change.
Merged cells and caption associations can therefore require review even when
the pinned engine returns zero render losses. Table diagnostics name the AST
node path and affected field.

Each result includes `assessmentScope` and a `preservation` report with
`complete: false`, checked fields, and unchecked boundaries. A `compatible`
result means the declared checks found no issue. It does not certify every
semantic property, host behavior, or source spelling. The PDF profile assesses
the HTML stage only; it does not check the final PDF.

The server bundles the `table-structure-v1` assessment so these checks work
with its published, pinned engine. Keep its contract aligned with the
JavaScript engine's preservation API when extending the checked fields.

## Resources

- `carve://guide` is a concise authoring quick start.
- `carve://rules` explains the normative rule categories.
- `carve://rules/{ruleId}` looks up a stable normative `CARVE-*` rule ID, such as
  `carve://rules/CARVE-P0-001`.
- `carve://lint-rules/{ruleName}` explains a stable diagnostic name returned by
  `carve_lint`.

The resources identify the Carve version and link to the complete documentation
when a reader needs normative detail. Lint diagnostic names are a separate
namespace and are returned with their explanations directly by `carve_lint`.

## Get started

Node.js 20 or newer is required.

```sh
npx -y @markup-carve/carve-mcp
```

See [Connect Carve to your writing tool](docs/client-setup.md) for copy-ready
setup in Claude, VS Code, Cursor, Zed, and Codex, plus prompts to confirm it
works.
The [compatibility page](docs/client-compatibility.md) explains what CI verifies
and provides the short host smoke test used for releases.

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Carve-007ACC?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522carve%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540markup-carve%252Fcarve-mcp%2522%255D%257D)
[![Add to Cursor](https://img.shields.io/badge/Cursor-Add_Carve-111111)](https://cursor.com/install-mcp?name=carve&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtYXJrdXAtY2FydmUvY2FydmUtbWNwIl19)

The [writer workflows](examples/README.md) show practical review, conversion,
preview, GitHub publishing, and documentation-folder tasks.

For local builds, workspace access, native binaries, HTTP and container
deployment, and contributor checks, see [Development and deployment](docs/development.md).

This project is licensed under the MIT License.

Table alignment checks treat an unset alignment as left alignment. Host CSS and default header styling are outside the assessment.