Conversation Handoff MCP

Instructions

Implementation Reference

• src/tools.ts:237-272 (handler)

  The main handler function for handoff_list tool that retrieves all handoffs from storage and returns them in both text format and structured content. Includes error handling and audit logging.

    async (): Promise<CallToolResult> => {
      const audit = getAuditLogger();
      const timer = audit.startTimer();
  
      const { storage } = await getStorage();
      const result = await storage.list();
  
      audit.logTool({
        event: "tool_call",
        toolName: "handoff_list",
        durationMs: timer.elapsed(),
        success: result.success,
        error: result.error,
      });
  
      if (!result.success) {
        return {
          content: [{ type: "text", text: `\u274C Error: ${result.error}` }],
        };
      }
  
      const handoffs = result.data || [];
  
      if (handoffs.length === 0) {
        return {
          content: [{ type: "text", text: "No handoffs saved. Use handoff_save to create one." }],
          structuredContent: { count: 0, handoffs: [] },
        };
      }
  
      return {
        content: [{ type: "text", text: JSON.stringify(handoffs, null, 2) }],
        structuredContent: { count: handoffs.length, handoffs },
      };
    }
  );

• src/tools.ts:212-236 (registration)

  Tool registration using registerAppTool with MCP Apps UI support. Defines the tool name, title, description, empty input schema, output schema (zod validation for count and handoffs array), and UI resource metadata.

  registerAppTool(
    server,
    "handoff_list",
    {
      title: "Handoff List",
      description:
        "List all saved handoffs with summaries. Returns lightweight metadata without full conversation content. Opens interactive UI if supported.",
      inputSchema: {},
      outputSchema: z.object({
        count: z.number().describe("Number of handoffs"),
        handoffs: z
          .array(
            z.object({
              key: z.string(),
              title: z.string(),
              summary: z.string(),
              from_ai: z.string(),
              from_project: z.string(),
              created_at: z.string(),
            })
          )
          .describe("List of handoffs"),
      }),
      _meta: { ui: { resourceUri: VIEWER_RESOURCE_URI } },
    },

• src/local-storage.ts:127-142 (helper)

  LocalStorage implementation of list() method that maps stored handoffs to HandoffSummary objects (excluding conversation content) for efficient listing without loading full data.

  /**
   * List all saved handoffs (summaries only, no conversation content).
   * @returns Result with array of handoff summaries
   */
  async list(): Promise<StorageResult<HandoffSummary[]>> {
    const summaries: HandoffSummary[] = Array.from(this.handoffs.values()).map((h) => ({
      key: h.key,
      title: h.title,
      from_ai: h.from_ai,
      from_project: h.from_project,
      created_at: h.created_at,
      summary: h.summary,
    }));
  
    return { success: true, data: summaries };
  }

• src/remote-storage.ts:170-173 (helper)

  RemoteStorage implementation of list() method that makes an HTTP GET request to the /handoff endpoint to retrieve handoff summaries from a remote server.

  /** @inheritdoc */
  async list(): Promise<StorageResult<HandoffSummary[]>> {
    return this.request("GET", "/handoff");
  }

• src/types.ts:17-24 (schema)

  HandoffSummary interface defining the structure of handoff metadata returned by list(): key, title, from_ai, from_project, created_at, and summary (excludes conversation).

  export interface HandoffSummary {
    key: string;
    title: string;
    from_ai: string;
    from_project: string;
    created_at: string;
    summary: string;
  }