fqrgen-mcp 1.0.0

package/README.md

@@ -0,0 +1,232 @@
+# fQRGen MCP Server
+
+fQRGen REST API를 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 도구로 제공하는 서버입니다.
+AI 에이전트(Claude Code, Claude Desktop 등)에서 QR 코드를 직접 생성할 수 있습니다.
+
+## 전제 조건
+
+fQRGen REST API 서버가 실행 중이어야 합니다:
+
+| 서버              | 실행 방법                                  |
+| ----------------- | ------------------------------------------ |
+| macOS 네이티브 앱 | fQRGen.app 실행 (설정에서 REST API 활성화) |
+| Node.js 웹 앱     | `cd lib/qrgen-node && npm start`           |
+
+기본 서버 주소: `http://localhost:3014`
+
+---
+
+## 설치
+
+### 방법 1: npx (설치 없이 바로 실행)
+
+별도 설치 없이 MCP 설정에서 `npx`로 직접 실행합니다. (권장)
+
+### 방법 2: 글로벌 설치
+
+```bash
+npm install -g fqrgen-mcp
+```
+
+### 방법 3: 소스에서 직접 실행
+
+```bash
+git clone https://github.com/nowage/fQRGen.git
+cd fQRGen/_public/mcp
+npm install
+```
+
+---
+
+## 설정
+
+### Claude Code
+
+`~/.claude/settings.json` 또는 프로젝트 `.claude/settings.json`에 추가:
+
+```json
+{
+  "mcpServers": {
+    "fqrgen": {
+      "command": "npx",
+      "args": ["-y", "fqrgen-mcp"]
+    }
+  }
+}
+```
+
+서버 주소를 변경하려면:
+
+```json
+{
+  "mcpServers": {
+    "fqrgen": {
+      "command": "npx",
+      "args": ["-y", "fqrgen-mcp", "--server=http://192.168.0.10:3014"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+`claude_desktop_config.json`에 추가:
+
+```json
+{
+  "mcpServers": {
+    "fqrgen": {
+      "command": "npx",
+      "args": ["-y", "fqrgen-mcp"]
+    }
+  }
+}
+```
+
+### 글로벌 설치 후 사용
+
+```json
+{
+  "mcpServers": {
+    "fqrgen": {
+      "command": "fqrgen-mcp"
+    }
+  }
+}
+```
+
+### 환경 변수
+
+`FQRGEN_SERVER` 환경변수로 서버 주소를 지정할 수 있습니다:
+
+```json
+{
+  "mcpServers": {
+    "fqrgen": {
+      "command": "npx",
+      "args": ["-y", "fqrgen-mcp"],
+      "env": {
+        "FQRGEN_SERVER": "http://192.168.0.10:3014"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 제공 도구 (Tools)
+
+### 1. `health_check`
+
+fQRGen 서버 상태를 확인합니다.
+
+**파라미터**: 없음
+
+**응답 예시**:
+```json
+{
+  "status": "ok",
+  "app": "fQRGen",
+  "port": 3014
+}
+```
+
+---
+
+### 2. `generate_qr`
+
+텍스트 또는 URL로 QR 코드를 생성합니다.
+
+**파라미터**:
+
+| 이름        | 타입               | 필수   | 기본값                  | 설명                      |
+| ----------- | ------------------ | ------ | ----------------------- | ------------------------- |
+| `data`      | string             | 아니오 | `"https://example.com"` | QR 코드에 인코딩할 데이터 |
+| `format`    | `"png"` \| `"svg"` | 아니오 | `"png"`                 | 출력 형식                 |
+| `save_path` | string             | 아니오 | -                       | 파일 저장 경로            |
+
+**동작**:
+- `save_path` 지정 시: 파일로 저장하고 경로를 반환
+- `format=svg`: SVG XML 문자열을 텍스트로 반환
+- `format=png`: Base64 인코딩된 PNG 이미지를 반환
+
+**사용 예시** (Claude에게 요청):
+```
+"https://finfra.kr" QR 코드를 PNG로 생성해서 ~/Downloads/finfra-qr.png에 저장해줘
+```
+
+---
+
+### 3. `generate_qr_batch`
+
+여러 개의 QR 코드를 일괄 생성합니다.
+
+**파라미터**:
+
+| 이름                | 타입               | 필수   | 설명                  |
+| ------------------- | ------------------ | ------ | --------------------- |
+| `items`             | array              | 예     | QR 코드 목록          |
+| `items[].data`      | string             | 예     | 인코딩할 데이터       |
+| `items[].format`    | `"png"` \| `"svg"` | 아니오 | 출력 형식 (기본: png) |
+| `items[].save_path` | string             | 예     | 저장 경로             |
+
+**사용 예시** (Claude에게 요청):
+```
+다음 URL들을 QR 코드로 만들어줘:
+- https://finfra.kr → ~/Downloads/finfra.png
+- https://github.com → ~/Downloads/github.png
+- https://example.com → ~/Downloads/example.png
+```
+
+---
+
+## 디버깅
+
+### MCP Inspector로 테스트
+
+```bash
+npx @modelcontextprotocol/inspector npx fqrgen-mcp
+```
+
+브라우저에서 Inspector UI가 열리며, 각 도구를 직접 테스트할 수 있습니다.
+
+### 서버 연결 확인
+
+```bash
+# fQRGen REST API 서버가 실행 중인지 확인
+curl http://localhost:3014/
+```
+
+---
+
+## npm 배포
+
+```bash
+cd _public/mcp
+npm publish
+```
+
+---
+
+## 아키텍처
+
+```
+Claude Code / Claude Desktop
+    │
+    │ MCP (stdio)
+    ▼
+fqrgen-mcp (이 서버)
+    │
+    │ HTTP (REST API)
+    ▼
+fQRGen Server (localhost:3014)
+    ├── macOS 네이티브 앱 (Swift)
+    └── Node.js 웹 앱 (Express)
+```
+
+---
+
+## 라이선스
+
+MIT

package/index.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+
+/**
+ * fQRGen MCP Server
+ *
+ * Usage:
+ *   node index.js [--server=<url>]
+ *
+ * Arguments:
+ *   --server=<url> : (옵션) fQRGen REST API 서버 주소 (기본값: http://localhost:3014)
+ *
+ * Environment:
+ *   FQRGEN_SERVER : fQRGen REST API 서버 주소 (--server 옵션보다 우선순위 낮음)
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+// 서버 주소 결정: CLI 인자 > 환경변수 > 기본값
+function getServerUrl() {
+  const arg = process.argv.find((a) => a.startsWith("--server="));
+  if (arg) return arg.split("=").slice(1).join("=");
+  return process.env.FQRGEN_SERVER || "http://localhost:3014";
+}
+
+const SERVER_URL = getServerUrl();
+
+const server = new McpServer({
+  name: "fqrgen-mcp",
+  version: "1.0.0",
+});
+
+// Tool: health_check
+server.tool(
+  "health_check",
+  "fQRGen 서버 상태를 확인합니다",
+  {},
+  async () => {
+    try {
+      const res = await fetch(SERVER_URL);
+      const contentType = res.headers.get("content-type") || "";
+
+      if (contentType.includes("application/json")) {
+        const json = await res.json();
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(json, null, 2),
+            },
+          ],
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `서버 응답: ${res.status} ${res.statusText} (HTML UI - Node.js 서버)`,
+          },
+        ],
+      };
+    } catch (err) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `서버 연결 실패: ${err.message}\n서버 주소: ${SERVER_URL}`,
+          },
+        ],
+      };
+    }
+  }
+);
+
+// Tool: generate_qr
+server.tool(
+  "generate_qr",
+  "텍스트 또는 URL로 QR 코드를 생성합니다. PNG 바이너리 또는 SVG 문자열을 반환합니다.",
+  {
+    data: z
+      .string()
+      .default("https://example.com")
+      .describe("QR 코드에 인코딩할 텍스트 또는 URL"),
+    format: z
+      .enum(["png", "svg"])
+      .default("png")
+      .describe("출력 형식: png 또는 svg"),
+    save_path: z
+      .string()
+      .optional()
+      .describe("(옵션) 생성된 QR 이미지를 저장할 파일 경로"),
+  },
+  async ({ data, format, save_path }) => {
+    try {
+      const res = await fetch(`${SERVER_URL}/api/generate`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ data, format }),
+      });
+
+      if (!res.ok) {
+        const errBody = await res.text();
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `QR 생성 실패 (${res.status}): ${errBody}`,
+            },
+          ],
+        };
+      }
+
+      const buffer = Buffer.from(await res.arrayBuffer());
+
+      // 파일 저장 요청이 있으면 저장
+      if (save_path) {
+        const absPath = resolve(save_path);
+        await writeFile(absPath, buffer);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `QR 코드 저장 완료: ${absPath} (${format.toUpperCase()}, ${buffer.length} bytes)\n인코딩 데이터: ${data}`,
+            },
+          ],
+        };
+      }
+
+      // SVG는 텍스트로 반환
+      if (format === "svg") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: buffer.toString("utf-8"),
+            },
+          ],
+        };
+      }
+
+      // PNG는 base64 이미지로 반환
+      return {
+        content: [
+          {
+            type: "image",
+            data: buffer.toString("base64"),
+            mimeType: "image/png",
+          },
+          {
+            type: "text",
+            text: `QR 코드 생성 완료 (PNG, ${buffer.length} bytes)\n인코딩 데이터: ${data}`,
+          },
+        ],
+      };
+    } catch (err) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `QR 생성 오류: ${err.message}\n서버 주소: ${SERVER_URL}`,
+          },
+        ],
+      };
+    }
+  }
+);
+
+// Tool: generate_qr_batch
+server.tool(
+  "generate_qr_batch",
+  "여러 개의 QR 코드를 일괄 생성합니다",
+  {
+    items: z
+      .array(
+        z.object({
+          data: z.string().describe("QR 코드에 인코딩할 텍스트 또는 URL"),
+          format: z
+            .enum(["png", "svg"])
+            .default("png")
+            .describe("출력 형식"),
+          save_path: z.string().describe("저장할 파일 경로"),
+        })
+      )
+      .describe("생성할 QR 코드 목록"),
+  },
+  async ({ items }) => {
+    const results = [];
+
+    for (const item of items) {
+      try {
+        const res = await fetch(`${SERVER_URL}/api/generate`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ data: item.data, format: item.format }),
+        });
+
+        if (!res.ok) {
+          results.push(`FAIL: ${item.data} → ${res.status} 에러`);
+          continue;
+        }
+
+        const buffer = Buffer.from(await res.arrayBuffer());
+        const absPath = resolve(item.save_path);
+        await writeFile(absPath, buffer);
+        results.push(
+          `OK: ${item.data} → ${absPath} (${buffer.length} bytes)`
+        );
+      } catch (err) {
+        results.push(`FAIL: ${item.data} → ${err.message}`);
+      }
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `일괄 생성 결과 (${results.length}건):\n${results.join("\n")}`,
+        },
+      ],
+    };
+  }
+);
+
+// 서버 시작
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("MCP 서버 시작 실패:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "fqrgen-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for fQRGen QR code generation via REST API",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "fqrgen-mcp": "./index.js"
+  },
+  "files": [
+    "index.js"
+  ],
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "qrcode",
+    "fqrgen",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nowage/fQRGen.git",
+    "directory": "_public/mcp"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "license": "MIT"
+}