hwpConverMdMCP

Instructions

Implementation Reference

• src/tools/convert-content.ts:5-71 (handler)

  Main tool registration and handler implementation - defines registerConvertContentTool function that registers 'convert_hwp_content_to_md' tool with MCP server and contains the async handler that processes content conversion requests

  export function registerConvertContentTool(
    server: McpServer,
    apiClient: HwpApiClient
  ): void {
    server.registerTool(
      "convert_hwp_content_to_md",
      {
        title: "Convert HWP content to Markdown",
        description:
          "Base64로 인코딩된 HWP 또는 HWPX 파일 내용을 Markdown으로 변환합니다. " +
          "파일 경로 대신 파일 내용을 직접 전달할 때 사용합니다. " +
          "filename은 포맷 감지를 위해 .hwp 또는 .hwpx 확장자를 포함해야 합니다.",
        inputSchema: {
          content: z
            .string()
            .describe("Base64로 인코딩된 HWP 또는 HWPX 파일 내용"),
          filename: z
            .string()
            .describe(
              "원본 파일명 (.hwp 또는 .hwpx 확장자 포함, 포맷 감지용)"
            ),
        },
        annotations: {
          readOnlyHint: true,
          openWorldHint: true,
        },
      },
      async ({ content, filename }) => {
        try {
          const ext = filename.toLowerCase();
          if (!ext.endsWith(".hwp") && !ext.endsWith(".hwpx")) {
            return {
              content: [
                {
                  type: "text" as const,
                  text: "오류: 파일명은 .hwp 또는 .hwpx 확장자를 포함해야 합니다.",
                },
              ],
              isError: true,
            };
          }
  
          const result = await apiClient.convertContent(content, filename);
          return {
            content: [
              {
                type: "text" as const,
                text: result.markdown,
              },
            ],
          };
        } catch (error) {
          const message =
            error instanceof Error ? error.message : String(error);
          return {
            content: [
              {
                type: "text" as const,
                text: `변환 실패: ${message}`,
              },
            ],
            isError: true,
          };
        }
      }
    );
  }

• src/tools/convert-content.ts:17-26 (schema)

  Input schema definition - Zod schema validating 'content' (base64-encoded HWP/HWPX file) and 'filename' (must have .hwp or .hwpx extension)

  inputSchema: {
    content: z
      .string()
      .describe("Base64로 인코딩된 HWP 또는 HWPX 파일 내용"),
    filename: z
      .string()
      .describe(
        "원본 파일명 (.hwp 또는 .hwpx 확장자 포함, 포맷 감지용)"
      ),
  },

• src/client/hwp-api-client.ts:28-55 (helper)

  API client methods that perform the actual conversion - convertContent converts base64 string to Buffer and calls sendConvertRequest which makes HTTP POST to /api/v1/convert endpoint

  async convertContent(
    base64Content: string,
    filename: string
  ): Promise<ConvertResult> {
    const fileBuffer = Buffer.from(base64Content, "base64");
    return this.sendConvertRequest(fileBuffer, filename);
  }
  
  private async sendConvertRequest(
    fileBuffer: Buffer,
    filename: string
  ): Promise<ConvertResult> {
    const formData = new FormData();
    const blob = new Blob([new Uint8Array(fileBuffer)], { type: "application/octet-stream" });
    formData.append("file", blob, filename);
  
    const response = await fetch(`${this.baseUrl}/api/v1/convert`, {
      method: "POST",
      body: formData,
    });
  
    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`HWP API error (${response.status}): ${errorText}`);
    }
  
    return (await response.json()) as ConvertResult;
  }

• src/client/hwp-api-client.ts:4-7 (schema)

  Type definition for conversion result - ConvertResult interface defining the structure of API response with filename and markdown fields

  export interface ConvertResult {
    filename: string;
    markdown: string;
  }