dx-writing
by soul667
README.md
# DX Writing
**Academic Minimalist (`Paper & Obsidian`) collaborative review UI and bidirectional MCP server for LaTeX & Markdown manuscripts.**
Live Interactive Demo & Docs: **[https://soul667.github.io/dx-writing/](https://soul667.github.io/dx-writing/)**
---
`DX Writing` brings **Notion-style stackable margin `CommentThread`s** to local `.tex` and `.md` academic writing—powered by zero-dependency Python (`>=3.10`) and a dual **Stdio + Streamable HTTP MCP server**:
- **Zero-Invasion Sidecar (`.dx-writing/`)**: Comments, multi-version AI rewrite candidates (`v1a` / `v1b` / `v1c`), and baseline snapshots live outside your source files—never polluting `.tex` or breaking `latexmk` / `git diff`.
- **Offset-Preserving `Clean` LaTeX View**: Strips `\textbf{}`, `\cite{}`, inline `$...$` math, booktabs `tabular` environments, and custom zero-arg `\newcommand` macros into calm serif prose while mapping mouse selections back to exact `.tex` character offsets.
- **Hover Preview, One-Click `Apply` & `Revert`**: Hover any candidate version in the margin to preview it seamlessly inside the paragraph; click `Apply` to write it to disk while keeping the anchor alive for further iteration, or `Revert` anytime.
- **Multi-Select Copy (`Copy Selected to AI` & Multi-Passage Pick)**:
- Check multiple margin threads (`Shift+Click` range select supported) to bundle their quotes, history, and drafts into one structured AI/MCP prompt (`Copy Selected (N)` or `Ctrl+C`).
- Hold `Ctrl`/`Cmd` while dragging (or click `+ Multi-select`) in `Clean` mode to select and copy multiple non-adjacent manuscript passages at once.
- **Optional `Redline` & Direct `LaTeX / Source` Sync**: Switch to inline character-level `Redline` diff against baseline only when needed; edits in `Source` automatically re-anchor existing threads via prefix/suffix context matching.
---
## 1. Quick Start
```bash
git clone https://github.com/soul667/dx-writing.git
cd dx-writing
pip install -e .
# Launch Web UI + Streamable HTTP MCP inside any paper/notes workspace
dx-writing serve --workspace /path/to/your/paper --port 5926
```
Or run directly without installing (zero third-party dependencies):
```bash
PYTHONPATH="src" python3 -m dx_writing serve --workspace /path/to/your/paper --port 5926
```
- **Web Workspace**: `http://127.0.0.1:5926`
- **Streamable HTTP MCP Endpoint**: `http://127.0.0.1:5926/mcp`
- **CLI Status & Config Generator**:
```bash
dx-writing status --workspace /path/to/your/paper
dx-writing mcp-config --workspace /path/to/your/paper
```
---
## 2. Connect Your AI Agent (MCP)
### Option A: Streamable HTTP MCP (when `dx-writing serve` is running)
```bash
# Claude Code
claude mcp add --transport http dx-writing http://127.0.0.1:5926/mcp
```
Or in `mcp_config.json` (Antigravity / Cursor / Windsurf):
```json
{
"mcpServers": {
"dx-writing": {
"serverUrl": "http://127.0.0.1:5926/mcp"
}
}
}
```
### Option B: Stdio MCP (works even without the Web server running)
```bash
# Codex CLI
codex mcp add dx-writing -- dx-writing mcp --workspace /path/to/your/paper
```
```json
{
"mcpServers": {
"dx-writing": {
"command": "dx-writing",
"args": ["mcp", "--workspace", "/path/to/your/paper"]
}
}
}
```
An optional agent skill guiding non-invasive multi-version academic review is included at [`skills/dx-writing/SKILL.md`](skills/dx-writing/SKILL.md).
---
## 3. MCP Tools Reference
| Tool | Purpose |
| --- | --- |
| `dx_list_documents` | List `.tex` / `.md` / `.txt` manuscripts with open thread counts and `pending_human_feedback` counts |
| `dx_read_document` | Read line-numbered manuscript content together with anchored `CommentThread`s |
| `dx_list_threads` | Query threads (`only_pending_feedback=true` returns threads awaiting an AI follow-up reply) |
| `dx_add_comment` | Anchor a new `CommentThread` onto an `anchor_quote` with multi-version candidates (`v1a`, `v1b`, `v1c`) |
| `dx_reply_comment` | Stack revised AI candidates (`v2a`, `v2b`) onto an existing `thread_id` in response to author feedback |
| `dx_apply_candidate` | Write a chosen candidate (`v1a` or candidate ID) into the manuscript while keeping the thread anchored |
| `dx_manage_thread` | `resolve`, `reopen`, `revert` (restore original baseline quote), or `delete` a thread |
| `dx_get_redline_diff` | Return unified diff against the initial baseline snapshot |
---
## 4. Development & Tests
```bash
python3 -m unittest discover -s tests -v
```
## License
MIT © [soul667](https://github.com/soul667)