Task Genius
MCP Integration

MCP API Reference

Complete API documentation for Task Genius MCP tools

This document provides comprehensive documentation for all MCP tools available in Task Genius. Each tool includes parameters, return values, and practical examples.

Authentication

All API calls require authentication using one of two methods:

Method A: Separate Headers

Authorization: Bearer YOUR_TOKEN
mcp-app-id: YOUR_APP_ID
Authorization: Bearer YOUR_TOKEN+YOUR_APP_ID

Protocol Flow

1. Initialize Session

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {}
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {}
    },
    "sessionId": "session_123"
  }
}

2. Use Tools

Include the session ID in subsequent requests:

mcp-session-id: session_123

Query Tools

query_tasks

Query tasks with advanced filtering and sorting options.

Parameters:

{
  filter?: {
    completed?: boolean;
    priority?: 1 | 2 | 3 | 4 | 5;
    project?: string;
    context?: string;
    tags?: string[];
    hasDate?: boolean;
    dateType?: "due" | "start" | "scheduled" | "completed";
    dateRange?: {
      from: string;  // YYYY-MM-DD
      to: string;    // YYYY-MM-DD
    };
  };
  sort?: {
    field: "priority" | "dueDate" | "startDate" | "created" | "modified";
    order: "asc" | "desc";
  };
  limit?: number;   // Default: 100, Max: 1000
  offset?: number;  // For pagination
}

Example:

{
  "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
    }
  }
}

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
      }
    ]
  }
}

query_project_tasks

Get all tasks for a specific project.

Parameters:

{
  project: string;  // Required: project name
  includeCompleted?: boolean;  // Default: true
  limit?: number;
}

Example:

{
  "name": "query_project_tasks",
  "arguments": {
    "project": "Website Redesign",
    "includeCompleted": false
  }
}

query_context_tasks

Get all tasks for a specific context.

Parameters:

{
  context: string;  // Required: context name (e.g., "@home", "@office")
  includeCompleted?: boolean;
  limit?: number;
}

query_by_priority

Filter tasks by priority level.

Parameters:

{
  priority: 1 | 2 | 3 | 4 | 5;  // Required
  completed?: boolean;
  limit?: number;
}

query_by_due_date

Find tasks within a date range.

Parameters:

{
  from?: string;  // YYYY-MM-DD (defaults to today)
  to?: string;    // YYYY-MM-DD (defaults to 7 days from now)
  includeOverdue?: boolean;
  limit?: number;
}

search_tasks

Full-text search across task content.

Parameters:

{
  query: string;  // Required: search text
  searchIn?: ("content" | "tags" | "project" | "context")[];
  caseSensitive?: boolean;  // Default: false
  limit?: number;
}

Example:

{
  "name": "search_tasks",
  "arguments": {
    "query": "meeting notes",
    "searchIn": ["content", "tags"],
    "limit": 20
  }
}

Create Tools

create_task

Create a single task with full metadata support.

Parameters:

{
  content: string;          // Required: task description
  filePath?: string;        // Target file (defaults to daily note)
  priority?: 1-5;           // Task priority
  dueDate?: string;         // YYYY-MM-DD
  startDate?: string;       // YYYY-MM-DD
  scheduledDate?: string;   // YYYY-MM-DD
  project?: string;         // Project name
  context?: string;         // Context (@location)
  tags?: string[];          // Tags without #
  parent?: string;          // Parent task ID for subtasks
  completed?: boolean;      // For recording completed tasks
  completedDate?: string;   // YYYY-MM-DD (when completed=true)
}

Example:

{
  "name": "create_task",
  "arguments": {
    "content": "Prepare presentation for client meeting",
    "priority": 4,
    "dueDate": "2024-01-20",
    "project": "ClientX",
    "tags": ["presentation", "important"],
    "context": "@office"
  }
}

