Motif

io.github.sleepycobaltPublished by GitHub account sleepycobaltv0.5.0Updated Oct 24, 2026

Research synthesis with receipts: cited, critic-checked insights from interview transcripts.

VerifiedSTDIODesktop onlyKnowledge & MemoryData & AnalyticsMedia & Design

Overview

AI-generated overview

Motif synthesizes cited, critic-checked insights from interview transcripts, with receipts to verify each citation.

What you can do
Motif exposes five tools: motif_synthesize turns a transcripts directory or file list plus a question into insights JSON, a markdown report, contested insight ids, and a cost figure; motif_critique checks insights or a prose document against rules and returns a verdict; motif_receipts returns verbatim turn text, speaker, and whether the speaker was the interviewer; motif_board produces FigJam layout JSON and use_figma scripts; motif_runs_get retrieves run metadata, notes, and per-iteration verdicts. Every tool is a thin call into a shared synthesis engine, so results match the CLI and FigJam plugin. Failures such as a missing verdict or unknown run id return tool errors rather than empty…
When to use it
Use it when a designer or researcher working in an agent host wants to synthesize interview transcripts into cited, critic-checked insights and then verify citations or push results to a FigJam board. It suits qualitative research workflows where traceability of each claim matters.
Requirements
Local process over stdio, desktop only. Needs Python 3.10+ and the etot-motif[mcp] package (pip install, or uvx --from "etot-motif[mcp]" motif-mcp), or a checkout installed with pip install -e ".[mcp]". Requires ANTHROPIC_API_KEY in the environment or a .env file. Hosts need the absolute path to the motif-mcp entry point. Run logs go to ~/.motif/runs or runs/, overridable with MOTIF_RUNS_DIR. A remote mode exists via MOTIF_REMOTE_URL.
Before you install
ANTHROPIC_API_KEY is required and is used to run the engine locally; in remote mode it is forwarded with each job and used for that job only. Run logs record every prompt, response, and iteration, so transcripts and model output are written to disk under MOTIF_RUNS_DIR. Synthesis and critique spend Anthropic API budget; the acceptance script also spends API budget. motif_board only returns layout and scripts and does not touch Figma itself; the host executes them through Figma's MCP server…

Installation

In SourceWeft

  1. Open Motif in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Motif MCP server

One server, usable from Claude Code, Cursor, Claude Desktop, and any MCP host. A designer or researcher working in an agent environment can say "synthesise these transcripts" and get the same cited, critic-checked result the CLI gives. Every tool is a thin call into synth/engine.py; the loop, prompts, and config are shared with the CLI and the FigJam plugin, never duplicated.

Tools

ToolInOut
motif_synthesizetranscripts_dir or files, question, condition (A/B/C), max_iterationsrun id, insights JSON, report markdown, contested insight ids, cost
motif_critiqueinsights (JSON) or document (markdown/prose); run_id or transcripts_dir; optional transcripts, questionverdict JSON (pass, failures, notes, skipped_rules), summary by rule and by insight, the structured insights, its own run id
motif_receiptsturn_ids; run_id or transcripts_dirverbatim turn text, speaker, whether the speaker was the interviewer; missing
motif_boardrun_id, columns, origin_x, origin_yFigJam layout JSON + one use_figma script per insight for the host to execute through Figma's MCP server
motif_runs_getrun_id, includemeta, notes, per-iteration verdicts; optionally insights, report, per-call token/timing

Failure semantics: a missing verdict, an empty synthesis, an unparseable document, a run that does not exist, or turn ids none of which exist all return an MCP tool error. There is no empty success.

Progress: every engine progress line (each transcript ingested, each model call, each critic iteration) is sent twice: as an MCP log notification, which a host only receives if it has set a logging level, and as a progress notification, which a host receives if it passed a progress token (Claude Code does). stdout is the protocol; nothing else ever writes to it.

Install (local mode)

From PyPI, into any Python 3.10+ environment:

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

Or with no install step, if you have uv: the command is uvx --from "etot-motif[mcp]" motif-mcp. Installed this way the server uses the packaged config and writes run logs to ~/.motif/runs (override with MOTIF_RUNS_DIR).

From a Motif checkout:

bash
git clone https://github.com/sleepycobalt/motif.gitcd motifpython3 -m venv .venv && source .venv/bin/activatepip install -e ".[mcp]"echo "ANTHROPIC_API_KEY=your-key-here" > .envls .venv/bin/motif-mcp        # the server entry point

The server reads ANTHROPIC_API_KEY from the environment or the repo's .env, writes run logs to runs/ in the repo (override with MOTIF_RUNS_DIR), and uses config/synth.yaml, a symlink to the packaged synth/synth.yaml (override with MOTIF_CONFIG). Every host below needs the absolute path to .venv/bin/motif-mcp; hosts spawn servers without your shell's PATH.

Claude Code

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

Optionally install the skill so Claude Code knows the workflow (verify citations with receipts, mind contested insights, push to FigJam):

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

Then in a new Claude Code session:

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

Claude Code calls motif_synthesize, streams the engine's progress, and can then call motif_receipts to verify any citation or motif_board to push the run onto a FigJam board via Figma's MCP server.

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

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

Restart Cursor; the five motif_* tools appear under MCP tools.

Claude Desktop

Open the config file (Claude menu → Settings → Developer → Edit Config), or edit it directly:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
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"      }    }  }}

Quit and reopen Claude Desktop; the tools appear under the tools icon in the chat box. Claude Desktop cannot open files on your disk, so ask for the report markdown in the reply, or read it from the run directory.

Remote mode

Set MOTIF_REMOTE_URL and the same five tools forward to the hosted Motif service (surfaces/hosted/) instead of running the engine locally: no Python dependencies beyond the server itself, and the same results. Your ANTHROPIC_API_KEY is forwarded with each job and used for that job only. In remote mode a tool's run_id is the hosted job id, valid for an hour after the job finishes; motif_receipts, motif_board, and motif_runs_get take it. The hosted engine runs with the logger's redact=True: prompt and response bodies are stored as length + SHA-256, corpora are never snapshotted, and the job's uploads are deleted at expiry. MOTIF_REMOTE_TOKEN selects the paid tier, which is not switched on yet.

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

Board output through Figma's MCP server

motif_board returns a layout and scripts; it does not touch Figma. The host (Claude Code with Figma's MCP server authenticated) runs each script with use_figma against a FigJam board URL and reads the result back with get_figjam. Verified on a real board on 2026-09-04 (docs/exhibits/step-zero/, docs/exhibits/board-r5/).

Listing

listing.md holds the descriptions for directories that index MCP servers; server.json is the manifest for the official MCP registry (publish after the package is on PyPI).

Tests

bash
.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

Source: surfaces/mcp/README.md at commit 3aa944a

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.5.0LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.