initial-commit (#1)

Reviewed-on: #1
Co-authored-by: Timo Behrendt <t.behrendt@t00n.de>
Co-committed-by: Timo Behrendt <t.behrendt@t00n.de>

src/tools/collection.ts

@@ -0,0 +1,28 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+import { handleSuccess, handleError } from "./utils";
+
+import type { ToolsFactory } from "./toolsFactory";
+import type { CollectionsApi } from "../gen/api/outline";
+import type { Logger } from "pino";
+
+export const registerCollectionTools: ToolsFactory<CollectionsApi> = (server: McpServer, client: CollectionsApi, logger: Logger) => {
+  server.registerTool(
+    "collections_list",
+    {
+      title: "List Collections",
+      description: "List all collections in the Outline workspace",
+      inputSchema: {},
+    },
+    async () => {
+      try {
+        const response = await client.collectionsList();
+        return handleSuccess(response, logger.child({ tool: "collections_list" }));
+      } catch (err) {
+        const error = handleError(err, logger.child({ tool: "collections_list" }));
+        logger.error(error);
+        return error;
+      }
+    }
+  );
+};

src/tools/common.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+const positiveInteger = z.number().int().positive();
+const uuid = z.string().uuid();
+const optionalUuid = uuid.optional();
+
+// Pagination
+export const offset = positiveInteger.optional();
+export const limit = positiveInteger.optional().default(10);
+export const sort = z.enum(["createdAt", "updatedAt", "title"]).optional();
+export const direction = z
+  .enum(["asc", "desc"])
+  .optional()
+  .transform((val) => val?.toUpperCase() as "ASC" | "DESC" | undefined);
+
+export const collectionId = optionalUuid;
+export const userId = optionalUuid;
+export const backlinkDocumentId = optionalUuid;
+export const parentDocumentId = optionalUuid;

src/tools/document.ts

@@ -0,0 +1,68 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { backlinkDocumentId, collectionId, direction, limit, offset, parentDocumentId, sort, userId } from "./common";
+import { handleSuccess, handleError } from "./utils";
+
+import type { ToolsFactory } from "./toolsFactory";
+import type { DocumentsApi } from "../gen/api/outline";
+import type { Logger } from "pino";
+
+export const registerDocumentTools: ToolsFactory<DocumentsApi> = (server: McpServer, client: DocumentsApi, logger: Logger): void => {
+  server.registerTool(
+    "documents_info",
+    {
+      title: "Get Document Info",
+      description: "Retrieve a document by its UUID, urlId, or shareId. At least one of these parameters must be provided.",
+      inputSchema: {
+        id: z.string().optional().describe("Unique identifier for the document. Either the UUID or the urlId is acceptable."),
+        shareId: z.string().optional().describe("Unique identifier for a document share, a shareId may be used in place of a document UUID"),
+      },
+    },
+    async (args) => {
+      try {
+        const response = await client.documentsInfo({
+          documentsInfoRequest: {
+            id: args?.id,
+            shareId: args?.shareId,
+          },
+        });
+        return handleSuccess(response, logger.child({ tool: "documents_info" }));
+      } catch (error) {
+        return handleError(error, logger.child({ tool: "documents_info" }));
+      }
+    }
+  );
+
+  const documentsListSchema = z.object({
+    offset,
+    limit,
+    sort,
+    direction,
+    collectionId,
+    userId,
+    backlinkDocumentId,
+    parentDocumentId,
+    template: z.boolean().optional(),
+  });
+
+  server.registerTool(
+    "documents_list",
+    {
+      title: "List Documents",
+      description: "This method will list all published documents and draft documents belonging to the current user.",
+      inputSchema: documentsListSchema.shape,
+    },
+    async (args) => {
+      try {
+        const validatedArgs = documentsListSchema.parse(args);
+        const response = await client.documentsList({
+          documentsListRequest: validatedArgs,
+        });
+        return handleSuccess(response, logger.child({ tool: "documents_list" }));
+      } catch (error) {
+        return handleError(error, logger.child({ tool: "documents_list" }));
+      }
+    }
+  );
+};

src/tools/toolsFactory.ts

@@ -0,0 +1,5 @@
+import type { BaseAPI } from "../gen/api/outline";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Logger } from "pino";
+
+export type ToolsFactory<T extends BaseAPI> = (server: McpServer, client: T, logger: Logger) => void;

src/tools/utils.ts

@@ -0,0 +1,28 @@
+import type { Logger } from "pino";
+
+export const handleError = (error: unknown, logger: Logger) => {
+  const message = `Error: ${error instanceof Error ? error.message : "Unknown error"}`;
+
+  logger.error(message);
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: message,
+      },
+    ],
+  };
+};
+
+const handleApiResponse = (response: unknown) => {
+  return JSON.stringify(response, null, 2);
+};
+
+export const handleSuccess = (data: unknown, logger: Logger) => {
+  const message = handleApiResponse(data);
+  logger.debug(message);
+
+  return {
+    content: [{ type: "text" as const, text: message }],
+  };
+};