Roberto plugins

Plugin packages that connect other AI agents to Roberto, a personal AI agent. With one of these plugins installed, an agent can report its work to Roberto, ask the person questions and approvals that they answer in Roberto (web, desktop or mobile), hand goals to their Roberto, and answer the messages the person sends it from a Roberto room.

Directory	Platform	What it is
chatgpt/	ChatGPT, Codex and OpenAI dots	Agent Plugins package (plugin.json with extensions.com.openai, one remote MCP server, the roberto-setup onboarding skill), a deterministic ZIP build and a validator
cursor-grok-bot/	Cursor and Grok Bot	Cursor Plugin (.cursor-plugin/plugin.json, mcp.json with OAuth, the roberto-inbox routine skill, logo), a header-auth variant and a validator
meta-muse/	Meta Muse	Connector documentation (tools with Read / Write / Sensitive write classes), a machine-readable classification, the CLI and polling setup, the icon and a validator
.cursor-plugin/marketplace.json	Cursor and Grok Bot	Marketplace manifest that points Cursor at cursor-grok-bot/plugin
shared/	All	tool-catalog.json (the tools, events and scopes the server serves) and the dependency-free check library the validators use
test-mode/	All	Step-by-step local testing for each platform, and conformance.mjs, a probe that talks to the server the way each platform does
assets/	All	The Roberto mark (SVG source), its PNG renders and the render script
scripts/	All	validate-all.sh and the repository hygiene scan

How the plugins connect

Every package points at the same hosted server; nothing in this repository runs on a user's machine.

• MCP server: https://api.robertoagent.com/mcp, Streamable HTTP. It speaks protocol 2026-07-28 (including server/discover and MCP Events) and the initialize handshake for the 2025 and 2024 protocol versions. Every request is authenticated.
• OAuth 2.1: the authorization server is https://api.robertoagent.com (metadata at /.well-known/oauth-authorization-server, protected resource at /.well-known/oauth-protected-resource/mcp). PKCE S256, public clients only (token_endpoint_auth_method: none), dynamic client registration, Client ID Metadata Documents, RFC 9207 iss. Access tokens are bound to the MCP resource and refresh tokens rotate. Each user signs in to their own Roberto account and approves the connection on Roberto's consent screen.
• Agents with only a shell: the REST API at https://api.robertoagent.com/api/agent-hub/v1/ and the Roberto CLI (npm install -g @robertoagent/cli, then roberto hub ...). See meta-muse/cli-polling-fallback.md.

Permissions are OAuth scopes. The user can narrow or revoke them per connection in Roberto under Account → Integrations.

Scope	Lets the agent
hub:read	Read the work items, answers, inbox and jobs it created
hub:write	Create and update its tasks, goals, projects, state and checkpoints
hub:ask	Ask the user questions and request approvals
hub:handoff	Hand goals to the user's Roberto (each one waits for the user's approval)
hub:chat	Receive the messages the user addresses to it and reply to them ("Talk with you in rooms")

The server serves 18 tools and 4 events (answer.created, question.updated, job.updated, message.created). shared/tool-catalog.json is a snapshot of them with their annotations; the platforms read tool metadata from the live server, and the validators use the snapshot to cross-check the skills, READMEs and the Muse classification. Refresh its tools and events with node test-mode/conformance/conformance.mjs catalog --write (scope descriptions aren't served, so edit those by hand).

Messages from Roberto. In a Roberto room that only the user is in, the user can pick a connected agent (or @mention it) and send it a message. The agent is woken by the message.created event (MCP Events in ChatGPT dots, the routine webhook in Grok Bot, or the inbox poller for Muse), reads the message with check_messages, marks it with acknowledge_message, and replies with post_message (reply_to = the message id). The reply appears in the same room under the agent's name. This needs the hub:chat scope.

Build and validate

Requires Node 20 or later. There are no dependencies to install.

npm run validate                  # everything below, then the hygiene scan (same as sh scripts/validate-all.sh)

./chatgpt/build.sh                # build chatgpt/dist/roberto-chatgpt-<version>.zip and validate package + ZIP
node cursor-grok-bot/validate.mjs # Cursor plugin, header-auth variant and the root marketplace.json
node meta-muse/validate.mjs       # Muse icon, classification, tool documentation and CLI fallback
node scripts/hygiene.mjs          # no secrets, emails, non-public hosts, ids or local paths; links resolve

Each validator prints one PASS, WARN or FAIL line per check and exits non-zero on any FAIL. The ChatGPT ZIP build is deterministic: the same sources always give the same SHA-256. Re-rendering the icons needs rsvg-convert (npm run render:assets).

Test against a server

test-mode/ has the local install steps for each platform: a custom MCP server or local marketplace in ChatGPT, a local plugin or team marketplace in Cursor and Grok Bot, and the CLI flow for Muse. Before testing in a platform, run the conformance probe, which reads the packaged mcp.json and makes the same discovery, OAuth, MCP, events, routine and CLI calls the platform would:

node test-mode/conformance/conformance.mjs help
node test-mode/conformance/conformance.mjs metadata        # read-only, no account needed
node test-mode/conformance/conformance.mjs oauth           # OAuth in your browser, then the tool calls
node test-mode/conformance/conformance.mjs all --base http://127.0.0.1:<port>   # against a local server

Contributing

Issues and pull requests are welcome. Before opening a pull request:

• Run npm run validate and make sure it ends with ALL VALIDATORS PASS.
• Keep shared/tool-catalog.json equal to what the server serves. Change it with catalog --write, not by hand (except scope descriptions).
• Bump the package version when a package changes: version in chatgpt/plugin/plugin.json, and version in both cursor-grok-bot/plugin/.cursor-plugin/plugin.json and cursor-grok-bot/alternatives/header-auth/plugin.json (the validator checks that the two Cursor manifests stay in sync).
• Never commit credentials, tokens, email addresses or local paths. The hygiene scan fails the build if it finds one.

Security

The repository holds no credentials. Each user authorizes their own Roberto account with OAuth, or uses a scoped credential they create in Roberto and can revoke at any time.

To report a vulnerability, use GitHub's private vulnerability reporting on this repository (Security → Report a vulnerability). Please don't open a public issue for security problems, and don't test against other people's accounts. For help with a Roberto account, see https://robertoagent.com/support.

License

Apache-2.0. See LICENSE.