@paradigma-inc/flywheel 0.1.10 → 0.1.12

package/skills/flywheel-to-graph/references/flywheel-mcp-tool-map.md

@@ -0,0 +1,160 @@
+# Flywheel MCP Tool Map
+
+This reference describes the Flywheel MCP tool families and the common runtime
+contract expected by the public Flywheel skill.
+
+Use it as a routing guide, not as a session snapshot. Always verify the exact
+tool surface exposed by your current MCP host before executing critical flows.
+
+## Core Contract Expectations
+
+- Node lifecycle and graph-mutation flows use optimistic locking
+  (`expected_revision`).
+- Node commits require `kind`, `outcome`, and `summary`.
+- `kind` is typically `insight` or `empirical`.
+- `insight` commits require non-empty `insights`.
+- `empirical` commits require a non-empty `hypothesis`; completed empirical
+  commits also require artifacts or a `no_artifacts_reason`.
+- Artifact publish is a two-step flow:
+  prepare upload, upload raw bytes to returned signed URLs, then finalize
+  the upload batch.
+
+## Tool Families
+
+### Session, Auth, and Contract
+
+- `mcp__flywheel__flywheel_auth_status`
+- `mcp__flywheel__flywheel_get_contract`
+- `mcp__flywheel__flywheel_get_contract_section`
+- `mcp__flywheel__flywheel_get_credits_balance`
+
+### Node Discovery and Read
+
+- `mcp__flywheel__flywheel_list_nodes`
+- `mcp__flywheel__flywheel_get_node`
+- `mcp__flywheel__flywheel_get_node_tree`
+- `mcp__flywheel__flywheel_get_node_ancestry`
+- `mcp__flywheel__flywheel_summarize_node_tree`
+- `mcp__flywheel__flywheel_get_campaign_snapshot`
+- `mcp__flywheel__flywheel_list_audit`
+
+### Node Mutation, Branching, and Commit
+
+- `mcp__flywheel__flywheel_stage_node_create`
+- `mcp__flywheel__flywheel_stage_node_update`
+- `mcp__flywheel__flywheel_commit_node`
+- `mcp__flywheel__flywheel_branch_node`
+- `mcp__flywheel__flywheel_merge_nodes`
+- `mcp__flywheel__flywheel_add_parent`
+- `mcp__flywheel__flywheel_remove_parent`
+- `mcp__flywheel__flywheel_delete_node`
+- `mcp__flywheel__flywheel_bulk_delete_nodes`
+
+### Access Policy and Collaboration
+
+- `mcp__flywheel__flywheel_get_node_sharing`
+- `mcp__flywheel__flywheel_set_sharing_for_node`
+- `mcp__flywheel__flywheel_set_sharing_for_nodes`
+
+### Tags and Graph Annotation
+
+- `mcp__flywheel__flywheel_create_node_tag`
+- `mcp__flywheel__flywheel_update_node_tag`
+- `mcp__flywheel__flywheel_delete_node_tag`
+- `mcp__flywheel__flywheel_set_node_tag_assignments`
+
+### Artifacts
+
+- `mcp__flywheel__flywheel_list_artifacts`
+- `mcp__flywheel__flywheel_get_artifact`
+- `mcp__flywheel__flywheel_get_artifact_preview`
+- `mcp__flywheel__flywheel_prepare_artifact_uploads`
+- `mcp__flywheel__flywheel_finalize_artifact_uploads`
+- `mcp__flywheel__flywheel_set_artifact_note`
+- `mcp__flywheel__flywheel_delete_artifact`
+
+Common artifact types include:
+`text`, `table`, `json`, `image`, `banner`, `html`, `plotly_html`, `vega`,
+`checkpoint`, and `diff_carousel`.
+
+### Export and Import
+
+- `mcp__flywheel__flywheel_export_subgraph`
+- `mcp__flywheel__flywheel_import_subgraph`
+- `mcp__flywheel__flywheel_export_summary`
+- `mcp__flywheel__flywheel_export_summary_stream`
+- `mcp__flywheel__flywheel_export_summary_pdf`
+- `mcp__flywheel__flywheel_export_summary_render_pdf`
+
+### Executions
+
+- `mcp__flywheel__flywheel_launch_execution`
+- `mcp__flywheel__flywheel_list_executions`
+- `mcp__flywheel__flywheel_terminate_execution`
+
+### Managed Compute
+
+- `mcp__flywheel__flywheel_approval_session_heartbeat`
+- `mcp__flywheel__flywheel_list_approval_sessions`
+- `mcp__flywheel__flywheel_expire_approval_session`
+- `mcp__flywheel__flywheel_request_compute_grant_approval`
+- `mcp__flywheel__flywheel_list_compute_grants`
+- `mcp__flywheel__flywheel_compute_list_options`
+- `mcp__flywheel__flywheel_compute_acquire`
+- `mcp__flywheel__flywheel_compute_status`
+- `mcp__flywheel__flywheel_compute_connection`
+- `mcp__flywheel__flywheel_compute_release`
+- `mcp__flywheel__flywheel_compute_release_all`
+
+### Campaign Budgets (Organizer Flows)
+
+- `mcp__flywheel__flywheel_list_campaign_budgets`
+- `mcp__flywheel__flywheel_create_campaign_budget`
+- `mcp__flywheel__flywheel_update_campaign_budget`
+- `mcp__flywheel__flywheel_revoke_campaign_budget`
+
+### Migration Helpers
+
+Some installations may expose migration-only helper tools with hashed names.
+Treat these as specialized one-off tools, not part of day-to-day research
+workflows.
+
+## Practical Tool Sequences
+
+### Insight Node Flow
+
+1. `mcp__flywheel__flywheel_stage_node_create`
+2. `mcp__flywheel__flywheel_stage_node_update`
+3. `mcp__flywheel__flywheel_commit_node`
+
+### Empirical Node With Artifacts
+
+1. `mcp__flywheel__flywheel_stage_node_create`
+2. `mcp__flywheel__flywheel_stage_node_update`
+3. Run experiment or compute steps
+4. `mcp__flywheel__flywheel_prepare_artifact_uploads`
+5. Upload artifact bytes to signed URLs
+6. `mcp__flywheel__flywheel_finalize_artifact_uploads`
+7. `mcp__flywheel__flywheel_commit_node`
+
+### Managed Compute Flow
+
+1. `mcp__flywheel__flywheel_approval_session_heartbeat`
+2. `mcp__flywheel__flywheel_request_compute_grant_approval`
+3. `mcp__flywheel__flywheel_list_compute_grants` (if needed)
+4. `mcp__flywheel__flywheel_compute_acquire`
+5. `mcp__flywheel__flywheel_compute_status` until ready
+6. `mcp__flywheel__flywheel_compute_connection`
+7. `mcp__flywheel__flywheel_compute_release` (or `..._release_all`)
+
+### Share a Graph With Collaborators
+
+1. `mcp__flywheel__flywheel_get_node_sharing`
+2. `mcp__flywheel__flywheel_set_sharing_for_node` (or `..._for_nodes`)
+3. `mcp__flywheel__flywheel_export_summary` or `..._export_subgraph` for handoff
+
+## Safety Notes
+
+- Prefer `get_contract` before implementing strict assumptions in automation.
+- Avoid call-order assumptions not mandated by contract.
+- Keep checks bounded: list/read first, then mutate only the intended nodes.