qr-for-agent 0.1.0

package/README.md

@@ -0,0 +1,85 @@
+# qr-for-agent
+
+MCP server for dynamic QR codes — create, track, and update QR codes from any AI agent.
+
+This is a lightweight [Model Context Protocol](https://modelcontextprotocol.io/) server that wraps the QR Agent Core API. It lets AI agents (Claude Desktop, Cursor, Windsurf, etc.) manage QR codes as native tools.
+
+## Quick Start
+
+```bash
+npx qr-for-agent
+```
+
+You need an API key. Set it via environment variable:
+
+```bash
+API_KEY=your-key-here npx qr-for-agent
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "qr-for-agent": {
+      "command": "npx",
+      "args": ["-y", "qr-for-agent"],
+      "env": {
+        "API_KEY": "your-api-key",
+        "BASE_URL": "https://your-instance.example.com"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "qr-for-agent": {
+      "command": "npx",
+      "args": ["-y", "qr-for-agent"],
+      "env": {
+        "API_KEY": "your-api-key",
+        "BASE_URL": "https://your-instance.example.com"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable   | Required | Default                  | Description                     |
+| ---------- | -------- | ------------------------ | ------------------------------- |
+| `API_KEY`  | Yes      | —                        | Your QR Agent Core API key      |
+| `BASE_URL` | No       | `http://localhost:3100`  | URL of your QR Agent Core instance |
+
+## Tools
+
+The server exposes 6 tools:
+
+| Tool                    | Description                                                                 |
+| ----------------------- | --------------------------------------------------------------------------- |
+| `create_qr_code`       | Create a new dynamic QR code pointing to a target URL (SVG or PNG)          |
+| `get_qr_code`          | Retrieve details of an existing QR code by short ID                         |
+| `update_qr_destination`| Change where a QR code redirects — the image stays the same                 |
+| `list_qr_codes`        | List all QR codes with pagination                                           |
+| `delete_qr_code`       | Permanently delete a QR code and its analytics                              |
+| `get_qr_analytics`     | Get scan count and recent scan events for a QR code                         |
+
+## How It Works
+
+This MCP server is a thin HTTP client. It forwards tool calls to your QR Agent Core API server, which handles QR generation, storage, redirects, and analytics. The QR codes are "dynamic" — you can change the destination URL at any time without regenerating the QR image.
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -0,0 +1,7 @@
+interface RequestOptions {
+    method?: string;
+    body?: unknown;
+    query?: Record<string, string | number>;
+}
+export declare function apiRequest(path: string, options?: RequestOptions): Promise<any>;
+export {};

package/dist/api-client.js

@@ -0,0 +1,28 @@
+import dotenv from "dotenv";
+dotenv.config();
+const BASE_URL = process.env.BASE_URL || "http://localhost:3100";
+const API_KEY = process.env.API_KEY || "";
+export async function apiRequest(path, options = {}) {
+    const { method = "GET", body, query } = options;
+    let url = `${BASE_URL}${path}`;
+    if (query) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            params.set(key, String(value));
+        }
+        url += `?${params.toString()}`;
+    }
+    const headers = {
+        "X-API-Key": API_KEY,
+    };
+    if (body) {
+        headers["Content-Type"] = "application/json";
+    }
+    const res = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    return res.json();
+}
+//# sourceMappingURL=api-client.js.map

package/dist/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,MAAM,CAAC,MAAM,EAAE,CAAC;AAEhB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,uBAAuB,CAAC;AACjE,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;AAQ1C,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY,EAAE,UAA0B,EAAE;IACzE,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAEhD,IAAI,GAAG,GAAG,GAAG,QAAQ,GAAG,IAAI,EAAE,CAAC;IAC/B,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACrC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACjD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACjC,CAAC;QACD,GAAG,IAAI,IAAI,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;IACjC,CAAC;IAED,MAAM,OAAO,GAA2B;QACtC,WAAW,EAAE,OAAO;KACrB,CAAC;IAEF,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;IAC/C,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAC3B,MAAM;QACN,OAAO;QACP,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;KAC9C,CAAC,CAAC;IAEH,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACpB,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { tools } from "./tools.js";
+/**
+ * Standalone MCP server for QR Agent Core.
+ *
+ * Run with: npx qr-for-agent
+ *
+ * This exposes all QR management tools via the Model Context Protocol,
+ * allowing agents like Claude to call them directly as tools
+ * rather than making HTTP requests.
+ */
+const server = new McpServer({
+    name: "qr-for-agent",
+    version: "0.1.0",
+});
+// Register each tool from our definitions
+for (const [name, tool] of Object.entries(tools)) {
+    server.tool(name, tool.description, tool.inputSchema.shape, async (input) => {
+        try {
+            const result = await tool.handler(input);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: message,
+                            hint: "Check the input parameters and try again. Use list_qr_codes to verify available QR codes.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("QR Agent Core MCP server running on stdio");
+}
+main().catch(console.error);
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC;;;;;;;;GAQG;AACH,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,cAAc;IACpB,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,0CAA0C;AAC1C,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;IACjD,MAAM,CAAC,IAAI,CACT,IAAI,EACJ,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,WAAW,CAAC,KAAK,EACtB,KAAK,EAAE,KAA8B,EAAE,EAAE;QACvC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAY,CAAC,CAAC;YAChD,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;qBACtC;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;4BACnB,KAAK,EAAE,OAAO;4BACd,IAAI,EAAE,2FAA2F;yBAClG,CAAC;qBACH;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;AAC7D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+/**
+ * MCP tool definitions for QR Agent Core.
+ * Each tool calls the production HTTP API.
+ */
+export declare const tools: {
+    create_qr_code: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            target_url: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            format: z.ZodDefault<z.ZodEnum<{
+                svg: "svg";
+                png: "png";
+            }>>;
+        }, z.core.$strip>;
+        handler: (input: {
+            target_url: string;
+            label?: string;
+            format?: "svg" | "png";
+        }) => Promise<any>;
+    };
+    get_qr_code: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            short_id: z.ZodString;
+        }, z.core.$strip>;
+        handler: (input: {
+            short_id: string;
+        }) => Promise<any>;
+    };
+    update_qr_destination: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            short_id: z.ZodString;
+            target_url: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        handler: (input: {
+            short_id: string;
+            target_url: string;
+            label?: string;
+        }) => Promise<any>;
+    };
+    list_qr_codes: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            limit: z.ZodDefault<z.ZodNumber>;
+            offset: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>;
+        handler: (input: {
+            limit: number;
+            offset: number;
+        }) => Promise<any>;
+    };
+    delete_qr_code: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            short_id: z.ZodString;
+        }, z.core.$strip>;
+        handler: (input: {
+            short_id: string;
+        }) => Promise<any>;
+    };
+    get_qr_analytics: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            short_id: z.ZodString;
+        }, z.core.$strip>;
+        handler: (input: {
+            short_id: string;
+        }) => Promise<any>;
+    };
+};

