Multica Plugin

Platform priority: ChatGPT desktop is the primary product and acceptance target. Codex CLI compatibility is best effort. Passing MCP protocol tests does not establish that a desktop host displays composer mentions; that interaction must be verified in ChatGPT desktop.

A plugin that brings Multica into ChatGPT desktop — browse issues and their details, explicitly create conversation drafts, and use connected tools to manage tasks, comments, agents and runs.

Built on the OpenAI MCP Extensions template established by the bits-and-bolts reference plugin.

What it does

See 功能与使用场景（中文） for the current capability matrix, example workflows, and implementation limits (v0.1.6).

• Sidebar workbench (global MCP App surface): lists workspace issues in seven lanes: backlog, todo, in_progress, in_review, done, blocked, cancelled.
• Issue details first: clicking a card opens its description, properties, returned root-comment summaries, child issues and linked PRs. Returning keeps the board’s project filter, loaded pages and scroll position.
• Optional conversation: from issue details, enter a question and explicitly create a new conversation draft with task context (send: false). Browsing never sends a message or changes model context. Hosts without the message extension retain the read-only detail view.
• Workspace switching: choose a workspace above the board. The plugin saves the selection in ~/.multica/codex-plugin.json and restores it on the next visit, including after restarting Codex. The first visit uses the CLI-configured workspace. Preferences are scoped by server and credential fingerprint and do not change the CLI default in ~/.multica/config.json. If membership was removed, select an accessible workspace before loading work.
• Project list: the selector beside the workspace lists its projects. Select one to filter every status lane and subsequent pages on the server. Switching workspaces reloads the project list and resets the filter to all projects.
• Workspace agents: a collapsible area shows agent names, models and runtime bindings. Expand a card to inspect its profile; no work is dispatched. Loading failures can be retried without blocking the issue board.
• Copy issue context: copy buttons beside issue identifiers on cards and details copy a scoped snapshot with workspace/project IDs, issue ID, title, state, full description, returned comment excerpts and re-read tool arguments. Paste it into a conversation manually. Clipboard restrictions open a manual copy dialog; copying never sends a message or opens a conversation.
• Full read/write tool set exposed as multica.* MCP tools: list/get/search issues, create/update/move/comment/rerun, list projects/agents/runtimes/members, linked PRs with coarse CI status, and active or historical runs per issue.
• Skill (skills/multica/SKILL.md) teaches the model when to reach for each tool.
• Agent mention provider: exposes searchable, non-archived agents in the selected workspace through openai/mentions. Each selected reference resolves to its original workspace and agent without dispatching work. Composer display depends on host support; Codex composer integration has not been verified. This does not make the external agent a native participant in the Codex chat.

After entering the plugin’s composer search, search for an agent name in the selected workspace, choose the result, then write your request in the main conversation. This search currently returns agents, not issues or projects. The provider accepts both bare-array and wrapped agent-list API responses.

Architecture

Codex sidebar
  → MCP server tool multica.open_workbench (_meta.openai/ui.entrypoints=[{type:"global"}])
  → Codex loads ui://multica/global-v1 (text/html;profile=mcp-app, data-surface="global")
  → app.html renders, App.connect() establishes the bridge
  → React workbench calls app.callServerTool("multica.list_my_work")
  → server/api.ts uses the mul_ PAT to call GET /api/issues
  → JSON → issue cards

