Doodleworks MCP

在项目中创建 .cursor/mcp.json（或者创建 ~/.cursor/mcp.json 以用于所有项目）：

{
  "mcpServers": {
    "doodleworks-mcp": {
      "command": "npx",
      "args": ["-y", "doodleworks-mcp"],
      "env": { "OPENAI_API_KEY": "${env:OPENAI_API_KEY}" }
    }
  }
}

然后打开 Cursor Settings → Tools & Integrations，确认 doodleworks 已启用，并在 Agent 聊天中调用它。使用 ${env:OPENAI_API_KEY} 可将密钥保留在文件之外（在 shell 中设置）；也可以直接粘贴 sk-...。内嵌查看器要求 Cursor 2.6+；旧版本可以运行工具，但不会渲染查看器。

VS Code 使用 servers 键（而不是 mcpServers），并可安全地提示输入密钥。创建 .vscode/mcp.json：

{
  "inputs": [
    { "type": "promptString", "id": "openai-api-key", "description": "OpenAI API key", "password": true }
  ],
  "servers": {
    "doodleworks-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "doodleworks-mcp"],
      "env": { "OPENAI_API_KEY": "${input:openai-api-key}" }
    }
  }
}

点击服务器条目上方的 Start（或运行 MCP: List Servers），并在提示时输入密钥，然后打开 Copilot Chat → Agent mode 并调用工具。查看器会内嵌渲染。要求 VS Code 1.109+（MCP Apps 处于预览阶段）。

Goose 使用 YAML。编辑 ~/.config/goose/config.yaml（Windows：%APPDATA%\Block\goose\config\config.yaml）：

extensions:
  doodleworks-mcp:
    type: stdio
    name: doodleworks-mcp
    enabled: true
    cmd: npx
    args: ["-y", "doodleworks-mcp"]
    envs:
      OPENAI_API_KEY: "sk-..."
    timeout: 300

也可以使用界面：Sidebar → Extensions → Add custom extension（Type：Standard IO；粘贴 npx -y doodleworks-mcp；添加密钥）。添加后重启 Goose。查看器仅支持 桌面版，MCP Apps 支持仍处于实验阶段。

