### Example Project Management Queries Source: https://taskgenius.md/docs/mcp-integration/clients/cursor These examples show how to use Task Genius for project management queries. They cover filtering tasks by project name, tags, and creating new tasks within specific projects. ```text "Show all tasks for project Q1Planning" "Find incomplete tasks tagged #milestone" "Create task in project: Design review meeting" ``` -------------------------------- ### Example Quick Capture Queries Source: https://taskgenius.md/docs/mcp-integration/clients/cursor These examples illustrate how to use Task Genius for quickly capturing new tasks. They show adding tasks to an inbox, creating tasks in daily notes, and referencing specific items like pull requests. ```text "Add to inbox: Call client about proposal" "Create task in daily note: Team standup at 10am" "Quick task: Review pull request #123" ``` -------------------------------- ### Getting Started with MCP Source: https://taskgenius.md/docs/mcp-integration/index Steps to enable and configure the MCP server in Task Genius and connect your AI tools. ```APIDOC ## Getting Started ### Prerequisites * Task Genius must be running on desktop (MCP is not available on mobile) * The AI tool you're using must support MCP connections ### Quick Setup #### Step 1: Enable MCP Server 1. Open Obsidian Settings 2. Navigate to **Task Genius → MCP Integration** 3. Toggle **Enable MCP Server** to ON 4. Review and accept the security warning #### Step 2: Configure Security The MCP server uses token-based authentication to secure your data: * **Authentication Token** : Generated automatically when you enable MCP * **Host** : Default is `127.0.0.1` (local only). Use `0.0.0.0` for network access * **Port** : Default is `7777` Keep your authentication token secure! Anyone with this token can access and modify your tasks. ``` -------------------------------- ### Getting Started with MCP Integration Source: https://taskgenius.md/docs/mcp-integration Steps to enable and configure the MCP server in Task Genius and connect your AI tools. ```APIDOC ## Getting Started ### Prerequisites * Task Genius must be running on desktop (MCP is not available on mobile) * The AI tool you're using must support MCP connections ### Quick Setup #### Step 1: Enable MCP Server 1. Open Obsidian Settings 2. Navigate to **Task Genius → MCP Integration** 3. Toggle **Enable MCP Server** to ON 4. Review and accept the security warning #### Step 2: Configure Security The MCP server uses token-based authentication to secure your data: * **Authentication Token** : Generated automatically when you enable MCP * **Host** : Default is `127.0.0.1` (local only). Use `0.0.0.0` for network access * **Port** : Default is `7777` Keep your authentication token secure! Anyone with this token can access and modify your tasks. #### Step 3: Connect Your AI Tool Task Genius supports multiple AI applications. Refer to the "Supported Clients" section for specific configuration details for each application. ``` -------------------------------- ### Example Daily Review Queries Source: https://taskgenius.md/docs/mcp-integration/clients/cursor These are example natural language queries for Task Genius to perform daily review tasks. They demonstrate how to ask for tasks due today, completed yesterday, or overdue high-priority items. ```text "Show today's tasks by priority" "What tasks did I complete yesterday?" "List overdue high-priority tasks" ``` -------------------------------- ### Example Task Creation Prompts (Natural Language) Source: https://taskgenius.md/docs/mcp-integration/clients/vscode These are examples of natural language prompts that can be used to create tasks within Task Genius. They demonstrate how to specify task details like descriptions, tags, and project assignments. ```text "Create task for PR #123 review" "List tasks tagged with current-sprint" "Mark deployment tasks as complete" ``` ```text "Add task: Fix TypeScript errors in components folder" "Show all tasks related to API refactoring" "Create subtasks for implementing user authentication" ``` ```text "List tasks assigned to team-frontend project" "Show high-priority bugs for this week" "Create task in daily note: Discuss architecture changes" ``` -------------------------------- ### Common Issues - Server Won't Start Source: https://taskgenius.md/docs/mcp-integration/troubleshooting Troubleshoot and resolve issues where the MCP server fails to start. ```APIDOC ## Common Issues - Server Won't Start ### Symptoms * Red "Stopped" indicator in settings * "Failed to start server" error * No response from health endpoint ### Solutions **1. Port Already in Use** Check if port 7777 is occupied: ``` # Windows netstat -ano | findstr :7777 # macOS/Linux lsof -i :7777 ``` Fix: * Kill the process using the port, OR * Change to a different port in settings, OR * Use "Next Available Port" button **2. Permission Issues** On macOS/Linux: ``` # Check permissions ls -la ~/.obsidian/plugins/Obsidian-Task-Genius/ # Fix permissions if needed chmod -R 755 ~/.obsidian/plugins/Obsidian-Task-Genius/ ``` **3. Firewall Blocking** * Add Obsidian to firewall exceptions * Allow localhost connections (127.0.0.1) * For network access, allow port 7777 **4. Plugin Not Fully Loaded** 1. Disable Task Genius plugin 2. Restart Obsidian 3. Enable Task Genius plugin 4. Wait 5 seconds before enabling MCP ``` -------------------------------- ### Register Task Genius MCP Server Programmatically (JavaScript) Source: https://taskgenius.md/docs/mcp-integration/clients/cursor Demonstrates how to programmatically register the Task Genius MCP server using Cursor's extension API. This is useful for enterprise deployments, automated setups, and dynamic configurations. ```javascript // Register Task Genius MCP server programmatically vscode.cursor.mcp.registerServer('task-genius', { transport: 'http', url: 'http://127.0.0.1:7777/mcp', headers: { 'Authorization': 'Bearer YOUR_TOKEN+YOUR_APP_ID' } }); ``` -------------------------------- ### MCP API Search Tasks Example Source: https://taskgenius.md/docs/mcp-integration/api-reference Demonstrates how to perform a full-text search for tasks using the 'search_tasks' method. The example shows how to specify the search query, the fields to search within, and case sensitivity options. It also includes an example of the arguments for the 'search_tasks' method. ```json // Example Arguments { "name": "search_tasks", "arguments": { "query": "meeting notes", "searchIn": ["content", "tags"], "limit": 20 } } ``` -------------------------------- ### Task Genius Progress Bar Example Source: https://taskgenius.md/docs/progress-bars Demonstrates how a parent task displays a progress bar and status summary based on its sub-tasks. Includes examples of different sub-task statuses and their impact on the progress calculation. ```markdown - [ ] Parent Task [||||----] [✓:4 ⟳:1 ?:1 / 8] // Example with graphical bar and custom text format - [x] Sub-task 1 - [x] Sub-task 2 - [/] Sub-task 3 [-] [✓:0 ⟳:0 ?:0 / 8] - [ ] Sub-task 4 - [-] Sub-task 5 (Abandoned - might be excluded from count based on settings) - [?] Sub-task 6 (Planned) - [x] Sub-task 7 - [x] Sub-task 8 ``` -------------------------------- ### Task Genius Progress Bar Custom Text Format Examples Source: https://taskgenius.md/docs/progress-bars Provides examples of custom text formats for Task Genius progress bars using placeholders and JavaScript expressions. These examples illustrate how to display completion status in various ways. ```javascript // Example 1 // [{{COMPLETED}}/{{TOTAL}}] -> [6/8] ``` ```javascript // Example 2 // {{PERCENT}}% Done -> 75% Done ``` ```javascript // Example 3 // [{{COMPLETED_SYMBOL}}:{{COMPLETED}} {{IN_PROGRESS_SYMBOL}}:{{IN_PROGRESS}} / {{TOTAL}}] -> [✓:6 ⟳:1 / 8] ``` ```javascript // Example 4 // Progress: ${="🟩".repeat(Math.floor(data.percentages.completed/10))}${"⬜".repeat(10-Math.floor(data.percentages.completed/10))} -> Progress: 🟩🟩🟩🟩🟩🟩🟩⬜⬜⬜ ``` -------------------------------- ### Supported Clients Source: https://taskgenius.md/docs/mcp-integration/index Configuration examples for various AI tools to connect to the Task Genius MCP server. ```APIDOC ## Supported Clients ### Cursor Configure Cursor to connect to Task Genius MCP: ```json { "mcpServers": { "your-vault-tasks": { "url": "http://127.0.0.1:7777/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN+YOUR_APP_ID" } } } } ``` ### Claude Desktop Add to your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows): ```json { "mcpServers": { "your-vault-tasks": { "command": "curl", "args": [ "-X", "POST", "-H", "Authorization: Bearer YOUR_TOKEN+YOUR_APP_ID", "-H", "Content-Type: application/json", "--data-raw", "@-", "http://127.0.0.1:7777/mcp" ] } } } ``` ### Claude Code Install via command line: ```bash claude mcp add --transport http your-vault-tasks http://127.0.0.1:7777/mcp \ --header "Authorization: Bearer YOUR_TOKEN+YOUR_APP_ID" ``` ### VS Code Add to your VS Code settings: ```json { "mcp": { "servers": { "your-vault-tasks": { "type": "http", "url": "http://127.0.0.1:7777/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN+YOUR_APP_ID" } } } } } ``` ### Windsurf Add to your Windsurf configuration: ```json { "mcpServers": { "your-vault-tasks": { "serverUrl": "http://127.0.0.1:7777/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN+YOUR_APP_ID" } } } } ``` ### Zed Add to your Zed settings: ```json { "context_servers": { "your-vault-tasks": { "command": { "path": "curl", "args": [ "-X", "POST", "-H", "Authorization: Bearer YOUR_TOKEN+YOUR_APP_ID", "-H", "Content-Type: application/json", "--data-raw", "@-", "http://127.0.0.1:7777/mcp" ] }, "settings": {} } } } ``` ``` -------------------------------- ### Configure MCP Client Headers Source: https://taskgenius.md/docs/mcp-integration/troubleshooting Examples of how to configure the 'Authorization' and 'mcp-app-id' headers for MCP client requests. Demonstrates both separate and combined header configurations. ```json // Method A (Separate): { "Authorization": "Bearer YOUR_TOKEN", "mcp-app-id": "YOUR_APP_ID" } // Method B (Combined): { "Authorization": "Bearer YOUR_TOKEN+YOUR_APP_ID" } ``` -------------------------------- ### Global MCP Server Configuration (JSON) Source: https://taskgenius.md/docs/mcp-integration/clients/cursor Sets up a global MCP server configuration by creating an `mcp.json` file in the user's home directory (`~/.cursor/mcp.json`). This configuration applies system-wide to all projects. ```json { "mcpServers": { "obsidian-tasks": { "transport": "http", "url": "http://127.0.0.1:7777/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN+YOUR_APP_ID" } } } } ``` -------------------------------- ### Task Genius Composer Agent Prompts (Natural Language) Source: https://taskgenius.md/docs/mcp-integration/clients/cursor Examples of natural language prompts that can be used with the Cursor Composer Agent to interact with Task Genius. These prompts cover creating, updating, and querying tasks. ```plaintext "Show today's high-priority tasks" "Create task: Review quarterly report, priority 4, due tomorrow" "Mark 'Review quarterly report' as complete" "What tasks are overdue?" "Show all tasks for project ClientPresentation" ``` -------------------------------- ### Supported Clients for MCP Integration Source: https://taskgenius.md/docs/mcp-integration Configuration examples for connecting various AI tools and applications to the Task Genius MCP server. ```APIDOC ## Supported Clients ### Cursor Configure Cursor to connect to the MCP server: ```json { "mcpServers": { "your-vault-tasks": { "url": "http://127.0.0.1:7777/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN+YOUR_APP_ID" } } } } ``` ### Claude Desktop Add to your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows): ```json { "mcpServers": { "your-vault-tasks": { "command": "curl", "args": [ "-X", "POST", "-H", "Authorization: Bearer YOUR_TOKEN+YOUR_APP_ID", "-H", "Content-Type: application/json", "--data-raw", "@-", "http://127.0.0.1:7777/mcp" ] } } } ``` ### Claude Code Install via command line: ```bash claude mcp add --transport http your-vault-tasks http://127.0.0.1:7777/mcp \ --header "Authorization: Bearer YOUR_TOKEN+YOUR_APP_ID" ``` ### VS Code Add to your VS Code settings: ```json { "mcp": { "servers": { "your-vault-tasks": { "type": "http", "url": "http://127.0.0.1:7777/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN+YOUR_APP_ID" } } } } } ``` ### Windsurf Add to your Windsurf configuration: ```json { "mcpServers": { "your-vault-tasks": { "serverUrl": "http://127.0.0.1:7777/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN+YOUR_APP_ID" } } } } ``` ### Zed Add to your Zed settings: ```json { "context_servers": { "your-vault-tasks": { "command": { "path": "curl", "args": [ "-X", "POST", "-H", "Authorization: Bearer YOUR_TOKEN+YOUR_APP_ID", "-H", "Content-Type: application/json", "--data-raw", "@-", "http://127.0.0.1:7777/mcp" ] }, "settings": {} } } } ``` ``` -------------------------------- ### Python SDK Example for TaskGenius MCP Source: https://taskgenius.md/docs/mcp-integration/api-reference Presents a Python class for interacting with the TaskGenius MCP API using the `requests` library. It covers initialization and task querying, handling authentication headers and session IDs. ```python import requests import json class TaskGeniusMCP: def __init__(self, url, token, app_id): self.url = url self.headers = { 'Authorization': f'Bearer {token}+{app_id}', 'Content-Type': 'application/json' } self.session_id = None def initialize(self): response = requests.post( self.url, headers=self.headers, json={ 'jsonrpc': '2.0', 'id': 1, 'method': 'initialize' } ) self.session_id = response.headers.get('mcp-session-id') def query_tasks(self, **filter): return self.call_tool('query_tasks', {'filter': filter}) ``` -------------------------------- ### JavaScript/TypeScript SDK Example for TaskGenius MCP Source: https://taskgenius.md/docs/mcp-integration/api-reference Demonstrates a basic JavaScript/TypeScript class for interacting with the TaskGenius MCP API. It includes methods for initializing the connection and querying tasks, utilizing `fetch` for HTTP requests. ```javascript class TaskGeniusMCP { private sessionId: string; async initialize(): Promise { const response = await fetch(this.url, { method: 'POST', headers: this.headers, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize' }) }); const result = await response.json(); this.sessionId = response.headers.get('mcp-session-id'); } async queryTasks(filter: TaskFilter): Promise { return this.callTool('query_tasks', { filter }); } } ``` -------------------------------- ### Handle Pagination for Task Results (JavaScript) Source: https://taskgenius.md/docs/mcp-integration/api-reference Illustrates how to implement pagination for retrieving large sets of task data. The example shows fetching the first page with an offset of 0 and then the next page with an offset of 100. ```javascript // First page const page1 = await queryTasks({ limit: 100, offset: 0 }); // Next page const page2 = await queryTasks({ limit: 100, offset: 100 }); ``` -------------------------------- ### Deep Link Button with Secondary Variant Source: https://taskgenius.md/docs/deep-link-examples This example demonstrates how to use the secondary variant of the DeepLinkButton component by passing the 'variant' prop. It's suitable for alternative actions. ```html Secondary Action ``` -------------------------------- ### Custom Port Configuration Example Source: https://taskgenius.md/docs/mcp-integration This example shows how to configure a custom port for the Task Genius MCP server. If the default port 7777 is in use, you can change it to another port, such as 8888, in the server settings and update your client configurations accordingly. ```text # In settings, change port to 8888 # Then update your client configuration accordingly ``` -------------------------------- ### Initialize MCP Server Source: https://taskgenius.md/docs/mcp-integration/troubleshooting Initializes the MCP server connection. Requires your authentication token and app ID. ```APIDOC ## POST /mcp ### Description Initializes the MCP server connection. Requires your authentication token and app ID. ### Method POST ### Endpoint http://127.0.0.1:7777/mcp ### Parameters #### Headers - **Authorization** (string) - Required - Bearer YOUR_TOKEN+YOUR_APP_ID - **Content-Type** (string) - Required - application/json #### Request Body - **jsonrpc** (string) - Required - "2.0" - **id** (number) - Required - Request ID (e.g., 1) - **method** (string) - Required - "initialize" ### Request Example ```json { "jsonrpc": "2.0", "id": 1, "method": "initialize" } ``` ### Response #### Success Response (200) (Response structure not detailed in provided text, but typically includes initialization status) #### Response Example (Response example not detailed in provided text) ``` -------------------------------- ### Optimize Batch Operations for Task Creation (JavaScript) Source: https://taskgenius.md/docs/mcp-integration/api-reference Compares efficient batch operations with inefficient individual calls for creating multiple tasks. The 'Good' example uses a single `batchCreateTasks` call, while the 'Bad' example iterates and calls `createTask` for each task. ```javascript // Good: Single batch operation await batchCreateTasks({ tasks: taskList }); // Bad: Multiple individual calls for (const task of taskList) { await createTask(task); // Inefficient } ``` -------------------------------- ### Project-Specific MCP Server Configuration (JSON) Source: https://taskgenius.md/docs/mcp-integration/clients/cursor Configures a Task Genius MCP server for a specific project by creating a `.cursor/mcp.json` file in the project's root directory. This method allows for project-level settings and authentication. ```json { "mcpServers": { "task-genius": { "transport": "http", "url": "http://127.0.0.1:7777/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN+YOUR_APP_ID" } } } } ``` -------------------------------- ### Use Specific Filters for Task Queries (JavaScript) Source: https://taskgenius.md/docs/mcp-integration/api-reference Demonstrates the efficient use of filters in task queries. The 'Good' example shows a specific filter for completed tasks with a priority and project, while the 'Bad' example shows an overly broad filter that returns all tasks. ```javascript // Good: Specific and efficient { "filter": { "completed": false, "priority": 5, "project": "CurrentSprint" } } // Bad: Too broad { "filter": {} // Returns all tasks } ``` -------------------------------- ### List Available Tools via MCP Source: https://taskgenius.md/docs/mcp-integration/troubleshooting This command lists the available tools on the MCP server. It requires your authentication token, app ID, and a session ID. The request body specifies the 'tools/list' method. ```shell curl -X POST http://127.0.0.1:7777/mcp \ -H "Authorization: Bearer YOUR_TOKEN+YOUR_APP_ID" \ -H "mcp-session-id: YOUR_SESSION_ID" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' ``` -------------------------------- ### MCP API Query Tasks Example Source: https://taskgenius.md/docs/mcp-integration/api-reference Provides an example of a JSON-RPC request to query tasks using the 'query_tasks' method. It includes parameters for filtering by completion status, priority, and tags, as well as sorting options and pagination limits. The response structure for found tasks is also shown. ```json // Example Request { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "query_tasks", "arguments": { "filter": { "completed": false, "priority": 5, "tags": ["urgent", "review"] }, "sort": { "field": "dueDate", "order": "asc" }, "limit": 50 } } } // Example Response { "jsonrpc": "2.0", "id": 2, "result": { "content": [ { "type": "text", "text": "Found 3 tasks matching criteria" } ], "tasks": [ { "id": "task_abc123", "content": "Review quarterly report", "completed": false, "priority": 5, "dueDate": "2024-01-15", "tags": ["urgent", "review"], "project": "Q1-Planning", "filePath": "Daily/2024-01-10.md", "line": 15 } ] } } ``` -------------------------------- ### List Available Tools Source: https://taskgenius.md/docs/mcp-integration/troubleshooting Lists the tools available through the MCP server. Requires a session ID. ```APIDOC ## POST /mcp/tools/list ### Description Lists the tools available through the MCP server. Requires a session ID. ### Method POST ### Endpoint http://127.0.0.1:7777/mcp ### Parameters #### Headers - **Authorization** (string) - Required - Bearer YOUR_TOKEN+YOUR_APP_ID - **mcp-session-id** (string) - Required - YOUR_SESSION_ID - **Content-Type** (string) - Required - application/json #### Request Body - **jsonrpc** (string) - Required - "2.0" - **id** (number) - Required - Request ID (e.g., 2) - **method** (string) - Required - "tools/list" ### Request Example ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/list" } ``` ### Response #### Success Response (200) (Response structure not detailed in provided text, but typically includes a list of available tools) #### Response Example (Response example not detailed in provided text) ``` -------------------------------- ### Query Context Tasks API Source: https://taskgenius.md/docs/mcp-integration/api-reference Get all tasks for a specific context. Requires `mcp-session-id` header. ```APIDOC ### query_context_tasks Get all tasks for a specific context. Requires `mcp-session-id` header. #### Request Body ```json { "name": "query_context_tasks", "arguments": { "context": string, // Required: context name (e.g., "@home", "@office") "includeCompleted"?: boolean, "limit"?: number } } ``` ``` -------------------------------- ### Configure Limits and Offsets for Large Result Sets Source: https://taskgenius.md/docs/mcp-integration/troubleshooting When dealing with large datasets, it's crucial to implement limits and offsets for efficient retrieval and pagination. This prevents overwhelming the system and improves performance. ```json { "limit": 100, // Reasonable limit "offset": 0 // For pagination } ``` -------------------------------- ### Query Project Tasks API Source: https://taskgenius.md/docs/mcp-integration/api-reference Get all tasks for a specific project. Requires `mcp-session-id` header. ```APIDOC ### query_project_tasks Get all tasks for a specific project. Requires `mcp-session-id` header. #### Request Body ```json { "name": "query_project_tasks", "arguments": { "project": string, // Required: project name "includeCompleted"?: boolean, // Default: true "limit"?: number } } ``` #### Request Example ```json { "name": "query_project_tasks", "arguments": { "project": "Website Redesign", "includeCompleted": false } } ``` ``` -------------------------------- ### MCP Server Configuration with Environment Variables (JSON) Source: https://taskgenius.md/docs/mcp-integration/clients/cursor Configures an MCP server using environment variables for secure credential management. The `Authorization` header dynamically fetches the token and app ID from specified environment variables. ```json { "mcpServers": { "task-genius": { "transport": "http", "url": "http://127.0.0.1:7777/mcp", "env": { "TASK_GENIUS_TOKEN": "YOUR_TOKEN", "TASK_GENIUS_APP_ID": "YOUR_APP_ID" }, "headers": { "Authorization": "Bearer ${TASK_GENIUS_TOKEN}+${TASK_GENIUS_APP_ID}" } } } } ```