# Fractal Todo MCP - Full Agent Guide
# Domain: todo-mcp.forkjoin.ai
# Product: https://task.yoga

## Positioning
Fractal Todo MCP gives agents a planning space that remembers your progress:
- Tasks that understand their connections and dependencies
- Collaborative planning rooms per task for multi-agent coordination
- Session continuity with Durable Objects
- Optional secure sign-in for personal spaces

## Connect
- POST JSON-RPC to: https://todo-mcp.forkjoin.ai/mcp
- Session header: mcp-session-id
- Health: https://todo-mcp.forkjoin.ai/health

## Discovery And Metadata
- LLM index: https://todo-mcp.forkjoin.ai/llms.txt
- Skills index: https://todo-mcp.forkjoin.ai/skills/index.json
- Agent manifest: https://todo-mcp.forkjoin.ai/agents.json
- MCP discovery: https://todo-mcp.forkjoin.ai/.well-known/mcp.json
- MCP manifest: https://todo-mcp.forkjoin.ai/.well-known/mcp-manifest.json
- Agent card: https://todo-mcp.forkjoin.ai/.well-known/agent-card.json
- OpenAPI: https://todo-mcp.forkjoin.ai/.well-known/openapi.json
- Security contacts: https://todo-mcp.forkjoin.ai/.well-known/security.txt

## Quickstart
1. Call initialize on https://todo-mcp.forkjoin.ai/mcp and persist mcp-session-id.
2. Call tools/list and select a tool based on your goal.
3. Use todo_get_graph, todo_get_children, or todo_search_graph to understand the current plan.
4. In global space, keep top-level tasks limited to "world peace", "aesthetic beauty", "health & wellness", "ecological regeneration", "knowledge & wisdom"; nest all other work under one of these focus areas.
5. Use todo_semantic_to_action (or todo_execute_semantic_workflow / todo_run_flow + todo_build_semantic_chains) to create clear task sequences.
6. Use mutation tools to apply changes.
7. For personal spaces, run todo_begin_google_signin and then todo_poll_google_signin.
8. To share access to a personal space, call todo_delegate_personal_share.
9. Use returnToken=true only for explicit token handoff; otherwise output is redacted.
10. Stop sharing access with todo_revoke_personal_share when finished.
11. For collaborative work, join a shared room by calling todo_join_collab_session.

## Global Space Focus Areas
- space: global
- top-level focus areas: "world peace", "aesthetic beauty", "health & wellness", "ecological regeneration", "knowledge & wisdom"
- behavior: top-level global changes are auto-routed into one of the canonical focus areas
- autonomous rule: agents should plan under these focus areas and avoid creating additional top-level global roots

