@freevectoricons/mcp 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreeVectorIcons
+
+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,111 @@
+# fvi-mcp
+
+MCP server for [FreeVectorIcons](https://freevectoricons.com) design collections.
+
+Connects Cursor, Claude Desktop, and other MCP clients to one FVI collection — icons, uploaded SVGs, strategy briefs, DESIGN.md, and related project files. Scoped to a single collection token.
+
+npm: [`@freevectoricons/mcp`](https://www.npmjs.com/package/@freevectoricons/mcp)
+
+## Why this exists
+
+The usual agent workflow for icons is: prompt → inline SVG → paste into code. That breaks down quickly — inconsistent paths, missing `viewBox`, made-up attribution, different output on every retry.
+
+FVI stores assets in a collection with stable ids, tags, and license fields. This server lets agents **search and fetch what's already approved** instead of generating new SVG from scratch.
+
+It's a stdio MCP wrapper over the FVI HTTP API. Responses are metadata-first JSON; file bytes are fetched only when a tool asks for content or a download URL.
+
+## Setup
+
+You need a FreeVectorIcons account and an MCP token for a design collection.
+
+1. Open a collection at [freevectoricons.com](https://freevectoricons.com)
+2. **Integrations** → **Setup MCP**
+3. Create a token; copy the collection ID and secret
+
+Add to `.cursor/mcp.json` (or your client's MCP config):
+
+```json
+{
+  "mcpServers": {
+    "freevectoricons": {
+      "command": "npx",
+      "args": ["-y", "@freevectoricons/mcp"],
+      "env": {
+        "FVI_API_URL": "https://freevectoricons.com/api",
+        "FVI_COLLECTION_ID": "<collection-id>",
+        "FVI_TOKEN": "<collection-token>"
+      }
+    }
+  }
+}
+```
+
+Use `npx`, not `pnpm run`. Package managers print lifecycle text to stdout, which breaks MCP stdio transport.
+
+See [`mcp.json.example`](./mcp.json.example) for a copy-paste template.
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `FVI_TOKEN` | yes | — | Collection-scoped MCP token |
+| `FVI_COLLECTION_ID` | yes | — | Collection id |
+| `FVI_API_URL` | no | `http://localhost:5001/api` | API base URL (include `/api`) |
+
+For production: `FVI_API_URL=https://freevectoricons.com/api`
+
+## Tools
+
+### Read
+
+| Tool | What it does |
+|------|----------------|
+| `get_design_collection_context` | Collection metadata, strategy brief, asset summary |
+| `list_design_collection_assets` | All assets (metadata only) |
+| `search_design_collection_assets` | Search by name, tag, category, or style |
+| `get_design_asset` | One asset by id |
+| `get_design_asset_content` | Inline UTF-8 for catalog SVGs, uploaded SVGs, Markdown |
+| `get_design_asset_download_url` | Short-lived URL for PNG, PDF, and other binaries |
+
+### Write
+
+| Tool | What it does |
+|------|----------------|
+| `create_design_asset_upload` | Create asset record + signed upload target |
+| `park_design_asset` | Upload inline text or base64 into the collection |
+| `create_design_asset_version` | Upload a new version of an existing asset |
+
+Binary files are not embedded in MCP responses. Agents should use metadata + download URLs for images and PDFs.
+
+Optional write metadata: `drlProjectId`, `drlAssetType`, `documentType`, `tags`.
+
+## Development
+
+```bash
+npm install
+npm run build
+node dist/mcp-server.mjs
+```
+
+To run from a local checkout in Cursor:
+
+```json
+"args": ["-y", "file:/absolute/path/to/fvi-mcp"]
+```
+
+Build first (`npm run build`). The bundled entry is `dist/mcp-server.mjs`.
+
+## What this is not
+
+- **Not a global icon search API.** One token, one collection.
+- **Not a guarantee of pixel-perfect icons.** Catalog SVGs are AI-generated and refined on a schedule; check assets before production use.
+- **Not a replacement for your design review.** It moves files and metadata; it doesn't judge brand fit.
+
+## Related
+
+- [freevectoricons.com/mcp](https://freevectoricons.com/mcp) — product docs
+- [ai-icon-generator](https://github.com/FreeVectorIcons/ai-icon-generator) — open pipeline that produces catalog icons
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/mcp-server.mjs

@@ -21116,7 +21116,7 @@ function withDrlMetadata(input) {
 }
 var server = new McpServer({
   name: "freevectoricons",
-  version: "0.1.0"
+  version: "0.1.2"
 });
 server.registerTool(
   "get_design_collection_context",

package/package.json

@@ -1,8 +1,25 @@
 {
   "name": "@freevectoricons/mcp",
-  "version": "0.1.0",
-  "description": "FreeVectorIcons design collection MCP server for Cursor and other MCP clients",
+  "version": "0.1.2",
+  "description": "MCP server for FreeVectorIcons design collections",
+  "author": "Hemanta Sapkota <hemanta@freevectoricons.com>",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FreeVectorIcons/fvi-mcp.git"
+  },
+  "homepage": "https://freevectoricons.com/mcp",
+  "bugs": {
+    "url": "https://github.com/FreeVectorIcons/fvi-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "freevectoricons",
+    "svg",
+    "icons",
+    "cursor"
+  ],
   "type": "module",
   "bin": {
     "fvi-mcp": "./dist/mcp-server.mjs"
@@ -10,6 +27,11 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "node ./build.mjs",
+    "prepublishOnly": "pnpm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.25.76"
@@ -24,9 +46,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "node ./build.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
   }
-}
+}