Fix get_inbox_tasks Not Found in @alexarevalo9/ticktick-mcp-server

A practical guide to diagnosing and patching the TickTick Inbox tasks retrieval issue, including a get_project_with_data workaround and safe deployment steps.

Symptoms and quick diagnosis

If you’re seeing a get_inbox_tasks error or a Not Found resource error when trying to retrieve Inbox tasks through the MCP server, the server is not resolving the Inbox project ID the way your code expects. The symptom typically appears as a 404 or resource-not-found response from the TickTick API when the MCP server requests tasks using a null or incorrect project id.

Typical traces include a failing call to a helper like get_project_with_data that returns null or an empty object, then a subsequent task query that references an undefined ID. This happens most often after account changes, API response shape changes, or when the special Inbox project is represented differently (e.g., a special key, boolean flag, or non-numeric id).

Before editing code, rule out the common causes: expired/invalid auth, rate limits, or a temporary API change. If those are clear, you’re very likely facing an Inbox project ID issue or a bug in the MCP server’s project resolution logic.

Root causes (what actually goes wrong)

The code in many MCP wrappers assumes projects are returned with stable, numeric IDs and that Inbox is identifiable by a fixed id or type. TickTick implementations vary: Inbox can be represented as a special project with a flag or as a name-only entry. When the wrapper expects one shape but receives another, get_project_with_data can return nothing — that’s the precise failure point.

Another root cause: the server may cache an old project list and use an expired ID. When the account’s Inbox ID changes (account migration, server-side refactor), cached values are stale and requests fail. Race conditions can make this intermittent — working one moment and failing the next.

Finally, the MCP server might call a private/undocumented endpoint that has been changed upstream. If the web client or API returns a different JSON schema, the deserialization layer can silently drop needed fields, producing the Not Found resource error on subsequent calls.

Immediate, no-code workarounds

1) Refresh project list and retry. Ask the MCP server to re-fetch projects before resolving Inbox. Practically: call the “list projects” endpoint and search the returned items for Inbox by name. This often restores the correct project id without code changes.

2) Use a manual project filter. Instead of relying on a special Inbox endpoint, query tasks with a general filter (e.g., tasks without project or tasks matching the Inbox name). This reduces dependency on a singular project id and gets you the Inbox tasks you need.

3) Restart the MCP server and clear caches. If the issue is stale state, a restart forces a fresh project fetch. For production, combine restart and health checks with temporary monitoring until a code fix is applied.

Patch: reliable get_project_with_data workaround (code)

Below is a concise patch that finds Inbox safely: fetch all projects, look for explicit Inbox flags, match by name case-insensitively, and provide a deterministic fallback. It handles nulls and includes a retry on transient errors.

async function resolveInboxProjectId(client) {
  const maxRetries = 2;
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const projects = await client.get_projects(); // existing client method
      if (!Array.isArray(projects) || projects.length === 0) continue;
      // Best heuristics first
      let inbox = projects.find(p =>
        p.isInbox === true ||
        p.special === 'INBOX' || // vendor-specific
        (p.name && p.name.toLowerCase() === 'inbox')
      );
      // Fallback: find project with order 0 or first project
      if (!inbox) inbox = projects.find(p => p.order === 0) || projects[0];
      return inbox && inbox.id ? inbox.id : null;
    } catch (err) {
      if (attempt === maxRetries) throw err;
      await new Promise(r => setTimeout(r, 200 * (attempt + 1)));
    }
  }
  return null;
}

Integrate this function into the flow where get_project_with_data or get_inbox_tasks currently resolves the Inbox. Replace direct ID usage with an explicit call to resolveInboxProjectId, and null-check the result to avoid issuing queries with an undefined id.

If you prefer minimal edits, add a pre-check in get_inbox_tasks: if the project id is falsy, call the resolver and skip the task request when the resolver returns null (and surface a clear error message). That prevents 404 noise and helps debugging.

How to modify and deploy the MCP server package safely

Workflow summary: fork the repo, apply the patch, test locally, and then publish or open a PR. Don’t push untested changes to production. Use this sequence: clone, create a branch, patch the module (or add a utility), run unit/integration checks against a dev TickTick account that reproduces the issue.

Local testing tips: use npm link or yarn link to inject your patched package into the server environment. Alternatively, use patch-package to ship the patch without forking if you manage a single deployment and want to avoid republishing.

When ready, open a PR against alexarevalo9/ticktick-mcp-server (GitHub) and reference the failing trace. If you patched locally first, include test results and a short rationale describing the Inbox project ID issue and the benefits of a resilient resolver.

Best practices to prevent recurrence

1) Add monitoring and an assertion: verify that Inbox resolution returns a non-null id at startup and after auth refreshes. If it fails, set the MCP server to fail fast or expose a clear health endpoint so orchestrators can restart and alert engineers.

2) Add a small suite of integration tests that create a TickTick test account, list projects, and assert Inbox is discoverable. This catches upstream API schema changes before they hit production.

3) Avoid hard-coded IDs or brittle assumptions about project object shapes. Use multiple heuristics (name, flag, order) and a documented fallback strategy. Log the heuristic that matched so future debugging is quick and painless.

Backlinks & resources

Primary reference and repo: alexarevalo9/ticktick-mcp-server (GitHub).

Issue snapshot and example traces: get_inbox_tasks error — issue page.

When linking or opening a PR, include logs showing the Not Found resource error and the output of the projects list so maintainers can reproduce quickly.

Semantic core (expanded keyword set)

FAQ — quick answers

1. Why does get_inbox_tasks return a ‘Not Found’ resource error?

   The MCP server is issuing a task query with an invalid or missing Inbox project ID. This happens when get_project_with_data fails to resolve Inbox (schema mismatch, caching, or API change). Refresh projects or use the resolver patch above to avoid the 404s.

2. How do I implement the get_project_with_data workaround?

   Add a resolver that lists projects, finds Inbox by flag/name (case-insensitive), and falls back safely. See the code block above for a minimal implementation with retry and fallback logic.

3. What’s the safest way to modify @alexarevalo9/ticktick-mcp-server?

   Fork the repo, apply a minimal, well-documented patch, test locally using npm/yarn link or patch-package, and open a PR. Include logs and reproducible steps so maintainers can accept the change quickly.