Sphere plugin

Status: v1.

The Sphere plugin is a local Claude desktop extension (MCPB) for working with agent-readable content "fragments." It runs on your machine over stdio. There is no hosted server, no sign-in, and nothing to deploy. It hosts nothing and stores nothing.

It has two tiers of tools.

Local tools (no configuration, no network)

These operate on fragment files on your disk and work out of the box.

• validate_fragment - structural validity of a fragment against the Sphere fragment schema. Returns PASS or FAIL with a list of structural errors.
• analyze_fragment_readiness - advisory readiness gaps that are not hard errors (missing sources, media without descriptions, unclear or missing license, data without a schema, missing canonical_url), each with a severity and a suggestion.
• generate_fragment_report - validation plus readiness in one readable report, for a single fragment or a directory of fragments. The report includes a "Rights and risk" placeholder that notes rights and risk analysis is not part of v1.
• prepare_fragment - scaffold and write a new fragment (sphere.json + content.md) from fields and Markdown body you provide, then validate it.

Node tools (your own Sphere Node)

These talk to the owner face of a Sphere Node that you run yourself. They only ever call the single Node URL you configure.

Read-only:

• get_publisher_summary - GET /owner/summary
• get_fragment_usage - GET /owner/fragments/{id}/usage
• get_payment_status - GET /owner/payments

Write:

• publish_fragment - validate a prepared local fragment, then publish it to your node (PUT /owner/fragments/{id}). It refuses to publish a structurally invalid fragment.

If you have not set a Node URL and token, these tools do not fail. They explain how to configure them, and the local tools keep working regardless.

Publishing

Publishing is a guided flow. The plugin stays a thin client: it sends only to the node you configured, holds no Cloudflare or hosting credentials, and refuses to push a structurally broken fragment.

1. prepare_fragment - scaffold and write the fragment (sphere.json + content.md) from your fields and Markdown.
2. validate_fragment - confirm it is structurally valid.
3. analyze_fragment_readiness - review advisory gaps (these do not block publishing; they are quality suggestions).
4. publish_fragment - publish it to your node.

publish_fragment runs the structural check itself as a hard gate: if the fragment is invalid, it lists the errors and never calls your node. On success it reports the node's canonical URL for the fragment, along with the readiness score and any advisory gaps to consider later. Publishing sends the fragment you choose - its manifest and content.md - to your own configured node, and nowhere else. (Media files are not sent yet; that is a planned follow-up.)

Configuration

Both settings are optional. The plugin is useful with neither set.

• Sphere Node URL (sphere_node_url) - the base URL of your own Sphere Node, for example https://node.example.com.
• Sphere Node Token (sphere_node_token) - the owner bearer token for your Node. It is marked sensitive and stored in your operating system keychain, never in a file in this repository.

Set them in the extension's settings in Claude Desktop after installing the bundle. They are passed to the local server as environment variables; the token is not written to disk by this plugin.

Privacy

This plugin stores nothing and sends nothing anywhere except to the Sphere Node you configure, authenticated with the token you provide.

• No telemetry, no analytics, no third-party services.
• The local fragment tools never touch the network at all.
• The Node tools call only your configured sphere_node_url. They never call a URL taken from fragment content, tool arguments, or any other source.
• Publishing (publish_fragment) sends the fragment content you selected - its manifest and content.md - only to your own configured Node, and nowhere else.
• Your token is stored in the OS keychain by Claude Desktop and is sent only as a bearer token to your own Node.
• Questions, support, or privacy requests: email hello@sphere.pub.

Build and package

npm install
npm test            # vitest
npm run typecheck   # tsc --noEmit
npm run build       # bundle src/ into server/index.js (esbuild)
npm run pack        # build, then produce dist/sphere-plugin.mcpb

npm run pack writes dist/sphere-plugin.mcpb, which you can install in Claude Desktop. The server is a single self-contained bundle: it ships no node_modules and no native dependencies.

The fragment contract

The fragment schema and the Node response types are vendored from the sphere-node repository into src/contract/. That repository is the source of truth for the contract; this plugin consumes it and does not redefine it.

License

The Sphere plugin source code is licensed under the MIT License.