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.

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 →