List Histories

Instructions

Implementation Reference

• src/tools/history.ts:7-13 (handler)

  The `listHistoriesHandler` async function that executes the tool logic: resolves workspaceId, executes a GraphQL query to fetch doc histories (id, timestamp, workspaceId), and returns the result as text.

  const listHistoriesHandler = async (parsed: { workspaceId?: string; guid: string; take?: number; before?: string }) => {
    const workspaceId = parsed.workspaceId || defaults.workspaceId || parsed.workspaceId;
    if (!workspaceId) throw new Error("workspaceId required (or set AFFINE_WORKSPACE_ID)");
    const query = `query Histories($workspaceId:String!,$guid:String!,$take:Int,$before:DateTime){ workspace(id:$workspaceId){ histories(guid:$guid, take:$take, before:$before){ id timestamp workspaceId } } }`;
    const data = await gql.request<{ workspace: any }>(query, { workspaceId, guid: parsed.guid, take: parsed.take, before: parsed.before });
    return text(data.workspace.histories);
  };

• src/tools/history.ts:14-27 (schema)

  Registration of the 'list_histories' tool with `server.registerTool()`, including input schema (workspaceId optional, guid required, take optional number, before optional string).

  server.registerTool(
    "list_histories",
    {
      title: "List Histories",
      description: "List doc histories (timestamps) for a doc.",
      inputSchema: {
        workspaceId: z.string().optional(),
        guid: z.string(),
        take: z.number().optional(),
        before: z.string().optional()
      }
    },
    listHistoriesHandler as any
  );

• src/index.ts:182-182 (registration)

  Top-level registration call: `registerHistoryTools(server, gql, { workspaceId: config.defaultWorkspaceId })` in index.ts.

  registerHistoryTools(server, gql, { workspaceId: config.defaultWorkspaceId });

• src/util/mcp.ts:8-24 (helper)

  The `text()` helper function used by the handler to format the response as MCP text content.

  export function text(data: unknown) {
    if (typeof data === "string") {
      return { content: [{ type: "text" as const, text: data }] };
    }
  
    if (data !== null && typeof data === "object" && !Array.isArray(data)) {
      const structuredContent = cloneJsonValue(data);
      return {
        content: [{ type: "text" as const, text: JSON.stringify(structuredContent) }],
        structuredContent,
      };
    }
  
    return {
      content: [{ type: "text" as const, text: JSON.stringify(data) }],
    };
  }

• src/toolSurface.ts:141-141 (registration)

  Permission/scope mapping for 'list_histories' in toolSurface.ts: requires 'history', 'history.read', 'read' scopes.

  list_histories: ["history", "history.read", "read"],