Build with an AI assistant

The Model Context Protocol (MCP) lets an AI assistant read project documentation and call tools directly, so instead of pasting docs into a chat, you point your editor at a server and the AI has everything it needs. NepTunes hosts a remote MCP server that exposes the full widget-developer documentation, the manifest.json schema, and tools to validate a manifest and scaffold a starter widget.

The server lives at:

https://neptunesmac.app/mcp

What it provides

Resources, every page in these docs, plus the manifest JSON Schema. The AI can read them on demand when you ask it to build or fix a widget.
Tools:
- list_docs / get_doc, browse and read the widget docs.
- validate_manifest, check a manifest.json against the schema and get precise error messages.
- scaffold_widget, generate a complete starter .nepget bundle (manifest.json, index.html, script.js, styles.css).
- list_permissions, the permission-to-method reference table.
- get_api_reference, the full window.NepTunes JavaScript API.

Give it the sample widgets too

MCP gives an assistant the reference. The sample widgets repository gives it working code to pattern-match against, which in practice matters more: fourteen complete bundles, plus an AGENTS.md written as an imperative checklist for coding agents rather than as prose for people.

git clone https://github.com/rurza/neptunes-widgets.git

Point your assistant at the clone alongside the MCP server and ask it to start from Minimal.nepget. It can then read a real manifest, a real script.js, and the _dev/ harness it can use to check its own work.

Signing is not part of the AI loop

An assistant can scaffold, validate and edit a bundle for you, but it cannot sign one , signing needs your Ed25519 private key, which lives only on your machine and should never be pasted into a chat, a tool call, or a repo.

So the last step is always yours, locally, with widget-tools.mjs (Updates & signing covers how to get it):

node widget-tools.mjs embed-sign MyWidget.nepget \
  --key .keys/my-widget-author.pem
node widget-tools.mjs embed-verify MyWidget.nepget

Worth telling your assistant up front, because it changes the definition of “done”: any edit it makes to a signed bundle, one line of CSS, a version bump, invalidates bundle.sig, and NepTunes will refuse the bundle until you re-sign it. Treat “AI changed a file” as “re-run embed-sign”. The rules it needs to respect are in Updates & signing.

Connect your client

Claude Code

claude mcp add --transport http neptunes-widgets https://neptunesmac.app/mcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "neptunes-widgets": {
      "url": "https://neptunesmac.app/mcp"
    }
  }
}

OpenCode

Add to your opencode.json under mcp servers with the http transport:

{
  "mcp": {
    "neptunes-widgets": {
      "type": "http",
      "url": "https://neptunesmac.app/mcp"
    }
  }
}

Codex / ChatGPT

Use the connector flow:

npx -y add-mcp https://neptunesmac.app/mcp

Follow the prompts to register the server.

Claude Desktop

Remote servers go in Connectors, not claude_desktop_config.json: Settings → Connectors → Add custom connector, and enter https://neptunesmac.app/mcp.

stdio-only clients

If your client only speaks stdio (no HTTP transport), bridge with mcp-remote:

npx mcp-remote https://neptunesmac.app/mcp

← Updates & signing Security & the sandbox →