create_note

Instructions

Implementation Reference

• src/tools.ts:42-78 (handler)

  Handler function for 'create_note' tool — builds request body with optional title, content, permissions, and permalink, then POSTs to /notes via hackmdFetch. Also includes Zod schema validation.

  server.tool(
    "create_note",
    "Create a new note",
    {
      title: z.string().optional().describe("Note title"),
      content: z.string().optional().describe("Markdown content"),
      read_permission: z
        .enum(["owner", "signed_in", "guest"])
        .default("guest")
        .describe("Read permission (default: guest)"),
      write_permission: z
        .enum(["owner", "signed_in", "guest"])
        .default("owner")
        .describe("Write permission (default: owner)"),
      comment_permission: z
        .enum(["disabled", "forbidden", "owners", "signed_in_users", "everyone"])
        .optional()
        .describe("Comment permission"),
      permalink: z.string().optional().describe("Custom permalink"),
    },
    async ({ title, content, read_permission, write_permission, comment_permission, permalink }) => {
      try {
        const body: Record<string, unknown> = {
          readPermission: read_permission,
          writePermission: write_permission,
        };
        if (title !== undefined) body.title = title;
        if (content !== undefined) body.content = content;
        if (comment_permission !== undefined) body.commentPermission = comment_permission;
        if (permalink !== undefined) body.permalink = permalink;
  
        return success(await hackmdFetch("/notes", { method: "POST", body }));
      } catch (e) {
        return error((e as Error).message);
      }
    }
  );

• src/tools.ts:42-61 (schema)

  Zod schema definition for 'create_note' input parameters: title, content, read_permission, write_permission, comment_permission, permalink.

  server.tool(
    "create_note",
    "Create a new note",
    {
      title: z.string().optional().describe("Note title"),
      content: z.string().optional().describe("Markdown content"),
      read_permission: z
        .enum(["owner", "signed_in", "guest"])
        .default("guest")
        .describe("Read permission (default: guest)"),
      write_permission: z
        .enum(["owner", "signed_in", "guest"])
        .default("owner")
        .describe("Write permission (default: owner)"),
      comment_permission: z
        .enum(["disabled", "forbidden", "owners", "signed_in_users", "everyone"])
        .optional()
        .describe("Comment permission"),
      permalink: z.string().optional().describe("Custom permalink"),
    },

• src/tools.ts:6-6 (registration)

  The registerTools function registers all tools including 'create_note' on the MCP server instance.

  export function registerTools(server: McpServer) {

• src/api.ts:13-38 (helper)

  hackmdFetch helper used by create_note to make authenticated HTTP requests to the HackMD API.

  export async function hackmdFetch(
    path: string,
    options: { method?: string; body?: unknown } = {}
  ): Promise<unknown> {
    const { method = "GET", body } = options;
    const token = getToken();
  
    const res = await fetch(`${API_BASE}${path}`, {
      method,
      headers: {
        Authorization: `Bearer ${token}`,
        ...(body ? { "Content-Type": "application/json" } : {}),
      },
      ...(body ? { body: JSON.stringify(body) } : {}),
    });
  
    if (!res.ok) {
      const text = await res.text().catch(() => "");
      throw new Error(`HackMD API ${method} ${path} → ${res.status}: ${text}`);
    }
  
    if (res.status === 204) return { success: true };
    if (res.status === 202) return { success: true, status: "accepted" };
  
    return res.json();
  }

• src/helpers.ts:1-12 (helper)

  success() and error() helper functions used to format MCP tool responses from create_note.

  export function success(data: unknown) {
    return {
      content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
    };
  }
  
  export function error(message: string) {
    return {
      content: [{ type: "text" as const, text: JSON.stringify({ error: message }) }],
      isError: true as const,
    };
  }