mcp-icon 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hustcc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+<div align="center">
+
+# 🎨 mcp-icon
+
+**A Model Context Protocol (MCP) server for semantic SVG icon search.**
+
+Generate infographic SVG icons by keyword — over **100,000 icons** with semantic search support, powered by [AntV Infographic](https://infographic.antv.vision/icon).
+
+[![npm version](https://img.shields.io/npm/v/mcp-icon.svg)](https://www.npmjs.com/package/mcp-icon)
+[![Build](https://github.com/hustcc/mcp-icon/actions/workflows/build.yml/badge.svg)](https://github.com/hustcc/mcp-icon/actions/workflows/build.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+</div>
+
+---
+
+## 📋 Table of Contents
+
+- [✨ Features](#-features)
+- [🤖 Usage](#-usage)
+- [🚰 Transport Modes](#-transport-modes)
+- [🎮 CLI Options](#-cli-options)
+- [🔨 Development](#-development)
+- [📄 License](#-license)
+
+---
+
+## ✨ Features
+
+- 🔍 **Semantic search** — Find icons by meaning, not just exact names
+- 🖼️ **100,000+ SVG icons** — A massive library of high-quality infographic icons
+- ⚡ **Three transport modes** — `stdio`, `sse`, and `streamable-http`
+- 🪶 **Minimal dependencies** — Clean, focused implementation
+- 🧪 **Fully tested** — Unit tests with Vitest
+
+### Available Tool
+
+| Tool | Description |
+|------|-------------|
+| `search_icons` | Search for SVG icons by keyword. Returns a list of SVG URLs matching the semantic query. |
+
+**`search_icons` parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `keyword` | string | ✅ | — | Search keyword or phrase (e.g. `"data analysis"`, `"cloud"`) |
+| `topK` | number | ❌ | `3` | Number of icons to return (1–20) |
+
+---
+
+## 🤖 Usage
+
+Add to your MCP client configuration (e.g. Claude Desktop, VS Code, Cursor):
+
+**macOS / Linux:**
+
+```json
+{
+  "mcpServers": {
+    "mcp-icon": {
+      "command": "npx",
+      "args": ["-y", "mcp-icon"]
+    }
+  }
+}
+```
+
+**Windows:**
+
+```json
+{
+  "mcpServers": {
+    "mcp-icon": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "mcp-icon"]
+    }
+  }
+}
+```
+
+---
+
+## 🚰 Transport Modes
+
+`mcp-icon` supports three standard MCP transport protocols.
+
+### stdio (default)
+
+Used by desktop MCP clients (Claude Desktop, Cursor, etc.):
+
+```bash
+npx mcp-icon
+# or explicitly:
+npx mcp-icon --transport stdio
+```
+
+### SSE (Server-Sent Events)
+
+```bash
+npx mcp-icon --transport sse --port 3456
+# Server available at: http://localhost:3456/sse
+```
+
+### Streamable HTTP
+
+```bash
+npx mcp-icon --transport streamable --port 3456
+# Server available at: http://localhost:3456/mcp
+```
+
+---
+
+## 🎮 CLI Options
+
+```
+mcp-icon CLI
+
+Options:
+  --transport, -t  Transport protocol: "stdio", "sse", or "streamable" (default: "stdio")
+  --host, -h       Host for SSE or streamable transport (default: localhost)
+  --port, -p       Port for SSE or streamable transport (default: 3456)
+  --endpoint, -e   Endpoint path:
+                   - For SSE: default is "/sse"
+                   - For streamable: default is "/mcp"
+  --help, -H       Show this help message
+```
+
+---
+
+## 🔨 Development
+
+```bash
+# Clone the repository
+git clone https://github.com/hustcc/mcp-icon.git
+cd mcp-icon
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Start with MCP inspector (for local debugging)
+npm start
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts          # CLI entry point
+├── server.ts         # MCP server + tool handlers
+├── services/
+│   ├── stdio.ts      # Stdio transport
+│   ├── sse.ts        # SSE transport
+│   └── streamable.ts # Streamable HTTP transport
+├── tools/
+│   └── search-icons.ts  # Tool definition
+└── utils/
+    ├── api.ts        # Icon search API client
+    └── logger.ts     # Logger utility
+tests/
+├── api.test.ts       # API client unit tests
+└── server.test.ts    # MCP server integration tests
+```
+
+---
+
+## 📄 License
+
+MIT © [hustcc](https://github.com/hustcc)
+

package/build/index.d.ts

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

package/build/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_util_1 = require("node:util");
+const logger_1 = require("./utils/logger.js");
+const server_1 = require("./server.js");
+const { values } = (0, node_util_1.parseArgs)({
+    options: {
+        transport: { type: "string", short: "t", default: "stdio" },
+        host: { type: "string", short: "h", default: "localhost" },
+        port: { type: "string", short: "p", default: "3456" },
+        endpoint: { type: "string", short: "e", default: "" },
+        help: { type: "boolean", short: "H" },
+    },
+});
+if (values.help) {
+    console.log(`
+mcp-icon CLI
+
+Options:
+  --transport, -t  Transport protocol: "stdio", "sse", or "streamable" (default: "stdio")
+  --host, -h       Host for SSE or streamable transport (default: localhost)
+  --port, -p       Port for SSE or streamable transport (default: 3456)
+  --endpoint, -e   Endpoint path:
+                   - For SSE: default is "/sse"
+                   - For streamable: default is "/mcp"
+  --help, -H       Show this help message
+`);
+    process.exit(0);
+}
+const transport = values.transport.toLowerCase();
+const port = Number.parseInt(values.port, 10);
+const host = values.host;
+if (transport === "sse") {
+    logger_1.logger.setIsStdio(false);
+    const endpoint = values.endpoint || "/sse";
+    (0, server_1.runSSEServer)(host, port, endpoint).catch(console.error);
+}
+else if (transport === "streamable") {
+    logger_1.logger.setIsStdio(false);
+    const endpoint = values.endpoint || "/mcp";
+    (0, server_1.runStreamableServer)(host, port, endpoint).catch(console.error);
+}
+else {
+    logger_1.logger.setIsStdio(true);
+    (0, server_1.runStdioServer)().catch(console.error);
+}

package/build/server.d.ts

@@ -0,0 +1,7 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { startSSEServer, startStdioServer, startStreamableServer } from "./services/index";
+export { startSSEServer, startStdioServer, startStreamableServer };
+export declare function createServer(): Server;
+export declare function runStdioServer(): Promise<void>;
+export declare function runSSEServer(host?: string, port?: number, endpoint?: string): Promise<void>;
+export declare function runStreamableServer(host?: string, port?: number, endpoint?: string): Promise<void>;

package/build/server.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startStreamableServer = exports.startStdioServer = exports.startSSEServer = void 0;
+exports.createServer = createServer;
+exports.runStdioServer = runStdioServer;
+exports.runSSEServer = runSSEServer;
+exports.runStreamableServer = runStreamableServer;
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const search_icons_1 = require("./tools/search-icons.js");
+const api_1 = require("./utils/api.js");
+const logger_1 = require("./utils/logger.js");
+const index_1 = require("./services/index.js");
+Object.defineProperty(exports, "startSSEServer", { enumerable: true, get: function () { return index_1.startSSEServer; } });
+Object.defineProperty(exports, "startStdioServer", { enumerable: true, get: function () { return index_1.startStdioServer; } });
+Object.defineProperty(exports, "startStreamableServer", { enumerable: true, get: function () { return index_1.startStreamableServer; } });
+function createServer() {
+    const server = new index_js_1.Server({ name: "mcp-icon", version: "1.0.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+        tools: [search_icons_1.searchIconsTool],
+    }));
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+        const { name, arguments: args = {} } = request.params;
+        if (name !== "search_icons") {
+            throw new types_js_1.McpError(types_js_1.ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        }
+        const { keyword, topK = 3 } = args;
+        if (!keyword || typeof keyword !== "string") {
+            throw new types_js_1.McpError(types_js_1.ErrorCode.InvalidParams, "The 'keyword' parameter is required and must be a string.");
+        }
+        const clampedTopK = Math.min(20, Math.max(1, Math.round(topK)));
+        logger_1.logger.info(`Searching icons: keyword="${keyword}", topK=${clampedTopK}`);
+        try {
+            const { urls } = await (0, api_1.searchIcons)(keyword, clampedTopK);
+            return {
+                content: urls.map((url) => ({
+                    type: "text",
+                    text: url,
+                })),
+                _meta: {
+                    description: "SVG icon URLs matching the search keyword. Each URL points to an SVG file that can be embedded using an <img> tag or rendered inline.",
+                    urls,
+                    keyword,
+                    topK: clampedTopK,
+                },
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "Unknown error";
+            logger_1.logger.error(`Failed to search icons: ${message}`);
+            throw new types_js_1.McpError(types_js_1.ErrorCode.InternalError, `Failed to search icons: ${message}`);
+        }
+    });
+    server.onerror = (err) => {
+        logger_1.logger.error("Server error", err);
+    };
+    process.on("SIGINT", async () => {
+        await server.close();
+        process.exit(0);
+    });
+    return server;
+}
+async function runStdioServer() {
+    const server = createServer();
+    await (0, index_1.startStdioServer)(server);
+}
+async function runSSEServer(host = "localhost", port = 3456, endpoint = "/sse") {
+    await (0, index_1.startSSEServer)(createServer, endpoint, port, host);
+}
+async function runStreamableServer(host = "localhost", port = 3456, endpoint = "/mcp") {
+    await (0, index_1.startStreamableServer)(createServer, endpoint, port, host);
+}

package/build/services/index.d.ts

@@ -0,0 +1,3 @@
+export { startStdioServer } from "./stdio";
+export { startSSEServer } from "./sse";
+export { startStreamableServer } from "./streamable";

package/build/services/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startStreamableServer = exports.startSSEServer = exports.startStdioServer = void 0;
+var stdio_1 = require("./stdio.js");
+Object.defineProperty(exports, "startStdioServer", { enumerable: true, get: function () { return stdio_1.startStdioServer; } });
+var sse_1 = require("./sse.js");
+Object.defineProperty(exports, "startSSEServer", { enumerable: true, get: function () { return sse_1.startSSEServer; } });
+var streamable_1 = require("./streamable.js");
+Object.defineProperty(exports, "startStreamableServer", { enumerable: true, get: function () { return streamable_1.startStreamableServer; } });

package/build/services/sse.d.ts

@@ -0,0 +1,2 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function startSSEServer(createServer: () => Server, endpoint?: string, port?: number, host?: string): Promise<void>;

package/build/services/sse.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startSSEServer = startSSEServer;
+const sse_js_1 = require("@modelcontextprotocol/sdk/server/sse.js");
+const express_1 = __importDefault(require("express"));
+const logger_1 = require("../utils/logger.js");
+async function startSSEServer(createServer, endpoint = "/sse", port = 3456, host = "localhost") {
+    const app = (0, express_1.default)();
+    app.use(express_1.default.json());
+    const connections = {};
+    app.get(endpoint, async (_req, res) => {
+        const server = createServer();
+        const transport = new sse_js_1.SSEServerTransport("/messages", res);
+        connections[transport.sessionId] = transport;
+        transport.onclose = () => {
+            delete connections[transport.sessionId];
+            logger_1.logger.info(`SSE connection closed: sessionId=${transport.sessionId}`);
+        };
+        await server.connect(transport);
+        logger_1.logger.info(`SSE connection opened: sessionId=${transport.sessionId}`);
+    });
+    app.post("/messages", async (req, res) => {
+        const sessionId = req.query.sessionId;
+        if (!sessionId) {
+            res.status(400).send("Missing sessionId parameter");
+            return;
+        }
+        const transport = connections[sessionId];
+        if (!transport) {
+            res.status(404).send("Session not found");
+            return;
+        }
+        try {
+            await transport.handlePostMessage(req, res, req.body);
+        }
+        catch (e) {
+            logger_1.logger.error("SSE error handling message", e);
+            if (!res.headersSent)
+                res.status(500).send("Error handling request");
+        }
+    });
+    app.listen(port, host, () => {
+        logger_1.logger.success(`SSE server listening on http://${host}:${port}${endpoint}`);
+    });
+}

package/build/services/stdio.d.ts

@@ -0,0 +1,2 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function startStdioServer(server: Server): Promise<void>;

package/build/services/stdio.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startStdioServer = startStdioServer;
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const logger_1 = require("../utils/logger.js");
+async function startStdioServer(server) {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    logger_1.logger.success("Stdio MCP server started");
+}

package/build/services/streamable.d.ts

@@ -0,0 +1,2 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function startStreamableServer(createServer: () => Server, endpoint?: string, port?: number, host?: string): Promise<void>;

package/build/services/streamable.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startStreamableServer = startStreamableServer;
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const cors_1 = __importDefault(require("cors"));
+const express_1 = __importDefault(require("express"));
+const logger_1 = require("../utils/logger.js");
+async function startStreamableServer(createServer, endpoint = "/mcp", port = 3456, host = "localhost") {
+    const app = (0, express_1.default)();
+    app.use(express_1.default.json());
+    app.use((0, cors_1.default)({ origin: "*", exposedHeaders: ["Mcp-Session-Id"] }));
+    app.post(endpoint, async (req, res) => {
+        try {
+            const server = createServer();
+            const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableJsonResponse: true,
+            });
+            res.on("close", () => {
+                transport.close();
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (e) {
+            logger_1.logger.error("Streamable HTTP error", e);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
+        }
+    });
+    app.listen(port, host, () => {
+        logger_1.logger.success(`Streamable HTTP server listening on http://${host}:${port}${endpoint}`);
+    });
+}

package/build/tools/search-icons.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const searchIconsTool: Tool;

package/build/tools/search-icons.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchIconsTool = void 0;
+exports.searchIconsTool = {
+    name: "search_icons",
+    description: "Search for SVG icons by keyword using semantic search. Returns URLs of matching SVG icons from a library of over 100,000 infographic icons.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            keyword: {
+                type: "string",
+                description: 'The search keyword or phrase to find relevant icons (e.g. "data analysis", "cloud computing", "security").',
+            },
+            topK: {
+                type: "number",
+                description: "The number of icons to return. Must be between 1 and 20. Defaults to 3.",
+                default: 3,
+                minimum: 1,
+                maximum: 20,
+            },
+        },
+        required: ["keyword"],
+    },
+};

package/build/utils/api.d.ts

@@ -0,0 +1,9 @@
+export interface IconSearchResult {
+    urls: string[];
+}
+/**
+ * Search for icons by keyword using the Infographic icon API.
+ * @param text - The search keyword (e.g. "data analysis")
+ * @param topK - Number of icons to return (1-20, default 3)
+ */
+export declare function searchIcons(text: string, topK?: number): Promise<IconSearchResult>;

package/build/utils/api.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchIcons = searchIcons;
+const ICON_API_BASE = "https://www.weavefox.cn/api/open/v1/icon";
+/**
+ * Search for icons by keyword using the Infographic icon API.
+ * @param text - The search keyword (e.g. "data analysis")
+ * @param topK - Number of icons to return (1-20, default 3)
+ */
+async function searchIcons(text, topK = 3) {
+    const url = `${ICON_API_BASE}?text=${encodeURIComponent(text)}&topK=${topK}`;
+    const response = await fetch(url, {
+        headers: { "Content-Type": "application/json" },
+    });
+    if (!response.ok) {
+        throw new Error(`Icon API request failed: ${response.status} ${response.statusText}`);
+    }
+    const json = (await response.json());
+    if (!json.status || !json.data?.success) {
+        throw new Error(`Icon API returned an error: ${json.message}`);
+    }
+    return { urls: json.data.data };
+}

package/build/utils/logger.d.ts

@@ -0,0 +1,13 @@
+declare function setIsStdio(isStdio: boolean): void;
+declare function info(message: string, ...args: unknown[]): void;
+declare function warn(message: string, ...args: unknown[]): void;
+declare function error(message: string, err?: unknown): void;
+declare function success(message: string, ...args: unknown[]): void;
+export declare const logger: {
+    info: typeof info;
+    warn: typeof warn;
+    error: typeof error;
+    success: typeof success;
+    setIsStdio: typeof setIsStdio;
+};
+export {};

package/build/utils/logger.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+const PREFIX = "[mcp-icon]";
+let IS_STDIO = true;
+function setIsStdio(isStdio) {
+    IS_STDIO = isStdio;
+}
+function getTimestamp() {
+    return new Date().toISOString();
+}
+function info(message, ...args) {
+    const fn = IS_STDIO ? console.error : console.log;
+    fn(`${PREFIX} ${getTimestamp()} ℹ️  ${message}`, ...args);
+}
+function warn(message, ...args) {
+    const fn = IS_STDIO ? console.warn : console.log;
+    fn(`${PREFIX} ${getTimestamp()} ⚠️  ${message}`, ...args);
+}
+function error(message, err) {
+    console.error(`${PREFIX} ${getTimestamp()} ❌ ${message}`, err ?? "");
+}
+function success(message, ...args) {
+    const fn = IS_STDIO ? console.error : console.log;
+    fn(`${PREFIX} ${getTimestamp()} ✅ ${message}`, ...args);
+}
+exports.logger = { info, warn, error, success, setIsStdio };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "mcp-icon",
+  "description": "A Model Context Protocol server for semantic icon search. Generate infographic SVG icons by keyword, with over 100,000 icons and semantic search support.",
+  "version": "1.0.0",
+  "main": "build/index.js",
+  "scripts": {
+    "start": "npx @modelcontextprotocol/inspector node build/index.js",
+    "prebuild": "rm -rf build/*",
+    "build": "tsc && tsc-alias -p tsconfig.json",
+    "postbuild": "chmod +x build/index.js",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "bin": {
+    "mcp-icon": "./build/index.js"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "files": ["build"],
+  "keywords": ["antv", "mcp", "icon", "svg", "search", "infographic"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hustcc/mcp-icon"
+  },
+  "author": {
+    "name": "hustcc"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "cors": "^2.8.5",
+    "express": "^5.1.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.3",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "tsc-alias": "^1.8.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  }
+}