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

Copyworks runs its MCP server on desktop (Windows, macOS, Linux) at http://127.0.0.1:8889/mcp, using the Streamable HTTP transport. Every request needs a bearer token, which the app keeps in ~/.loqu8/mcp-token; a request without it is refused.

The easy way: Connect AI

In Copyworks, open the ⋮ menu and choose Connect AI. It finds the AI clients on your computer (Claude Code, Cursor, VS Code Copilot, Windsurf, Claude Desktop, Zed, Gemini CLI and others) and writes the address and token into each one. If a client shows Needs update, press Update beside it.

By hand

Give your client the address and an Authorization header. For Claude Code:

claude mcp add --transport http copyworks http://127.0.0.1:8889/mcp \
  --header "Authorization: Bearer $(cat ~/.loqu8/mcp-token)" --scope user

For clients configured with JSON:

{
  "mcpServers": {
    "copyworks": {
      "type": "http",
      "url": "http://127.0.0.1:8889/mcp",
      "headers": { "Authorization": "Bearer <contents of ~/.loqu8/mcp-token>" }
    }
  }
}

On a sandboxed Mac build the token is in ~/Library/Containers/com.loqu8.copyworks/Data/.loqu8/mcp-token.

Available Tools

Tool	Purpose	Read-only?
app_state	Current text, characters, config, active tab, plan and version	Yes
set_text	Set the Chinese text for the worksheet	No
set_config	Change grid, annotations, paper size, tab, game and title	No
list_lessons	Browse the content library	Yes
load_lesson	Load a lesson onto the worksheet	No
select_characters	Include or exclude characters, or select all or none	No
export_pdf	Make a PDF of the active tab and return its path	No
get_barcode_payload	What the worksheet’s barcode encodes	Yes
open_about	Open the About dialog (version and usage-data switch)	No

Every Loqu8 app also answers the shared tools: screenshot, desktop_screenshot, tap, list_loqu8_apps, show_window, hide_window, set_window_size, window_bounds, usage_data, models, models_repair and quit. screenshot and tap work only when the person has turned on Let AI agents capture this window in Settings → Privacy.

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

Config Reference

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

Field	Values
gridType	miZiGe, tianZiGe, huiGongGe, none
columns	3–20
rowsPerBlock	1–10
showPinyin, showBopomofo, showDefinition	true/false
showJyutping	true/false (Cantonese Jyutping)
showYale	true/false (Cantonese Yale)
showPoj	true/false (Hokkien POJ)
showToneNumbers	true/false (ma3 instead of mǎ)
characterMode	solid, outline
useToneColors	true/false
characterVariant	asEntered, simplified, traditional
isLeftHanded	true/false
title	any string
tab	copysheets, flashTiles, slides, games
gameType	coloring, sudoku, memoryMatch, wordSearch, ticTacToe, bingo
bingoCardCount	1–10
flashCols	2–9
showBack	true/false (the back or answer side)
paperSize	letter, a4, legal
language	any of the 26 language codes, such as en, es or ja
fontFamily	a font name, such as AR PL UKai CN
theme	light, dark, system

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