carve-mcp
Official# 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 headings, footnotes, node types, or a current
AST path without making an ambiguous selection for the caller.
- `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.
- `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).
## 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.
[](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)
[](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.
TDQS
Scored across 13 tools
Most tools target distinct operations, but the create_ast_patch/create_reversible_ast_patch and apply_ast_patch/apply_reversible_ast_patch pairs have heavily overlapping purposes and could cause misselection. Similarly, plan_ast_edit and diagnose_and_fix both surface proposed changes, though their intended workflows differ. Overall, descriptions help, but boundaries between the patch-related tools are not crisp.
All tools follow a consistent carve_ prefix with snake_case verb_noun naming, e.g. carve_parse, carve_render, carve_migrate, carve_create_ast_patch. The pattern is predictable and makes the purpose of each tool clear from its name alone.
With 13 tools, the server is well within the ideal 3-15 range for a domain-specific toolset. Each tool covers a distinct phase of the Carve document workflow: parsing, rendering, formatting, linting, migrating, patching, and cross-target checking. The count feels proportional to the complexity of the domain.
The toolset covers a comprehensive document lifecycle: parse, edit via AST patches, render, format, lint, migrate, check target compatibility, and diagnose/fix. Minor gaps include a lack of direct high-level document creation or deletion operations, though these can be handled through migration and AST patch operations. Overall, agents should be able to complete most Carve authoring and conversion workflows without dead ends.