Codeprint

Codeprint turns code, Markdown, JSON, and CSV into readable, paginated PDFs. The same document engine powers the web app, a local CLI, and an MCP server for agents.

Document rendering happens locally. Direct printer submission is available only through the CLI and MCP packages, and every print job has an explicit preparation and confirmation boundary.

Table of contents

• Products

• Key features

• Architecture

• Prerequisites

• Getting started

• CLI

• MCP server

• Direct printing

• Development commands

• Testing

• Deployment and publishing

• Troubleshooting

• License

Related MCP server: pdf-it

Products

Key features

• Print-ready PDFs for Markdown, code, JSON, and CSV

• Shared PDF implementation across web, CLI, and MCP

• Syntax highlighting for the supported programming languages

• Markdown headings, lists, tables, links, code blocks, and optional table of contents

• Print-safe Mermaid diagrams inside Markdown. Flowchart, state, sequence, class, and ER diagrams render at 300 PPI; unsupported families preserve their source with a warning

• CSV headers and alternating row colors

• A4, Letter, and Legal paper in portrait or landscape

• Local printer discovery through CUPS on macOS and Linux

• Two-step printing with short-lived, single-use confirmation tokens

• Local-only document handling with no Codeprint upload service

Architecture

apps/web ───────────────────────────────┐
                                       ├──> packages/core
packages/cli ───────┬──> packages/print│
                    └───────────────────┤
packages/mcp ───────┬──> packages/print│
                    └───────────────────┘

Directory structure

codeprint/
├── apps/
│   └── web/                  Next.js application
├── packages/
│   ├── core/                 Document types and PDF rendering
│   ├── print/                Native print adapters and confirmation service
│   ├── cli/                  `codeprint` executable
│   └── mcp/                  `codeprint-mcp` executable
├── CONTRIBUTING.md           Contributor workflow and quality gates
├── SECURITY.md               Private vulnerability reporting policy
├── THIRD_PARTY_NOTICES.md    Bundled dependency and asset notices
├── biome.json                Workspace formatting and linting
├── tsconfig.base.json        Shared TypeScript settings
└── package.json              npm workspace orchestration

Document flow

1. A surface normalizes the source, filename, format, and paper settings.

2. @codeprint/core creates the React PDF document and final PDF bytes.

3. The web app downloads those bytes or opens the browser print flow.

4. The CLI and MCP server can write the PDF locally.

5. If physical printing is requested, @codeprint/print validates the PDF and printer capabilities before creating a confirmation token.

6. A separate submission consumes the token and sends the PDF to the operating system spooler.

Printer integrations do not live in core. This keeps the document engine portable and prevents native Node dependencies from entering the web application.

Prerequisites

• Node.js 22.12 or newer

• npm 10 or newer

• For direct printing on macOS or Linux: CUPS commands lpstat, lpoptions, lp, and cancel

Windows can render PDFs today, but direct printer submission is not implemented yet. Print the generated PDF through the system viewer on Windows.

Getting started

Install all workspace dependencies from the repository root:

npm install

Start the web application:

npm run dev

Open http://localhost:3000.

Build every package and the production web application:

npm run build

CLI

Run the CLI from the repository:

npm run cli -- --help

Run the published CLI without a permanent install:

npx @codeprint/cli render README.md

Render documents

codeprint render README.md
codeprint render report.csv --page-size letter --orientation landscape
codeprint render payload.json --output ./printouts
codeprint render source.ts --language typescript --no-line-numbers
cat notes.md | codeprint render - --format markdown --filename notes.md

The CLI infers Markdown, CSV, JSON, and programming languages from file extensions. JSON uses the code renderer with JSON syntax highlighting. Markdown Mermaid fences render flowchart, state, sequence, class, and ER diagrams. Other Mermaid families remain readable as source code and include a concise warning. There is no dedicated Mermaid route yet.

An existing output file is never replaced unless --force is supplied.

Print documents

codeprint printers
codeprint printer-info "Office_Printer"
codeprint print README.md --printer "Office_Printer" --duplex two-sided-long-edge
codeprint print report.pdf --copies 2 --page-ranges 1-3,7
codeprint jobs
codeprint cancel Office_Printer-42

codeprint print displays the resolved printer, copies, paper, duplex, color, and page range before asking for confirmation. Automation may pass --yes, but callers should display and approve the settings first.

Use --json for machine-readable output:

codeprint --json printers
codeprint --json render README.md --output ./out

See packages/cli/README.md for the full option reference.

MCP server

Run the server over stdio:

npm run mcp:start

An MCP client can launch the published package with:

{
  "mcpServers": {
    "codeprint": {
      "command": "npx",
      "args": ["-y", "@codeprint/mcp"],
      "env": {
        "CODEPRINT_OUTPUT_DIR": "/absolute/path/to/Codeprint"
      }
    }
  }
}

Available tools:

The MCP instructions require explicit user approval between prepare_print_job and submit_print_job. A token expires after five minutes and cannot be reused.

See packages/mcp/README.md for examples and client configuration.

Importing public files by URL

