Assembly MCP

A small Model Context Protocol server that gives any MCP client (Claude Code, Claude Desktop, …) document-conversion and assembly-app upload tools:

convert_pdftomd and the upload tools run the assembly-app CLIs from self-contained bundles in cli/bin/*.mjs (built by cli/build.mjs), so no assembly-app checkout is needed to use them — just Node ≥ 22. The bundles talk straight to the app's server (Supabase at newapi-next.assembly.nz) as the signed-in person. See Building the CLI bundles. convert_mdtopdf renders Markdown/HTML → PDF with WeasyPrint (pure-Python, no TeX toolchain).

Requirements

• Python ≥ 3.11

• uv (recommended) or pip

• Node ≥ 22 — runs the bundled CLIs in cli/bin/. convert_pdftomd also needs cd cli && npm ci --omit=dev once (pdf.js + the native canvas module).

• An assembly-app checkout is optional: only used when a bundle is missing (falls back to <ASSEMBLY_APP_DIR>/apps/frontend/scripts/<name>.ts) and for env="dev" config (its apps/frontend/.env.local).

• WeasyPrint native libraries — only needed for convert_mdtopdf (convert_pdftomd works without them):

  • Linux (Debian/Ubuntu): apt install libpango-1.0-0 libpangoft2-1.0-0 libgdk-pixbuf-2.0-0 libffi-dev

  • macOS: brew install pango gdk-pixbuf libffi

  • Windows: install the GTK3 runtime. Without it, convert_pdftomd still works and convert_mdtopdf returns a clear "install GTK" error.

Related MCP server: Markdown2PDF MCP Server

Install

git clone https://github.com/AssemblyJustin/assembly-mcp.git
cd assembly-mcp
uv sync            # creates .venv and installs everything

Run the server directly to confirm it starts (it speaks MCP over stdio and will wait for a client — Ctrl-C to exit):

uv run assembly-mcp

Add to Claude Code

From anywhere, register the server (adjust the path to your clone):

claude mcp add assembly -- uv --directory /ABSOLUTE/PATH/TO/assembly-mcp run --no-sync assembly-mcp

(--no-sync: on Windows, a second Claude session's uv run otherwise tries to reinstall the assembly-mcp.exe the first session is running, fails with "file in use", and the server never connects. Run uv sync yourself after pulling.)

Then the tools are available in your session. This repo also ships matching slash commands — run Claude Code from inside the repo (or copy .claude/commands/* into your project) to use:

/convert-pdftomd  report.pdf  report.md
/convert-mdtopdf  notes.md     notes.pdf
/upload issues
/upload renders
/dwgtogeomap

Add to Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and add:

{
  "mcpServers": {
    "assembly": {
      "command": "uv",
      "args": ["--directory", "C:\\ABSOLUTE\\PATH\\TO\\assembly-mcp", "run", "--no-sync", "assembly-mcp"]
    }
  }
}

Restart Claude Desktop. The tools appear under the 🔌 tools menu.

Tools

convert_pdftomd

Convert a PDF file to Markdown. PDF→Markdown runs the assembly-app pdf2md converter (pdf.js) — headings, lists, ruled tables, images (saved to <stem>_images/). Requires node ≥ 22 and cli/ installed (npm ci --omit=dev).

Returns the Markdown text (prefixed with a <!-- pdf2md: … --> summary comment giving page/table/image counts and the output path).

This is a code-only extraction. It does not run vision-based verification, so treat the output as a high-quality first pass, not a certified copy.

convert_mdtopdf

Convert Markdown to a PDF file. Provide either md_path or markdown_text.

Renders Markdown → HTML → PDF with a clean A4 print stylesheet (tables, code blocks, page numbers) and verifies the PDF magic bytes before writing.

upload_issue / issue_draft / upload_renders / dwg_to_geomap

Upload to an assembly-app project as the person doing it. These are thin wrappers over the assembly-app CLIs upload-issues, upload-renders and upload-dwg-geomap, run from the bundles in cli/bin/ (node ≥ 22; no checkout). Each signs in as uploader_email, so the database's own permission rules apply: people can only upload to projects they're on, and viewers and clients can't upload. The slash command /upload issues / /upload renders (.claude/commands/upload.md) drives them; /dwgtogeomap (.claude/commands/dwgtogeomap.md) drives dwg_to_geomap.

uploader_email is optional everywhere: omitted, the tools act as the saved default.

project is the project number (e.g. 2610) or UUID. issue_type is the issue purpose: For Information / Review / Approval / Construction / Tender / Coordination / Record (or an org's own).

Setup (once per machine):

• Login: nothing to do by hand. The first /upload asks for the person's app email + password once and save_login stores them in ~/.assembly/credentials.json ({"_default": "<email>", "<email>": "<password>"}, several people allowed). After that it never asks again. ASSEMBLY_PASSWORD still works for scripted use.

• Prod: set ASSEMBLY_SUPABASE_ANON_KEY to the prod app's public anon key (URL defaults to https://newapi-next.assembly.nz; override with ASSEMBLY_SUPABASE_URL).

• Dev (env="dev"): read from the checkout's apps/frontend/.env.local.

Develop

uv run pytest            # smoke tests (PDF→MD skips without node/assembly-app; MD→PDF skips without GTK)

Project layout:

src/assembly_mcp/
  server.py       FastMCP server — registers the tools (stdio); convert_pdftomd
                  shells out to the assembly-app pdf2md CLI (_app_dir())
  md_to_pdf.py    python-markdown → WeasyPrint rendering
.claude/commands/ /convert-pdftomd, /convert-mdtopdf, /upload and /dwgtogeomap slash commands
tests/            smoke tests

License

MIT — see LICENSE.

Building the CLI bundles

cli/bin/*.mjs are esbuild bundles of the assembly-app operator CLIs (upload-issues, upload-renders, upload-product, upload-dwg-geomap, upload-artifact, upload-panomap, pdf2md). They are built from a private repo, so they are gitignored here (this repo is public) and reach the shared copy on P: through push-to-p.sh. Rebuild after the app's CLIs change (build from main, which is what prod runs):

cd cli
npm ci
ASSEMBLY_APP_DIR=<assembly-app checkout on main> npm run build   # writes bin/*.mjs + bin/SOURCE.json

bin/SOURCE.json records the app commit the bundles came from.