Skip to content

A self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search

10.4 KB
Raw Blame
import { CallToolResult } from "@modelcontextprotocol/server";
import { z } from "zod";

import { karakeepClient, registerTool, turndownService } from "./shared";
import { compactBookmark, compactList, toMcpToolError } from "./utils";

// Tools
export const searchBookmarksInputSchema = {
  query: z.string().describe(`
    By default, this will do a full-text search, but you can also use qualifiers to filter the results.
You can search bookmarks using specific qualifiers. is:fav finds favorited bookmarks,
is:archived searches archived bookmarks, is:tagged finds those with tags,
is:inlist finds those in lists, and is:link, is:text, and is:media filter by bookmark type.
url:<value> searches for URL substrings, #<tag> searches for bookmarks with a specific tag,
list:<name> searches for bookmarks in a specific list given its name (without the icon),
after:<date> finds bookmarks created on or after a date (YYYY-MM-DD), and before:<date> finds bookmarks created on or before a date (YYYY-MM-DD).
If you need to pass names with spaces, you can quote them with double quotes. If you want to negate a qualifier, prefix it with a minus sign.
## Examples:

### Find favorited bookmarks from 2023 that are tagged "important"
is:fav after:2023-01-01 before:2023-12-31 #important

### Find archived bookmarks that are either in "reading" list or tagged "work"
is:archived and (list:reading or #work)

### Combine text search with qualifiers
machine learning is:fav`),
  limit: z
    .number()
    .optional()
    .describe(`The number of results to return in a single query.`)
    .default(10),
  nextCursor: z
    .string()
    .optional()
    .describe(
      `The next cursor to use for pagination. The value for this is returned from a previous call to this tool.`,
    ),
  sortOrder: z
    .enum(["asc", "desc", "relevance"])
    .optional()
    .describe(`Sort by relevance or creation date. Defaults to relevance.`),
  searchMode: z
    .enum(["fts", "semantic", "hybrid"])
    .optional()
    .describe(
      `Search strategy. 'fts' uses full-text search, 'semantic' uses embeddings, and 'hybrid' combines both. Semantic and hybrid modes only support relevance sorting. Defaults to 'fts'.`,
    )
    .default("fts"),
};

export type SearchBookmarksInput = z.infer<
  z.ZodObject<typeof searchBookmarksInputSchema>
>;

export async function searchBookmarksHandler({
  query,
  limit,
  nextCursor,
  sortOrder,
  searchMode,
}: SearchBookmarksInput): Promise<CallToolResult> {
  const res = await karakeepClient.GET("/bookmarks/search", {
    params: {
      query: {
        q: query,
        limit: limit,
        includeContent: false,
        cursor: nextCursor,
        sortOrder,
        searchMode,
      },
    },
  });
  if (!res.data) {
    return toMcpToolError(res.error);
  }
  return {
    content: [
      {
        type: "text",
        text: `
${res.data.bookmarks.map((bm) => compactBookmark(bm)).join("\n\n")}

Next cursor: ${res.data.nextCursor ? `'${res.data.nextCursor}'` : "no more pages"}
`,
      },
    ],
  };
}

registerTool(
  "search-bookmarks",
  {
    description: `Search for bookmarks matching a specific query using full-text, semantic, or hybrid search.`,
    inputSchema: z.object(searchBookmarksInputSchema),
  },
  searchBookmarksHandler,
);

registerTool(
  "get-bookmark",
  {
    description: `Get a bookmark by id.`,
    inputSchema: z.object({
      bookmarkId: z.string().describe(`The bookmarkId to get.`),
    }),
  },
  async ({ bookmarkId }): Promise<CallToolResult> => {
    const res = await karakeepClient.GET(`/bookmarks/{bookmarkId}`, {
      params: {
        path: {
          bookmarkId,
        },
        query: {
          includeContent: false,
        },
      },
    });
    if (!res.data) {
      return toMcpToolError(res.error);
    }
    return {
      content: [
        {
          type: "text",
          text: compactBookmark(res.data),
        },
      ],
    };
  },
);

export const getBookmarkListsInputSchema = {
  bookmarkId: z
    .string()
    .min(1)
    .describe(`The id of the bookmark whose lists to retrieve.`),
};

export async function getBookmarkListsHandler({
  bookmarkId,
}: {
  bookmarkId: string;
}): Promise<CallToolResult> {
  const res = await karakeepClient.GET("/bookmarks/{bookmarkId}/lists", {
    params: { path: { bookmarkId } },
  });
  if (!res.data) {
    return toMcpToolError(res.error);
  }
  return {
    content: [
      {
        type: "text",
        text:
          res.data.lists.length > 0
            ? res.data.lists.map(compactList).join("\n\n")
            : "This bookmark is not in any lists.",
      },
    ],
  };
}

registerTool(
  "get-bookmark-lists",
  {
    description: `List every list that contains a bookmark.`,
    inputSchema: z.object(getBookmarkListsInputSchema),
    annotations: { readOnlyHint: true },
  },
  getBookmarkListsHandler,
);