Response:

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Task created successfully"
      }
    ],
    "task": {
      "id": "task_xyz789",
      "content": "Prepare presentation for client meeting",
      "filePath": "Daily/2024-01-15.md",
      "line": 23
    }
  }
}

create_task_in_daily_note

Create a task specifically in today's daily note.

Parameters:

{
  content: string;        // Required
  heading?: string;       // Place under specific heading
  priority?: 1-5;
  dueDate?: string;
  startDate?: string;
  project?: string;
  context?: string;
  tags?: string[];
  parent?: string;        // Parent task ID
  completed?: boolean;    // For recording
  completedDate?: string;
}

add_project_quick_capture

Quick capture with automatic project tagging.

Parameters:

{
  content: string;    // Required
  project: string;    // Required: auto-adds as +project
  heading?: string;   // Section heading
  priority?: 1-5;
  dueDate?: string;
  context?: string;
  tags?: string[];
}

batch_create_tasks

Create multiple tasks efficiently in one operation.

Parameters:

{
  defaultFilePath?: string;  // Default file for all tasks
  tasks: Array<{
    content: string;         // Required for each task
    filePath?: string;       // Override default
    priority?: 1-5;
    dueDate?: string;
    startDate?: string;
    project?: string;
    context?: string;
    tags?: string[];
    parent?: string;
    completed?: boolean;
    completedDate?: string;
  }>;
}

Example:

{
  "name": "batch_create_tasks",
  "arguments": {
    "defaultFilePath": "Projects/Sprint-01.md",
    "tasks": [
      {
        "content": "Setup development environment",
        "priority": 5,
        "tags": ["setup"]
      },
      {
        "content": "Review API documentation",
        "priority": 3,
        "tags": ["documentation"]
      },
      {
        "content": "Create initial tests",
        "priority": 4,
        "dueDate": "2024-01-18",
        "tags": ["testing"]
      }
    ]
  }
}

batch_create_subtasks

Add multiple subtasks to an existing parent task.

Parameters:

{
  parentTaskId: string;  // Required: parent task ID
  subtasks: Array<{
    content: string;     // Required for each
    priority?: 1-5;
    dueDate?: string;
  }>;
}

Update Tools

update_task

Update any properties of an existing task.

Parameters:

{
  taskId: string;     // Required
  updates: {
    content?: string;
    priority?: 1-5;
    dueDate?: string;
    startDate?: string;
    project?: string;
    context?: string;
    tags?: string[];
    completed?: boolean;
    completedDate?: string;
  };
}

update_task_status

Change task completion status.

Parameters:

{
  taskId: string;           // Required
  completed?: boolean;      // Set completion
  status?: string;         // Custom status marker
}

batch_update_task_status

Update multiple task statuses at once.

Parameters:

{
  taskIds: string[];        // Required: array of task IDs
  completed?: boolean;
  status?: string;
}

Example:

{
  "name": "batch_update_task_status",
  "arguments": {
    "taskIds": ["task_1", "task_2", "task_3"],
    "completed": true
  }
}

batch_update_text

Find and replace text across multiple tasks.

Parameters:

{
  taskIds: string[];    // Required
  findText: string;     // Required: text to find
  replaceText: string;  // Required: replacement text
}

postpone_tasks

Reschedule tasks to a new date.

Parameters:

{
  taskIds: string[];    // Required
  newDate: string;      // Required: YYYY-MM-DD
  updateType?: "due" | "start" | "both";  // Default: "due"
}

List Tools

list_all_metadata

Get all unique tags, projects, and contexts in your vault.

Parameters: None

Response:

{
  "result": {
    "tags": ["urgent", "review", "documentation"],
    "projects": ["Website", "Mobile App", "API"],
    "contexts": ["@home", "@office", "@phone"]
  }
}

list_tasks_for_period

List tasks for a specific time period.

Parameters:

{
  period: "day" | "month" | "year";  // Required
  date: string;                       // Required: base date YYYY-MM-DD
  dateType?: "due" | "start" | "scheduled" | "completed";
  limit?: number;
}