package/dist/tools.js

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { apiRequest } from "./api-client.js";
+/**
+ * MCP tool definitions for QR Agent Core.
+ * Each tool calls the production HTTP API.
+ */
+export const tools = {
+    create_qr_code: {
+        description: "Create a new managed QR code. The QR code points to a short URL that redirects to your target URL. You can change the target URL later without regenerating the QR image. Returns the QR image data (SVG or PNG) and the short URL.",
+        inputSchema: z.object({
+            target_url: z
+                .string()
+                .url()
+                .describe("The destination URL the QR code should redirect to."),
+            label: z
+                .string()
+                .optional()
+                .describe("An optional label to identify this QR code."),
+            format: z
+                .enum(["svg", "png"])
+                .default("svg")
+                .describe('Image format. "svg" is recommended (smaller, scalable, text-parseable). Use "png" only if a bitmap is required.'),
+        }),
+        handler: async (input) => {
+            return apiRequest("/api/qr", { method: "POST", body: input });
+        },
+    },
+    get_qr_code: {
+        description: "Retrieve details of an existing QR code by its short ID. Returns the current target URL, metadata, and timestamps.",
+        inputSchema: z.object({
+            short_id: z.string().describe("The short ID of the QR code to look up."),
+        }),
+        handler: async (input) => {
+            return apiRequest(`/api/qr/${input.short_id}`);
+        },
+    },
+    update_qr_destination: {
+        description: "Change where an existing QR code redirects to. This is the key 'dynamic link' feature: the QR image stays the same, but scanning it will now go to the new URL. Ideal for updating campaigns, fixing broken links, or A/B testing.",
+        inputSchema: z.object({
+            short_id: z.string().describe("The short ID of the QR code to update."),
+            target_url: z
+                .string()
+                .url()
+                .describe("The new destination URL."),
+            label: z
+                .string()
+                .optional()
+                .describe("Optionally update the label too."),
+        }),
+        handler: async (input) => {
+            return apiRequest(`/api/qr/${input.short_id}`, {
+                method: "PATCH",
+                body: { target_url: input.target_url, label: input.label },
+            });
+        },
+    },
+    list_qr_codes: {
+        description: "List all managed QR codes with pagination. Returns short IDs, target URLs, labels, and timestamps. Use this to browse or search for existing QR codes.",
+        inputSchema: z.object({
+            limit: z.number().min(1).max(100).default(20).describe("Max results to return."),
+            offset: z.number().min(0).default(0).describe("Number of results to skip."),
+        }),
+        handler: async (input) => {
+            return apiRequest("/api/qr", { query: { limit: input.limit, offset: input.offset } });
+        },
+    },
+    delete_qr_code: {
+        description: "Permanently delete a QR code and all its scan analytics. The short URL will stop working immediately. This cannot be undone.",
+        inputSchema: z.object({
+            short_id: z.string().describe("The short ID of the QR code to delete."),
+        }),
+        handler: async (input) => {
+            return apiRequest(`/api/qr/${input.short_id}`, { method: "DELETE" });
+        },
+    },
+    get_qr_analytics: {
+        description: "Get scan analytics for a QR code. Returns total scan count and recent scan events with timestamps and user agents.",
+        inputSchema: z.object({
+            short_id: z.string().describe("The short ID of the QR code to get analytics for."),
+        }),
+        handler: async (input) => {
+            return apiRequest(`/api/analytics/${input.short_id}`);
+        },
+    },
+};
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "qr-for-agent",
+  "version": "0.1.0",
+  "description": "MCP server for dynamic QR codes — create, track, and update QR codes from any AI agent",
+  "type": "module",
+  "bin": {
+    "qr-for-agent": "dist/server.js"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": [
+    "mcp",
+    "qr-code",
+    "ai-agent",
+    "dynamic-qr",
+    "model-context-protocol",
+    "claude",
+    "cursor"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.3.6",
+    "dotenv": "^17.3.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}