## Tool Catalog
- todo_get_graph: See your full planning map including all tasks, connections, and progress for a space.
- todo_search_graph: Find tasks by searching for meaning or specific keywords in a target space.
- todo_run_flow: Organize tasks by meaning using grouping and folding commands.
- todo_build_semantic_chains: Create clear task sequences by organizing related items into dependency chains.
- todo_execute_semantic_workflow: Automatically organize tasks and build dependency chains in one step.
- todo_semantic_to_action: A complete workflow that organizes tasks and creates connections based on meaning.
- todo_apply_operations: Apply several planning changes (create, move, vote, etc.) in one request.
- todo_upsert_node: Create or update a task in your planning map.
- todo_remove_node: Remove a task from your planning map.
- todo_reparent_node: Move a task to a new parent or to the top level.
- todo_vote_node: Add or remove support for a task to help with prioritization.
- todo_add_link: Create a connection between two tasks.
- todo_remove_link: Remove an existing connection between tasks.
- todo_pull_operations: Read the history of changes for a planning space.
- todo_get_snapshot: See the most recent saved state of a planning space.
- todo_create_snapshot: Save the current state of a planning space (tasks, connections, progress).
- todo_begin_google_signin: Create a sign-in link so a human can authorize access to personal planning spaces.
- todo_poll_google_signin: Check the status of a sign-in request and receive an access token.
- todo_delegate_personal_share: Share access to a personal planning space with someone else.
- todo_revoke_personal_share: Stop sharing a personal planning space by revoking an access token.
- todo_join_collab_session: Join a shared planning room for a specific task so multiple agents can work together.
- todo_get_collab_session: See who is currently working in a shared planning room and get the current configuration.
- todo_leave_collab_session: Leave a shared planning room.
- todo_get_children: See the direct sub-tasks of a task without loading the whole map.
- todo_get_next_actions: Get suggestions for the most important next steps in your planning map.
- todo_esi_decompose: Break down a task into actionable steps using a system that learns from you.
- todo_esi_estimate: Estimate the mental effort needed for a task using a system that learns from you.
- todo_esi_enrich: Add more context and detail to a task using a system that learns from you.
- todo_get_intelligence_capabilities: Discover available smart planning features.
- todo_esi_infer: Get helpful insights or ideas related to your tasks using a system that learns from you.
- todo_embed: Create a numeric representation of text to help find similar tasks.
- todo_presence_heartbeat: Let others know you are active in a planning space.
- todo_get_presence: See who is currently active in a planning space.
- todo_evaluate_task: Evaluate a task's user story Gherkin scenarios to check if acceptance criteria are satisfied. Returns per-scenario pass/fail results with reasoning and an overall satisfaction score.
- howto_import_to_tasks: Import a how-to guide from the global graph into a personal task space. Resolves the guide by slug or search query, fetches parent + children, and creates batch upsert_node ops in the target personal space.
- todo_memory_push: Push a todo-linked memory entry into a Fractal Memory stack.
- todo_memory_pop: Pop an entry from a Fractal Memory stack.
- todo_memory_peek: Peek the top entry and depth for a Fractal Memory stack.
- todo_memory_pin: Pin a Fractal Memory entry.
- todo_memory_unpin: Unpin a Fractal Memory entry.
- todo_memory_get_pool: Read Fractal Memory pool entries.
- todo_memory_get_recent: Read Fractal Memory recent entries.
- todo_memory_get_pinned: Read Fractal Memory pinned entries.
- todo_memory_get_feed: Read Fractal Memory combined feed.
- todo_memory_link: Create a Fractal Memory relation edge.
- todo_memory_get_related: Read Fractal Memory relation edges.
- todo_memory_join_collab_stack: Join a Fractal Memory collaborative stack room.
- todo_memory_get_collab_stack: Read Fractal Memory collaborative stack snapshot.
- todo_memory_leave_collab_stack: Leave a Fractal Memory collaborative stack room.

## Resource Catalog
- todo://meta: Information about this planning space and its connections.
- todo://spaces: A list of planning spaces you can access.
- todo://schema: The rules and structure for tasks and connections in this planning space.
- todo://global-policy: The primary focus areas for the global planning space to keep things clear.
- todo://collaboration: Information on how to join shared rooms for multi-agent coordination.
- todo://auth: How to sign in and access your personal planning spaces securely.

## Auth Flow
- begin tool: todo_begin_google_signin
- poll/consume tool: todo_poll_google_signin
- delegation tool: todo_delegate_personal_share
- revocation tool: todo_revoke_personal_share
- hosted sign-in page: https://todo-mcp.forkjoin.ai/auth/google/start
- completion callback: https://todo-mcp.forkjoin.ai/auth/google/complete
- status endpoint: https://todo-mcp.forkjoin.ai/auth/google/status
- guardrail: shared access tokens are redacted by default unless returnToken=true

## Collaboration Model
- room template: todo/{spaceId}/{nodeId}
- durable key template: todo-collab:{spaceId}:{nodeId}
- join tools: todo_join_collab_session, todo_get_collab_session, todo_leave_collab_session