The website's Import URL control loads a public GitHub file link or a direct HTTPS text-file URL. Review the fetched file before replacing editor content. Codeprint offers the matching code, Markdown, or CSV editor when needed. The cross-editor handoff uses one-shot tab-local session storage with a one-minute expiry, not URL parameters. No import happens just by visiting a link.

Browser imports contact the source host directly with no cookies or referrer; there is no Codeprint fetch proxy. Hosts that block CORS or redirect require a public Raw link or a download-and-upload fallback. A browser cannot inspect DNS answers; the website rejects literal private addresses and local hostnames, and browser network/security policies still apply to other hosts.

The CLI supports codeprint render --url 'https://github.com/itsyogesh/codeprint/blob/main/README.md'. MCP exposes create_pdf_from_url. Both fetch locally using connection-time DNS validation, reject private/special-use IPs and redirects, and never forward authentication. All surfaces cap imports at 2 MiB and 15 seconds, require UTF-8 text, and do not execute it. PDF generation stays on the user's device. Imports do not bypass the normal physical-printing approval flow. Private repositories, whole repositories, arbitrary web-page extraction, and authenticated URLs are outside this release.

Direct printing

The first print adapter targets CUPS on macOS and Linux. It calls native commands with argument arrays and never invokes a shell, so printer names and file paths are not evaluated as commands.

The print service validates:

• The source exists and begins with a PDF file signature

• The requested printer exists

• Copies are between 1 and 99

• Page ranges contain positive, ascending ranges

• Requested paper, duplex, and color modes are reported by the printer when capability data is available

Preparing a job does not print. Submission requires the returned single-use token.

Environment variables

The web app does not require environment variables for document rendering. Copy apps/web/.env.example to apps/web/.env.local only when you need to preview the developer-tool launch state.

Development commands

Testing

Run all tests once:

npm run test:run

Run the MCP integration smoke test:

npm run mcp:smoke

The print unit tests use a fake backend. They do not submit jobs to a physical printer. The MCP smoke test also uses a fake printer and a temporary output directory.

For a complete verification pass:

npm run release:check

Deployment and publishing

The web app in apps/web is a standard Next.js application and can be deployed to Vercel. Configure the project root as the repository root and use npm run build; the workspace build compiles shared packages before Next.js.

The public packages belong to the @codeprint npm organization. Releases publish in dependency order: core, print, CLI, then MCP.

Before every release:

1. Update the package versions and exact internal dependency versions together.

2. Run npm run release:check on Node.js 22 and 24.

3. Confirm the release commit is on the protected default branch of itsyogesh/codeprint.

4. Confirm the public history contains no private prompts, research, credentials, generated documents, or personal files.

5. Verify the deployed source link resolves to the exact public release.

Each package uses a GitHub Actions trusted publisher on npm:

• Repository owner: itsyogesh

• Repository: codeprint

• Workflow: publish-packages.yml

• Environment: npm

• Allowed action: npm publish

The manual Publish npm packages workflow then verifies and publishes all four packages without a stored npm token. No package is published by the normal build scripts.

Troubleshooting

lpstat is not installed or is not available on PATH

Install or enable CUPS. macOS normally includes the required commands. On Debian or Ubuntu, install the CUPS client tools:

sudo apt-get install cups-client

No printers are configured

Verify the operating system can see a printer:

lpstat -p -d

Add the printer through system settings or CUPS, then retry codeprint printers.

Requested capability is rejected

Inspect the printer-reported options:

codeprint printer-info "Printer_ID"

Printer IDs can differ from display names and commonly replace spaces with underscores.

Output file already exists

Choose another output path or explicitly allow replacement:

codeprint render README.md --output README-print.pdf --force

CJK, Arabic, Indic, or complex emoji text is not rendered correctly

The first release embeds fonts for exact Latin and Cyrillic output. Locale-specific CJK packs, right-to-left Arabic extraction, Indic extraction, and joined emoji sequences are not supported yet. Do not distribute a PDF containing those scripts without inspecting both the rendered pages and copied text. The public roadmap tracks the language-pack work; Codeprint will not claim support until visual and text-extraction fixtures both pass.

MCP client cannot find the executable

Use an absolute Node or npx path in the client configuration, or install @codeprint/mcp globally.

Privacy

Codeprint does not need a document API. The web app renders in the browser. The CLI and MCP server render on the local computer. Direct printing sends the PDF only to the configured operating-system print service or printer.

License

Codeprint's original source is open source under GNU AGPL version 3 only, identified as AGPL-3.0-only. Personal and commercial use are allowed. Distribution and network use of modified covered versions must follow the source-availability and copyleft conditions in the license. Copyright 2026 Yogesh Kumar.

PDFs created from your own material are not placed under the AGPL merely because Codeprint generated them. Read Open source and sustainability for the plain-language project decision, future business model, and trademark boundary.

See CONTRIBUTING.md before submitting changes, SECURITY.md for private vulnerability reporting, and THIRD_PARTY_NOTICES.md for licenses that apply to bundled dependencies, fonts, and externally served icons.

The Codeprint name and logo are not granted for use by the AGPL.