registerTool(
  "create-bookmark",
  {
    description: `Create a link bookmark or a text bookmark`,
    inputSchema: z.object({
      type: z
        .enum(["link", "text"])
        .describe(`The type of bookmark to create.`),
      title: z.string().optional().describe(`The title of the bookmark`),
      content: z
        .string()
        .describe(
          "If type is text, the text to be bookmarked. If the type is link, then it's the URL to be bookmarked.",
        ),
    }),
  },
  async ({ title, type, content }): Promise<CallToolResult> => {
    const res = await karakeepClient.POST(`/bookmarks`, {
      body:
        type === "link"
          ? {
              type: "link",
              title,
              url: content,
            }
          : {
              type: "text",
              title,
              text: content,
            },
    });
    if (!res.data) {
      return toMcpToolError(res.error);
    }
    return {
      content: [
        {
          type: "text",
          text: compactBookmark(res.data),
        },
      ],
    };
  },
);

registerTool(
  "update-bookmark",
  {
    description: `Update fields on an existing bookmark. Only the fields you pass are modified; omitted fields stay unchanged. Returns the updated bookmark.`,
    inputSchema: z.object({
      bookmarkId: z.string().describe(`The bookmarkId to update.`),
      title: z
        .string()
        .nullable()
        .optional()
        .describe(`The bookmark's user-set title. Pass null to clear it.`),
      note: z.string().optional().describe(`A free-form note on the bookmark.`),
      summary: z
        .string()
        .nullable()
        .optional()
        .describe(`The bookmark's summary. Pass null to clear it.`),
      archived: z
        .boolean()
        .optional()
        .describe(`Whether the bookmark is archived.`),
      favourited: z
        .boolean()
        .optional()
        .describe(`Whether the bookmark is favourited.`),
      url: z.string().url().optional().describe(`New URL for a link bookmark.`),
      description: z
        .string()
        .nullable()
        .optional()
        .describe(`Link description. Pass null to clear it.`),
      author: z
        .string()
        .nullable()
        .optional()
        .describe(`Link author. Pass null to clear it.`),
      publisher: z
        .string()
        .nullable()
        .optional()
        .describe(`Link publisher. Pass null to clear it.`),
      createdAt: z
        .string()
        .datetime()
        .optional()
        .describe(`Override the bookmark's createdAt timestamp (ISO 8601).`),
    }),
  },
  async ({ bookmarkId, ...fields }): Promise<CallToolResult> => {
    const patchRes = await karakeepClient.PATCH(`/bookmarks/{bookmarkId}`, {
      params: {
        path: {
          bookmarkId,
        },
      },
      body: fields,
    });
    if (!patchRes.data) {
      return toMcpToolError(patchRes.error);
    }
    const getRes = await karakeepClient.GET(`/bookmarks/{bookmarkId}`, {
      params: {
        path: {
          bookmarkId,
        },
        query: {
          includeContent: false,
        },
      },
    });
    if (!getRes.data) {
      return toMcpToolError(getRes.error);
    }
    return {
      content: [
        {
          type: "text",
          text: compactBookmark(getRes.data),
        },
      ],
    };
  },
);

export const getBookmarkContentInputSchema = {
  bookmarkId: z.string().describe(`The bookmarkId to get content for.`),
};

export async function getBookmarkContentHandler({
  bookmarkId,
}: {
  bookmarkId: string;
}): Promise<CallToolResult> {
  const res = await karakeepClient.GET(`/bookmarks/{bookmarkId}`, {
    params: {
      path: { bookmarkId },
      query: { includeContent: true },
    },
  });
  if (!res.data) {
    return toMcpToolError(res.error);
  }
  let content;
  if (res.data.content.type === "link") {
    const htmlContent = res.data.content.htmlContent;
    content = turndownService.turndown(htmlContent ?? "");
  } else if (res.data.content.type === "text") {
    content = res.data.content.text;
  } else if (res.data.content.type === "asset") {
    content = res.data.content.content;
  }
  return {
    content: [
      {
        type: "text",
        text: content ?? "",
      },
    ],
  };
}

registerTool(
  "get-bookmark-content",
  {
    description: `Get the content of the bookmark in markdown`,
    inputSchema: z.object(getBookmarkContentInputSchema),
  },
  getBookmarkContentHandler,
);

export const deleteBookmarkInputSchema = {
  bookmarkId: z.string().min(1).describe(`The id of the bookmark to delete.`),
};

export async function deleteBookmarkHandler({
  bookmarkId,
}: {
  bookmarkId: string;
}): Promise<CallToolResult> {
  const getRes = await karakeepClient.GET("/bookmarks/{bookmarkId}", {
    params: { path: { bookmarkId }, query: { includeContent: false } },
  });
  if (!getRes.data) {
    return toMcpToolError(getRes.error);
  }
  const { id } = getRes.data;
  const titleFromContent =
    getRes.data.content.type === "link" ? getRes.data.content.title : undefined;
  const label = getRes.data.title ?? titleFromContent ?? id;

  const delRes = await karakeepClient.DELETE("/bookmarks/{bookmarkId}", {
    params: { path: { bookmarkId: id } },
  });
  if (delRes.error) {
    return toMcpToolError(delRes.error);
  }
  return {
    content: [
      {
        type: "text",
        text: `Deleted bookmark "${label}" (id: ${id}).`,
      },
    ],
  };
}

registerTool(
  "delete-bookmark",
  {
    description: `Delete a bookmark by id. This is destructive — the bookmark, its highlights, and its assets are removed.`,
    inputSchema: z.object(deleteBookmarkInputSchema),
  },
  deleteBookmarkHandler,
);