Loqu8

MCP Server

Drive Copyworks from AI assistants via Model Context Protocol.

What is MCP?

MCP (Model Context Protocol) is an open protocol that lets AI assistants interact with external tools. Copyworks exposes its entire functionality as MCP tools, so you can say things like:

• “Make me HSK Level 1 worksheets with tone colors”
• “Load the Tang poem 静夜思 and export a PDF”
• “Create flash cards for my daughter’s name characters”

The AI assistant handles the details — loading content, configuring the worksheet, and exporting the result.

Setup

The MCP server starts automatically on desktop (Windows, macOS, Linux) at http://localhost:7420/mcp.

Claude Code

claude mcp add --transport http copyworks http://localhost:7420/mcp --scope user

Or add to ~/.claude.json:

{
  "mcpServers": {
    "copyworks": {
      "type": "http",
      "url": "http://localhost:7420/mcp"
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "copyworks": {
      "url": "http://localhost:7420/mcp"
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "copyworks": {
        "type": "http",
        "url": "http://localhost:7420/mcp"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "copyworks": {
      "url": "http://localhost:7420/mcp"
    }
  }
}

Other Clients

Any MCP client that supports HTTP transport can connect to http://localhost:7420/mcp. The server uses the Streamable HTTP transport (MCP spec 2025-03-26).

Available Tools

Tool	Purpose	Read-only?
app_state	Get current text, characters, config, tier, version	Yes
set_text	Set Chinese text for the worksheet	No
set_config	Change grid, annotations, paper size, tab, title	No
list_lessons	Browse the content library tree	Yes
load_lesson	Load a lesson onto the worksheet	No
select_characters	Include/exclude specific characters	No
export_pdf	Generate a printable PDF	No
screenshot	Capture the live app window as PNG	No

Quick Start

1. app_state          → see what's on screen
2. set_text / load_lesson → set content
3. set_config         → adjust format
4. export_pdf         → generate PDF
5. screenshot         → capture preview

Config Reference

All fields in set_config are optional — pass only what you want to change.

Field	Values	Default
gridType	miZiGe, tianZiGe, huiGongGe, none	miZiGe
columns	3–20	12
rowsPerBlock	1–10	1
showPinyin	true/false	true
showBopomofo	true/false	false
showDefinition	true/false	true
characterMode	solid, outline, toneColor	solid
characterVariant	asEntered, simplified, traditional	asEntered
isLeftHanded	true/false	false
title	any string	“”
tab	copysheets, flashTiles, slides	copysheets
paperSize	letter, a4, legal	letter
flashCols	2–9	4

Entitlement Gating

The MCP server respects the same tier gates as the UI. Free tier users can use all tools, but gated features return a structured upgrade message that the AI assistant can relay naturally, including what the user was trying to do, what the Family plan unlocks, and a checkout link.

Example Workflow

User says: “I need practice worksheets for my daughter learning HSK Level 1.”

Agent does:

1. list_lessons → finds HSK: Level 1 with 19 lessons
2. load_lesson(category: "HSK: Level 1", number: "1") → loads first lesson (8 chars)
3. set_config(showPinyin: true, showDefinition: true, rowsPerBlock: 2) → adds practice rows
4. screenshot → shows the user what it looks like
5. export_pdf → generates the printable PDF
6. Repeats for lessons 2–19

The entire HSK Level 1 curriculum as printable worksheets, generated in seconds.

File Locations

What	Path
Screenshots	~/Pictures/Copyworks/screenshots/
PDF exports (via MCP)	~/Documents/Copyworks/
App data	~/.loqu8/data/
Saved worksheets	User-chosen via file picker