@superdoc/mcp 0.18.0-next.100

package/README.md

@@ -0,0 +1,153 @@
+# @superdoc/mcp
+
+MCP server for SuperDoc. Lets AI agents open, read, edit, and save `.docx` files through the [Model Context Protocol](https://modelcontextprotocol.io).
+
+Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.
+
+## Quick start
+
+```bash
+npx @superdoc/mcp
+```
+
+The server runs locally over stdio as a subprocess. You don't run it directly; your MCP client spawns it.
+
+## Setup
+
+### Claude Code
+
+```bash
+claude mcp add superdoc -- npx @superdoc/mcp
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "superdoc": {
+      "command": "npx",
+      "args": ["@superdoc/mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "superdoc": {
+      "command": "npx",
+      "args": ["@superdoc/mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "superdoc": {
+      "command": "npx",
+      "args": ["@superdoc/mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+Three lifecycle tools are always registered. The editing surface depends on `MCP_PRESET`:
+
+| `MCP_PRESET` | Tools |
+| --- | --- |
+| `legacy` (default) | 13: 3 lifecycle + 10 grouped intent tools |
+| `core` | 5: 3 lifecycle + `superdoc_inspect` and `superdoc_perform_action` |
+
+All tools except `superdoc_open` take a `session_id` from `superdoc_open`.
+
+Pass absolute paths. A relative path resolves against the server process's working directory, which your MCP client chooses. `superdoc_open` also opens a blank document when the path does not exist rather than reporting an error, so a wrong path presents as an empty file instead of a failure.
+
+The server reads and writes any path it is given, with no restriction to a particular directory. Run it under a container, a dedicated user account, or an OS sandbox if you need to bound what it can reach.
+
+`superdoc_save` has no overwrite guard: it resolves `out` and writes it, replacing any file already there, including the source. Point the agent at copies, and preflight the destination yourself when a workflow cannot tolerate that.
+
+### Lifecycle
+
+| Tool | Description |
+| --- | --- |
+| `superdoc_open` | Open a `.docx` file by absolute path and get a `session_id`. A missing path opens a blank document |
+| `superdoc_save` | Save the document to disk (original path or custom `out` path). Overwrites an existing file without warning |
+| `superdoc_close` | Close the session and release memory |
+
+### Intent tools (`legacy` preset)
+
+Most intent tools take an `action` argument selecting the operation within the group. `superdoc_search` is the exception: it takes `select`, not `action`.
+
+| Tool | Covers |
+| --- | --- |
+| `superdoc_get_content` | Read the document as text, markdown, HTML, blocks, or metadata |
+| `superdoc_search` | Find content and return stable targets. Takes `select`, not `action` |
+| `superdoc_edit` | Insert, replace, and delete text, plus undo and redo |
+| `superdoc_format` | Inline and paragraph formatting, styles, direction, and flow |
+| `superdoc_create` | Create paragraphs, headings, and tables |
+| `superdoc_list` | Create, convert, nest, split, merge, and renumber lists |
+| `superdoc_table` | Table structure, content, and styling |
+| `superdoc_comment` | Create, update, resolve, and read comment threads |
+| `superdoc_track_changes` | List tracked changes and decide on them |
+| `superdoc_mutations` | Preview and apply multi-step edits as one atomic batch |
+
+Each tool's exact action list is generated from the Document API contract and changes with it. Read the advertised schema rather than a copy of it. Every tool's JSON Schema is served over MCP, and `getToolCatalog('legacy')` in `@superdoc/sdk` returns the same data.
+
+## Workflow
+
+Every interaction follows the same pattern:
+
+```
+open → read/search → edit → save → close
+```
+
+1. `superdoc_open` loads a document and returns a `session_id`
+2. `superdoc_get_content` reads the current document and `superdoc_search` finds stable handles or addresses
+3. Intent tools use `session_id` plus `action` to modify content
+4. `superdoc_save` writes changes to disk
+5. `superdoc_close` releases the session
+
+Steps 2 and 3 name `legacy` tools. Under `MCP_PRESET=core` the shape is the same, but reads go through `superdoc_inspect` and edits through `superdoc_perform_action`. The lifecycle steps are identical under both presets.
+
+### Tracked changes
+
+Actions that support tracked edits use the underlying Document API's `changeMode: "tracked"` option.
+
+Reviewing them differs by preset. Under `legacy`, call `superdoc_track_changes`. Under `core` that tool does not exist: use `superdoc_perform_action` with `accept_tracked_changes` or `reject_tracked_changes`.
+
+Not every action honors `changeMode`. Some ignore it and edit directly, and `move_range` accepts it and then fails without mutating, so check the action rather than assuming the argument applied.
+
+Every session authors its changes as `MCP Server`; there is no way to configure that identity. Two MCP deployments editing the same document produce tracked changes a reviewer cannot tell apart. Use the SDK when attribution matters.
+
+## Development
+
+```bash
+# Run locally
+bun run src/index.ts
+
+# Run tests
+bun test
+
+# Test with MCP Inspector
+npx @modelcontextprotocol/inspector -- bun run src/index.ts
+```
+
+## License
+
+See the [SuperDoc license](../../LICENSE).