shoal-cognition-edit-mcp

Local admin MCP for maintainers. This is deliberately separate from the public read MCP.

Required environment:

export SHOAL_COGNITION_URL="https://cognition.shoal.xyz"
export SHOAL_COGNITION_ADMIN_TOKEN="..."
# Optional: when set, approved public packets also project into Stream by default.
export SHOAL_STREAM_URL="https://shoal-stream-production.up.railway.app"
export SHOAL_STREAM_AGENT_TOKEN="..."
npx -y shoal-cognition-edit-mcp@latest

Tools:

• public_graph_plan_publish
• public_graph_apply_publish
• public_graph_upsert_node
• public_graph_upsert_edge
• public_graph_delete_node
• public_graph_delete_edge

Publish Flow

Treat publishing like a graph PR:

1. Export a public-safe candidate set from Shoal Thesis.
2. Call public_graph_plan_publish with nodes and edges.
3. Review the returned operations, validation.errors, validation.warnings, and plan_hash.
4. Call public_graph_apply_publish with the same payload, expected_plan_hash, and confirm: "APPLY_PUBLIC_GRAPH_PUBLISH".

Use prune_missing: false for normal merge-style publishes. Use prune_missing: true only when intentionally replacing the public graph projection.

When SHOAL_STREAM_URL and SHOAL_STREAM_AGENT_TOKEN are configured, approved public packets are also pushed to the current Shoal Stream session after the public graph write succeeds. To make the stream behavior explicit, pass:

{
  "push_to_stream_session": true,
  "stream_make_live": true
}

To publish only to the public graph for a one-off call, pass:

{
  "push_to_stream_session": false
}

The stream projection is broadcast-safe. It sends only title, public summary/claim/detail text, public observables/falsifiers, conviction, public graph link, and visible connection labels from public graph edges included in the publish payload. It does not display provenance/history or timeframe on Stream cards. Private Thesis relationships, unpublished relationships, and private source context must not be projected into Stream. Stream push happens after the public graph write succeeds; stream errors are returned as warnings and do not roll back the public publish.

Do not deploy this as a public endpoint.