打开 Settings → Developer → Edit Config（或在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，在 Windows 上编辑 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "doodleworks-mcp": {
      "command": "npx",
      "args": ["-y", "doodleworks-mcp"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

保存后，完全退出并重新启动 Claude Desktop（按 Cmd+Q，而不只是关闭窗口），查看器便会在聊天中内嵌渲染。（如果较旧版本只显示文本备用内容，而不显示画廊，请更新 Claude Desktop。）

claude mcp add --scope project --transport stdio --env OPENAI_API_KEY=sk-... \
  doodleworks -- npx -y doodleworks-mcp

（或者提交一个包含顶层 mcpServers 块的项目 .mcp.json。）终端没有 webview，因此交互式查看器无法在此渲染：你会看到工具输出，而不是画廊。请使用图形界面宿主查看器。

编辑 ~/.codeium/windsurf/mcp_config.json（Windows：%USERPROFILE%\.codeium\windsurf\mcp_config.json；如果文件不存在，请创建）：

{
  "mcpServers": {
    "doodleworks-mcp": {
      "command": "npx",
      "args": ["-y", "doodleworks-mcp"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

在 Cascade MCP 面板中点击 Refresh（或重启 Windsurf）。Windsurf 可以运行工具，但不会渲染 MCP Apps UI，因此查看器不会内嵌显示。

最可靠的查看方式是通过 Streamable HTTP 搭配开发宿主（从克隆的仓库中运行）：

pnpm start    # watch-build the viewer + serve on http://localhost:3001/mcp

将 MCP Apps basic-host 或 MCPJam inspector 指向 http://localhost:3001/mcp。两者都能正确渲染查看器，也是开发和验证画廊的推荐方式。

• plan_illustrations （提示词） 将主题转化为一组可直接渲染的内容。参数：topic（必填）、audience?、count?、spine?（teaching | persuasion | report | product | knowledge-card）。
• create_illustrations 渲染整组插画（1–10 幅，每幅都需要付费渲染），并打开查看器。每个 prompt 都包含一个装置 + Tinku 的动作 + Required text only: 区块；服务会自动添加角色、概念引擎和整体风格。
• regenerate_illustration 重新渲染一幅图（对应查看器中的 Regenerate 按钮）。
• get_illustration 将每幅渲染后的图像流式传输到查看器中（仅限应用；模型无法看到图像）。

请参阅 examples/ 中可直接运行的载荷（net-ai-stack.json、keep-cool-in-hot-weather.json、tinku-contraptions.json）。规划文档以 doc://doodleworks/* 资源的形式提供，因此任何宿主都能访问，无需单独安装技能。

介绍替尔泊肽（一种 GLP‑1/GIP 药物）的作用原理，从首次注射到用药剂量和副作用，将一份内容繁杂的药品说明书转化为 9 幅通俗易懂的图片。这些是绘画风格示例，并非医疗建议。

一目了然：每周注射一次，用于治疗 2 型糖尿病和减重。

减重：降低食欲，让你更有饱腹感、吃得更少。

错过一次用药：像切换轨道一样：≤4 天，立即注射；超过 4 天，则跳过。

严重症状：出现这些警示信号时，意味着需要寻求帮助。

介绍尼古丁为何并非有害成分、尼古丁替代疗法有哪些形式，以及它如何稳定地缓解烟瘾。

误区与危害：尼古丁并非毒物；焦油和毒素才是。

疗法形式：贴片、口香糖、含片、喷雾剂、吸入器。

抑制烟瘾：让刻度保持稳定。

将杂乱的来源整理成互相关联、由模型维护的维基：无需复杂的 RAG，即可实现问答。

更少代码，更多知识：将原始资料加工成整洁的 Wiki。

自我维护：模型负责整理，无需人工介入。

持续积累：输出会随着时间不断累积。

.NET AI 库详解：艰难的起步阶段、支撑众多接口的统一基础，以及能够调用工具的 Agent。

艰难的起步：手工编写，脆弱易错，约 200 行。

统一基础：一个插座面板提供多种接口。

配备工具的 Agent：机器人从挂板上挑选工具。

MCP App 由一个工具和一个 UI 资源组成。create_illustrations 会生成插画，并通过 _meta.ui.resourceUri 注册，因此宿主会获取 ui://doodleworks-mcp/viewer.html 资源，并在沙盒 iframe 中渲染。

为保持上下文整洁，并符合 MCP 单个结果的大小上限，工具结果中不包含任何图像字节：结果只携带一个 setId 和插画元数据。服务端会在小型进程内 LRU 缓存中保留刚生成的图像（最近 8 组），查看器则通过单独的 get_illustration 调用获取每张图像（每个结果一张图像）。渲染在后台进行，因此调用会立即返回，图像完成后便会流入查看器。

host LLM ── create_illustrations(illustrations[]) ─▶ server: render × N  (OpenAI / Gemini, your key)
   model sees: 1-line summary ◀── content (no bytes)         cache.set(setId, …)
   viewer sees: { setId, metadata } ◀── _meta["doodleworks/set"]
   viewer ── get_illustration({ setId, index }) ─▶ one image per result ─▶ iframe gallery

由于图像只存在于进程内缓存中，因此仅在服务进程运行期间有效（且只保留最近 8 组）。这是此个人版有意做出的取舍：无需任何基础设施，也没有密钥处理方面的责任。若要持久保存图像或与其他用户共享，就该转向托管版了。

assets/style-references/ 是一个可扩展的库：放入 .png/.jpg/.webp/.gif 文件后，即可立即将其用作风格参考（它只校准绘画风格，不会影响角色或文本）。可为每张插画单独设置、对整组插画统一设置，或通过 DOODLEWORKS_STYLE_REF 设置。完整图库及工作原理请参阅图库 README。

Tinku 是应用自带的角色，在 engine.ts 中通过 TINKU_CHARACTER 定义一次：一个小巧、纯黑的蛋形工人，长着一双大眼睛和连指手套般的手，总是在操作那台装置。编辑该常量即可为其更换风格（并通过 pnpm run check:tinku 同步更新 references/visual-dna.md，该检查由构建流程强制执行）。