The MCP server talks directly to the Multica HTTP API (/api/*), not through the multica CLI. Authentication reuses the user’s mul_ personal access token stored in ~/.multica/config.json (the same profile multica login writes). The /v1/* plugin-bearer surface is intentionally not used — that path is reserved for mpi_/mpc_ plugin-machine tokens and rejects user PATs with plugin_bearer_required.

Auth headers

Every request sends:

Authorization: Bearer 
X-Workspace-ID: 
X-Client-Platform: codex-plugin
X-Client-Version: 0.1.6
X-Client-OS: 
X-Client-Capabilities: stable_attachment_urls

Setup

Prerequisites

• Node.js 22+
• pnpm 11+ (or npm — the package is standalone, no workspace required)
• The multica CLI installed and authenticated (multica login) — the plugin reads ~/.multica/config.json for server_url, workspace_id, and token.

Build

pnpm install   # or: npm install
pnpm build     # or: node ./scripts/build.mjs

Outputs:

• dist/server.js — the stdio MCP server (esbuild bundle)
• dist/app.html — the workbench UI (Vite IIFE inlined)

The committed dist/ is shipped so the plugin runs immediately after clone without a build step. Rebuild after editing source.

Install into Codex

Point Codex at this plugin directory:

codex plugin add "$(pwd)"

Restart Codex; the Multica icon appears in the sidebar.

Dev mode

pnpm build:plugin:dev   # or: node ./scripts/dev.mjs

Watches src/ and rebuilds dist/ on every change (500ms poll fingerprint).

Layout

.
├── .codex-plugin/plugin.json   # manifest + interface (sidebar icon/name/defaultPrompt)
├── .mcp.json                    # { command: "node ./dist/server.js" }
├── package.json                 # deps + scripts
├── tsconfig.json / vite.config.ts
├── scripts/                     # build.mjs (esbuild+Vite), build-app.mjs, dev.mjs
├── assets/icon.svg               # sidebar icons
├── skills/multica/SKILL.md       # teaches the model the tool surface
├── dist/                        # built server.js + app.html (shipped)
└── src/
    ├── shared/contracts.ts      # Zod schemas (Issue/Project/Agent/Run/PR…)
    ├── server/
    │   ├── index.ts             # serveStdio + McpServer entry
    │   ├── register.ts          # UI resources + all multica.* tools
    │   ├── api.ts                # Multica HTTP client (/api/*)
    │   └── auth.ts               # reads ~/.multica/config.json
    └── app/
        ├── index.html           # workbench shell (APP_STYLES/APP_SCRIPT placeholders)
        ├── index.ts             # startApp()
        ├── controller.ts        # App + OpenAIExtensions bootstrap, surface dispatch
        └── workbench.tsx        # issue board React component

Tools

UI entrypoints

• multica.open_workbench — opens the global sidebar workbench
• multica.open_thread_panel — opens the conversation side panel

Reads

multica.list_issues · multica.get_issue · multica.list_my_work · multica.list_projects · multica.get_project · multica.list_agents · multica.list_runtimes · multica.get_active_runs · multica.get_linked_prs · multica.list_members

multica.list_workspaces lists accessible workspaces and the plugin’s selected workspace_id (null if unavailable). multica.switch_workspace validates and persists a selection for all subsequent plugin tools.

Writes (status changes have server side effects — read status_category)

multica.create_issue · multica.update_issue · multica.move_issue · multica.create_comment · multica.rerun_issue

Reference material

This plugin is a sibling of and modeled on the official OpenAI reference plugin:

• bits-and-bolts — plugins/bits-and-bolts/ in openai/mcp-extensions. The build pipeline (scripts/build.mjs, build-app.mjs, dev.mjs), the App + OpenAIExtensions bootstrap pattern, and the UI resource registration contract (text/html;profile=mcp-app, data-surface, _meta.openai/ui.entrypoints) are all adapted from it.

Codex / MCP App contracts:

• Plugins overview
• Build plugins
• ChatGPT UI guide
• Extensions (sidebar / file viewer entrypoints)
• Plugin UI reference

Multica platform contracts (from the local Multica skill references at C:\Users\kainh\.claude\skills\multica-platform\references\):

• issues.md — PR linking vs close intent, status side effects, sub-issues & stages
• projects.md — durable resources, local_directory execution modes
• agents.md — field contracts, env/secrets, skill binding
• runtimes.md — daemon/task CLI boundary, repo checkout
• mentions.md — which mention:// types enqueue a run

Multica HTTP API surface and auth scheme were traced from the Multica server source (E:\venus\reference-project\multica\server\): route registrations in server/cmd/server/server/router.go, the Auth middleware in server/internal/middleware/auth.go, and the CLI HTTP client in server/internal/cli/client.go. The /v1/* PluginBearerOnly middleware (server/internal/middleware/plugin_auth.go) only accepts mpi_/mpc_ tokens; all issue/project/agent/runtime routes live under /api/* and accept the mul_ user PAT.

License

Apache-2.0