duet-mcp

English | 日本語

One shared state for humans through a GUI and LLMs through MCP. Define each operation once.

Start a project

Requires Node.js 22+.

npx --package=duet-mcp duet init my-app
cd my-app && npm install
npm run dev

Open the URL printed by Vite. Edit text or drag the box; the shared state updates for connected clients. duet init creates the template, build configuration, dependencies, and scripts in an empty directory.

Read template/app.ts for shared state and operations, then template/ui/main.tsx for the screen. Add an action in app.ts and call it from the GUI. Keep the template's rootDir/webDist settings when editing it.

Related MCP server: Express REST API and MCP Server Framework

Define an action once

import { defineApp, createAction } from "duet-mcp";
import { appInfo, awaitChange, observerOps } from "duet-mcp/assets";
import { z } from "zod";

type Doc = { text: string };
const action = createAction<Doc>();

export const app = defineApp({
  id: "notes",
  version: "1.0.0",
  initialDoc: (): Doc => ({ text: "" }),
  actions: {
    set_text: action({
      description: "Replace the shared text.",
      input: z.object({ text: z.string() }),
      handler: ({ doc }, { text }) => {
        doc.update(state => { state.text = text; });
        return { text };
      },
    }),
    url: appInfo().url,
    await_change: awaitChange(),
    ...observerOps(),
  },
});

The handler's document, input, and result are typed. Custom actions and built-in actions share the same actions object.

In the GUI, import useDoc from ../duet/browser, call const doc = useDoc(), and handle the initial null. Then call await doc.set_text({ text: "hello" }). A Node caller imports getDoc from ./duet/node and calls await getDoc() first. MCP takes the same { text: "hello" } input.

Keep drafts in React useState / useRef. Clear a draft only after its action succeeds; use the value calculated in the release handler when submitting a drag.

Connect an MCP client

Run npm run build, then configure your MCP client to launch node with the absolute path to dist/template/main.js. The template provides GUI URL, observation, screenshot, blob, and undo/redo actions. Screenshots automatically use installed Chrome, Edge, then Playwright Chromium. If none is installed, run npx playwright install chromium. Use renderScreenshot({ channel: "chromium", timeoutMs: 10_000 }) to select a browser and per-step capture timeout.

Use npm run typecheck to check your app. Generated template/duet/browser.ts, node.ts, and connection.ts need no manual editing.

State lives in memory; your application owns persistence. For update behavior, observation and guarded edits, assets, and takeover, see doc/SEMANTICS.md.