motif

Motif MCP 服务

一个服务，可供 Claude Code、Cursor、Claude Desktop 及任何 MCP 主机使用。 在 Agent 环境中工作的设计师或研究人员可以说“综合这些访谈记录”，并获得与 CLI 相同的、附有引用且经过批判检查的结果。每个工具都是对 synth/engine.py 的轻量调用；循环、提示词和配置与 CLI 及 FigJam 插件共用，绝不重复实现。

工具

工具	输入	输出
motif_synthesize	transcripts_dir 或 files、question、condition（A/B/C）、max_iterations	运行 ID、insights JSON、报告 Markdown、存在争议的 insight ID、费用
motif_critique	insights（JSON）或 document（Markdown/散文）；run_id 或 transcripts_dir；可选的 transcripts、question	verdict JSON（pass、failures、notes、skipped_rules）、按规则和按 insight 汇总的结果、结构化 insights、自身的运行 ID
motif_receipts	turn_ids；run_id 或 transcripts_dir	逐字显示的轮次文本、说话者、说话者是否为访谈者；missing
motif_board	run_id、columns、origin_x、origin_y	FigJam 布局 JSON，以及每个 insight 对应的一个 use_figma 脚本，供主机通过 Figma 的 MCP 服务执行
motif_runs_get	run_id、include	meta、备注、每轮 verdict；可选的 insights、报告、每次调用的 token/耗时

失败语义：缺少 verdict、综合结果为空、文档无法解析、运行不存在，或所有轮次 ID 均不存在时，都会返回 MCP 工具错误。不会出现空的成功结果。

进度：每一条引擎进度行（每份访谈记录的载入、每次模型调用、每轮批判迭代）都会发送两次：作为 MCP 日志通知发送；主机只有设置了日志级别才会收到此通知。另一次作为进度通知发送；主机传入进度令牌时才会收到此通知（Claude Code 会传入）。stdout 是协议；除此之外，任何内容都不会写入其中。

安装（本地模式）

从 PyPI 安装到任意 Python 3.10+ 环境：

pip install "etot-motif[mcp]"
which motif-mcp                # the server entry point; hosts need this absolute path

如果已安装 uv，也可以不经过安装步骤：命令为 uvx --from "etot-motif[mcp]" motif-mcp。以这种方式运行时，服务会使用打包的配置，并将运行日志写入 ~/.motif/runs（可通过 MOTIF_RUNS_DIR 覆盖）。

从 Motif 检出目录运行：

git clone https://github.com/sleepycobalt/motif.git
cd motif
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[mcp]"
echo "ANTHROPIC_API_KEY=your-key-here" > .env
ls .venv/bin/motif-mcp        # the server entry point

服务会从环境变量或仓库的 .env 读取 ANTHROPIC_API_KEY，将运行日志写入仓库中的 runs/（可通过 MOTIF_RUNS_DIR 覆盖），并使用 config/synth.yaml；它是指向打包文件 synth/synth.yaml 的符号链接（可通过 MOTIF_CONFIG 覆盖）。 以下每种主机都需要 .venv/bin/motif-mcp 的绝对路径；主机启动服务时不会使用 shell 的 PATH。

Claude Code

claude mcp add motif -- /ABSOLUTE/PATH/TO/motif/.venv/bin/motif-mcp

还可以选择安装 skill，让 Claude Code 了解工作流（使用 receipts 验证引用、留意有争议的 insights，并推送到 FigJam）：

mkdir -p ~/.claude/skills/motif
cp /ABSOLUTE/PATH/TO/motif/surfaces/mcp/skills/motif/SKILL.md ~/.claude/skills/motif/SKILL.md

然后在新的 Claude Code 会话中：

/mcp                                   # motif should show as connected
synthesise ./data/raw/Dataset-2 with motif and open the report

Claude Code 会调用 motif_synthesize，流式显示引擎进度，之后可以调用 motif_receipts 验证任意引用，或调用 motif_board，通过 Figma 的 MCP 服务将本次运行推送到 FigJam 白板。

Cursor

添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "motif": {
      "command": "/ABSOLUTE/PATH/TO/motif/.venv/bin/motif-mcp",
      "env": { "ANTHROPIC_API_KEY": "your-key-here" }
    }
  }
}

重启 Cursor；五个 motif_* 工具将显示在 MCP 工具下。

Claude Desktop

打开配置文件（Claude 菜单 → 设置 → 开发者 → 编辑配置），或直接编辑：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "motif": {
      "command": "/ABSOLUTE/PATH/TO/motif/.venv/bin/motif-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "your-key-here",
        "MOTIF_RUNS_DIR": "/ABSOLUTE/PATH/TO/motif/runs"
      }
    }
  }
}

退出并重新打开 Claude Desktop；工具会显示在聊天框的工具图标下。Claude Desktop 无法打开磁盘上的文件，因此请在回复中要求提供报告 Markdown，或从运行目录中读取。

远程模式

设置 MOTIF_REMOTE_URL 后，同样的五个工具会转发到托管的 Motif 服务（surfaces/hosted/），而不是在本地运行引擎：除服务本身外，无需其他 Python 依赖，结果也相同。每次作业都会转发你的 ANTHROPIC_API_KEY，且仅用于该作业。在远程模式下，工具的 run_id 是托管作业 ID，作业结束后一小时内有效；motif_receipts、motif_board 和 motif_runs_get 均接受该 ID。托管引擎使用日志记录器的 redact=True：提示词和响应正文会以长度 + SHA-256 的形式存储，语料库不会被快照，作业上传的文件会在到期时删除。MOTIF_REMOTE_TOKEN 用于选择付费层级，但目前尚未启用。

claude mcp add motif -e MOTIF_REMOTE_URL=https://motif-hosted.fly.dev -e ANTHROPIC_API_KEY=your-key-here -- motif-mcp

通过 Figma 的 MCP 服务输出画板

motif_board 会返回布局和脚本；它不会操作 Figma。宿主（已通过 Figma 的 MCP 服务完成身份验证的 Claude Code）会针对 FigJam 画板 URL，使用 use_figma 运行每个脚本，并通过 get_figjam 读取结果。已于 2026-09-04 在真实画板上验证（docs/exhibits/step-zero/、docs/exhibits/board-r5/）。

项目目录列表

listing.md 保存 MCP 服务索引目录所需的描述；server.json 是官方 MCP 注册表的清单（在软件包发布到 PyPI 后发布）。

测试

.venv/bin/python -m pytest -q tests               # offline: stubbed model, spawns the server over stdio
.venv/bin/python scripts/critique_acceptance.py   # spends API budget: critic vs eval2 human scoring