Example:

{
  "name": "list_tasks_for_period",
  "arguments": {
    "period": "month",
    "date": "2024-01-15",
    "dateType": "due"
  }
}

list_tasks_in_range

Get tasks between two dates.

Parameters:

{
  from: string;     // Required: YYYY-MM-DD
  to: string;       // Required: YYYY-MM-DD
  dateType?: "due" | "start" | "scheduled" | "completed";
  limit?: number;
}

Delete Tools

delete_task

Remove a task by ID.

Parameters:

{
  taskId: string;  // Required
}

Response:

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Task deleted successfully"
      }
    ],
    "deleted": true,
    "taskId": "task_abc123"
  }
}

Error Handling

All tools return errors in standard JSON-RPC format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "field": "priority",
      "reason": "Must be between 1 and 5"
    }
  }
}

Common Error Codes

CodeMeaningSolution
-32700Parse errorCheck JSON syntax
-32600Invalid requestVerify request structure
-32601Method not foundCheck tool name spelling
-32602Invalid paramsReview parameter requirements
-32603Internal errorCheck server logs
-32000Server errorRetry or check server status

Rate Limiting

To ensure optimal performance:

  • Batch operations when possible (use batch_* tools)
  • Limit query results to necessary data
  • Use pagination for large result sets
  • Cache responses when appropriate

Best Practices

1. Use Specific Filters

// Good: Specific and efficient
{
  "filter": {
    "completed": false,
    "priority": 5,
    "project": "CurrentSprint"
  }
}

// Bad: Too broad
{
  "filter": {}  // Returns all tasks
}

2. Handle Pagination

// First page
const page1 = await queryTasks({
  limit: 100,
  offset: 0
});

// Next page
const page2 = await queryTasks({
  limit: 100,
  offset: 100
});

3. Error Recovery

try {
  const result = await createTask({
    content: "New task"
  });
} catch (error) {
  if (error.code === -32602) {
    // Invalid parameters - check and retry
  } else if (error.code === -32603) {
    // Server error - log and notify user
  }
}

4. Optimize Batch Operations

// Good: Single batch operation
await batchCreateTasks({
  tasks: taskList
});

// Bad: Multiple individual calls
for (const task of taskList) {
  await createTask(task);  // Inefficient
}

WebSocket Support (Future)

The MCP server currently uses HTTP. WebSocket support for real-time updates is planned:

// Future implementation
const ws = new WebSocket('ws://127.0.0.1:7777/mcp/stream');

ws.on('message', (data) => {
  const event = JSON.parse(data);
  if (event.type === 'task.created') {
    // Handle new task
  }
});

SDK Examples

JavaScript/TypeScript

class TaskGeniusMCP {
  private sessionId: string;
  
  async initialize(): Promise<void> {
    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<Task[]> {
    return this.callTool('query_tasks', { filter });
  }
}

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})

Next Steps

API Tip: Always include a limit parameter in queries to prevent overwhelming responses. Start with small limits during development.

On this page

Authentication
Method A: Separate Headers
Method B: Combined Bearer (Recommended)
Protocol Flow
1. Initialize Session
2. Use Tools
Query Tools
query_tasks
query_project_tasks
query_context_tasks
query_by_priority
query_by_due_date
search_tasks
Create Tools
create_task
create_task_in_daily_note
add_project_quick_capture
batch_create_tasks
batch_create_subtasks
Update Tools
update_task
update_task_status
batch_update_task_status
batch_update_text
postpone_tasks
List Tools
list_all_metadata
list_tasks_for_period
list_tasks_in_range
Delete Tools
delete_task
Error Handling
Common Error Codes
Rate Limiting
Best Practices
1. Use Specific Filters
2. Handle Pagination
3. Error Recovery
4. Optimize Batch Operations
WebSocket Support (Future)
SDK Examples
JavaScript/TypeScript
Python
Next Steps