HackMD MCP Server

Instructions

Implementation Reference

• tools/teamNotes.ts:57-74 (handler)

  The handler function that implements the core logic of the 'create_team_note' tool by calling the HackMD API client to create a team note.

  async ({ teamPath, payload }) => {
    try {
      const note = await client.createTeamNote(teamPath, payload);
      return {
        content: [
          {
            type: "text",
            text: `Team note created successfully:\n${JSON.stringify(note, null, 2)}`,
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [{ type: "text", text: `Error: ${error.message}` }],
        isError: true,
      };
    }
  },

• utils/schemas.ts:29-59 (schema)

  Zod schema for note creation options (payload parameter in create_team_note tool).

  export const CreateNoteOptionsSchema = z.object({
    title: z.string().optional().describe("Note title"),
    content: z.string().optional().describe("Note content"),
    readPermission: z
      .enum([
        NotePermissionRole.OWNER,
        NotePermissionRole.SIGNED_IN,
        NotePermissionRole.GUEST,
      ])
      .optional()
      .describe("Read permission"),
    writePermission: z
      .enum([
        NotePermissionRole.OWNER,
        NotePermissionRole.SIGNED_IN,
        NotePermissionRole.GUEST,
      ])
      .optional()
      .describe("Write permission"),
    commentPermission: z
      .enum([
        CommentPermissionType.DISABLED,
        CommentPermissionType.FORBIDDEN,
        CommentPermissionType.OWNERS,
        CommentPermissionType.SIGNED_IN_USERS,
        CommentPermissionType.EVERYONE,
      ])
      .optional()
      .describe("Comment permission"),
    permalink: z.string().optional().describe("Custom permalink"),
  });

• tools/teamNotes.ts:43-75 (registration)

  Registration of the 'create_team_note' MCP tool using server.tool(), defining name, description, input schema, hints, and handler.

  server.tool(
    "create_team_note",
    "Create a new note in a team",
    {
      teamPath: z.string().describe("Team path"),
      payload: CreateNoteOptionsSchema.describe("Create note options"),
    },
    {
      title: "Create a note in a Team workspace",
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: false,
      openWorldHint: true,
    },
    async ({ teamPath, payload }) => {
      try {
        const note = await client.createTeamNote(teamPath, payload);
        return {
          content: [
            {
              type: "text",
              text: `Team note created successfully:\n${JSON.stringify(note, null, 2)}`,
            },
          ],
        };
      } catch (error: any) {
        return {
          content: [{ type: "text", text: `Error: ${error.message}` }],
          isError: true,
        };
      }
    },
  );

• tools/index.ts:20-20 (registration)

  Invocation of registerTeamNotesApiTools which includes registration of create_team_note.

  registerTeamNotesApiTools(server, client);

• index.ts:132-132 (registration)

  Top-level call to registerAllTools, which chains to registration of create_team_note tool.

  registerAllTools(server, client);