Heuresis

What is Heuresis?

Heuresis is a Model Context Protocol (MCP) server that exposes a Heuresis workspace to any MCP‑capable client—Claude Desktop, Claude Code, Cursor, Windsurf, or custom agents. It logs into the user’s Heuresis account, communicates with the same Supabase project the webapp uses, and respects the same Row‑Level Security (RLS). The webapp and the MCP server are two front‑ends to one cloud workspace.

How to use Heuresis?

Install the package globally (npm install -g @heuresis/mcp) or run it on‑demand with npx -y @heuresis/mcp. First link the machine to your Heuresis account using npx -y -p @heuresis/mcp heuresis-mcp login, then configure your MCP client (e.g., Claude Desktop or a .mcp.json file) to run the @heuresis/mcp server. For ephemeral environments (CI, cloud agents), set environment variables HEURESIS_EMAIL, HEURESIS_PASSWORD, and HEURESIS_ANON_KEY to sign in fresh on every boot.

Key features of Heuresis

• 34 tools: 31 data tools and 3 operator tools
• Live sync via Supabase Realtime (no manual refresh)
• Device‑code login for personal machines
• Email/password authentication for headless/CI usage
• Respects workspace Row‑Level Security (RLS)
• All writes stamped with origin='mcp' for session audit

Use cases of Heuresis

• Ideate and manage workspace content from Claude Desktop or similar clients
• Automate concept editing, linking, and project creation in CI pipelines
• Collaborate with the webapp — changes sync instantly via Realtime
• Search concepts and explore project graphs through natural‑language agent prompts
• Run creative operators (Branch, Matrix, ASIT, TRIZ, etc.) from an agent

FAQ from Heuresis

How do I authenticate the MCP server?

On a personal machine, run heuresis-mcp login and follow the device‑code URL to confirm in your browser. In ephemeral environments (CI, cloud agents), set HEURESIS_EMAIL, HEURESIS_PASSWORD, and HEURESIS_ANON_KEY environment variables to sign in fresh on each boot.

Can I unlink a machine?

Yes — run heuresis-mcp logout to delete the credentials file locally, or go to Settings ▸ Connected devices in the Heuresis webapp to revoke a device remotely.

What tools are available?

The server exposes 34 tools: 10 read tools (e.g., get_workspace_summary, list_projects, search_concepts), 21 write tools (e.g., add_concept, link_concepts, create_idea), and 3 operator‑run tools (run_operator, run_operator_and_commit, expand_concept).

Does the MCP server sync with the webapp?

Yes — by default the server subscribes to Supabase Realtime and notifies the client whenever rows change in nodes, edges, projects, or ideas. Edits made in the webapp appear without a manual refresh.

Is there a legacy read‑only mode?

Yes, but it is deprecated. If no credentials file exists and the HEURESIS_SNAPSHOT env var points to a JSON export, the server reads that file and exposes a reduced set of read‑only tools. This mode will be removed in a later release.