# Local Codex plugin development

Napkin's primary deployment is a local plugin. Codex launches its stdio MCP server; the server exposes model tools and a bundled MCP Apps workbench. Studies live on the user's machine. No separately running web server is required for the plugin connection.

## Build and install

Node 22+ must be on the host's PATH. Build tooling needs npm; the completed plugin does not.

```sh
npm ci
npm run plugin:build
npm run plugin:check
```

Register the local marketplace and install from the CLI:

```sh
codex plugin marketplace add /absolute/path/to/napkin
codex plugin add napkin@napkin-local
codex plugin list --marketplace napkin-local --json
```

Restart Codex or the ChatGPT desktop host after installing. In the plugin directory, the local source is **Napkin Local**. Enable **Napkin**, verify its MCP connection, and use its design workflow skill. CLI and IDE surfaces can use the tools; rendering interactive widgets requires a host that supports MCP Apps. Validate widget behavior in that host rather than assuming every Codex surface renders HTML.

Try: “Use Napkin to sketch a balsa block, change its width, and explain how its mass changes.” The workflow creates or selects a study, inspects supported capabilities, performs revision-checked edits, explains calculations, and opens the drawing with `napkin_open`.

Codex copies locally installed plugins into its cache. Rebuild and reinstall after changing this plugin; restart the host to reload it. The install commands above are user setup steps; the repository's build and check commands do not register or enable plugins in your global settings.

For a distributable local ZIP:

```sh
npm run plugin:pack
```

This creates `artifacts/plugins/napkin-0.6.1.zip`. It contains the manifests, skill, icon, bundled server, UI, and license notices. It excludes studies, source downloads, development dependencies and credentials. Local distribution and installation are the current target.

## Data and server lifecycle

Default study storage is `~/.local/share/napkin/studies`. Both the stdio server and optional local browser bridge use the same default. A plugin reinstall replaces runtime files while retaining studies in this separate directory.

Storage precedence is `--store DIRECTORY`, then `NAPKIN_STORE`, then the default. Standalone launches resolve relative paths against their current working directory; use an absolute directory in plugin configuration.

The old CLI default was `.napkin` in the launch directory. Existing files stay there. To continue using those studies, explicitly configure their absolute directory; no automatic migration is performed.

For a plugin-specific directory, add `"env": { "NAPKIN_STORE": "/absolute/path/to/designs" }` to `mcpServers.napkin` in `plugins/napkin/mcp.json`, rebuild, and reinstall. Portable hosts consume this file. The generated Codex compatibility config also forwards a host environment `NAPKIN_STORE`. Keep customized paths outside the plugin's installation/cache directory.

The MCP process runs for the host connection and exits when the host closes its stdin. Each connection may use its own process; the filesystem store uses locks and revision tokens to serialize edits across processes. Undo history belongs to the active process, while design snapshots and run records persist.

## Connect MCP directly during development

You can test the server without installing the plugin:

```sh
npm run build
node dist/mcp/cli.js --help
codex mcp add napkin -- node /absolute/path/to/napkin/dist/mcp/cli.js \
  --store /absolute/path/to/designs
```

Use direct MCP configuration or the plugin's MCP connection for a given workflow so the host presents one set of tools. The local MCP transport is stdio. `napkin-bridge` is an optional authenticated loopback application RPC service for a separately hosted browser editor; it is a different transport and is not needed by the MCP Apps workbench.

The interactive workbench is delivered through `ui://napkin/workbench` with MIME type `text/html;profile=mcp-app`. App actions call the server through the host. The widget includes parameter editing, drawing, selection, dragging, deletion, undo, scene scopes, calculations, refresh, and host-supported conversation/fullscreen controls.

## Repository boundaries

| Location                                 | Responsibility                                                              |
| ---------------------------------------- | --------------------------------------------------------------------------- |
| `plugins/napkin/`                        | Portable plugin manifest, local MCP configuration, workflow skill, and icon |
| `.agents/plugins/marketplace.json`       | Local plugin discovery; paths resolve from the repository root              |
| `apps/mcp-apps/`                         | Shipped interactive workbench and host integration                          |
| `src/core/`, `src/react/`                | Shared design model and drawing components                                  |
| `src/mcp/`, `src/server/`                | Protocol, commands, local persistence, and optional browser bridge          |
| `examples/react-demo/`                   | Standalone drawing and multicopter examples                                 |
| `studies/`, source ZIPs                  | Numerical references and imported evidence                                  |
| `dist/`, plugin `runtime/`, `artifacts/` | Generated package/runtime/test outputs, ignored by git                      |

The npm package remains available for embedding core/React APIs. `npm run build` produces its declarations, mathematical bundle, MCP Apps HTML, and standalone plugin server bundle. `plugin:build` assembles those artifacts and derives compatibility manifests from the portable source files. Release versions in `package.json` and `plugins/napkin/plugin.json` must agree.

## Verify

```sh
npm test
npm run demo:check
npm run plugin:check
npm run plugin:codex-check
npm run licenses
NAPKIN_MCP_ENTRY=plugins/napkin/runtime/mcp/cli.mjs node scripts/browser-mcp-apps-check.mjs
```

`plugin:check` copies the plugin to an isolated directory with no `node_modules`, connects with a real MCP client, reads the embedded UI, edits a design and evaluates calculations, then replaces the install and verifies persistence. `plugin:codex-check` requires the Codex CLI and uses its read-only app-server plugin discovery API to verify the marketplace, skill, metadata and MCP declaration. It does not install the plugin or run a model turn. The browser check exercises the bundled server through the official MCP Apps host SDK in a sandbox.

The license audit covers production dependencies and all mathematical, UI, and local server bundle inputs. See [the package guide](package-guide.md) for the core APIs, tool schemas, revision behavior, and analytical limits.

The layout follows the [official plugin packaging guide](https://developers.openai.com/plugins/build/plugins). Local stdio setup follows [Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).