Conversation Handoff MCP

Instructions

Implementation Reference

• src/tools.ts:339-385 (handler)

  Complete MCP tool registration for handoff_clear including handler logic that calls storage.clear(), logs the operation, and returns appropriate success/error messages.

  // handoff_clear
  server.tool(
    "handoff_clear",
    "Clear handoffs. If key is provided, clears only that handoff. Otherwise clears all.",
    {
      key: z.string().optional().describe("Optional: specific handoff key to clear"),
    },
    async ({ key }) => {
      const audit = getAuditLogger();
      const timer = audit.startTimer();
  
      const { storage } = await getStorage();
      const result = await storage.clear(key);
  
      audit.logTool({
        event: "tool_call",
        toolName: "handoff_clear",
        durationMs: timer.elapsed(),
        success: result.success,
        error: result.error,
      });
  
      if (!result.success) {
        return {
          content: [
            {
              type: "text",
              text: `\u274C ${result.error}`,
            },
          ],
        };
      }
  
      const message = key
        ? `\u2705 ${result.data?.message}`
        : `\u2705 ${result.data?.message} (${result.data?.count} items)`;
  
      return {
        content: [
          {
            type: "text",
            text: message,
          },
        ],
      };
    }
  );

• src/tools.ts:343-345 (schema)

  Input validation schema for handoff_clear tool using Zod - accepts an optional 'key' parameter to clear a specific handoff or clear all if omitted.

  {
    key: z.string().optional().describe("Optional: specific handoff key to clear"),
  },

• src/local-storage.ts:180-192 (handler)

  Local in-memory storage implementation of clear method - deletes a specific handoff by key if provided, or clears all handoffs from the Map otherwise.

  async clear(key?: string): Promise<StorageResult<{ message: string; count?: number }>> {
    if (key) {
      if (this.handoffs.has(key)) {
        this.handoffs.delete(key);
        return { success: true, data: { message: `Handoff cleared: "${key}"` } };
      }
      return { success: false, error: `Handoff not found: "${key}"` };
    }
  
    const count = this.handoffs.size;
    this.handoffs.clear();
    return { success: true, data: { message: "All handoffs cleared", count } };
  }

• src/remote-storage.ts:182-187 (handler)

  Remote HTTP storage implementation of clear method - sends DELETE request to server, either to specific handoff endpoint or to clear all handoffs.

  async clear(key?: string): Promise<StorageResult<{ message: string; count?: number }>> {
    if (key) {
      return this.request("DELETE", `/handoff/${encodeURIComponent(key)}`);
    }
    return this.request("DELETE", "/handoff");
  }

• ui/viewer.ts:264-272 (registration)

  Client-side usage of handoff_clear tool in the UI viewer - calls the tool with a specific key parameter to delete individual handoffs.

  async function deleteHandoff(key: string): Promise<void> {
    statusEl.textContent = "Deleting...";
    try {
      await app.callServerTool({ name: "handoff_clear", arguments: { key } });
      await refreshList();
    } catch (err) {
      statusEl.textContent = `Error: ${err}`;
    }
  }