ailibrary-mcp 1.0.0

package/README.md

@@ -0,0 +1,113 @@
+# ailibrary-mcp
+
+[![npm version](https://img.shields.io/npm/v/ailibrary-mcp.svg)](https://www.npmjs.com/package/ailibrary-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/ailibrary-mcp.svg)](https://www.npmjs.com/package/ailibrary-mcp)
+
+MCP (Model Context Protocol) server for [AILibrary](https://ailibrary-m43k.polsia.app) — the AI-native media asset library.
+
+Gives AI agents the ability to **search, discover, and download** licensed videos, images, and audio clips autonomously, with automatic credit billing.
+
+## Installation
+
+```bash
+npx -y ailibrary-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g ailibrary-mcp
+```
+
+## Configuration
+
+Add to your MCP client config (Claude Desktop, Cursor, Windsurf, Cline, etc.):
+
+### Using environment variable (recommended)
+
+```json
+{
+  "mcpServers": {
+    "ailibrary": {
+      "command": "npx",
+      "args": ["-y", "ailibrary-mcp"],
+      "env": {
+        "AILIBRARY_API_KEY": "alib_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Passing API key per tool call
+
+```json
+{
+  "mcpServers": {
+    "ailibrary": {
+      "command": "npx",
+      "args": ["-y", "ailibrary-mcp"]
+    }
+  }
+}
+```
+
+Then pass `api_key` in each tool call directly.
+
+Get an API key at [ailibrary-m43k.polsia.app](https://ailibrary-m43k.polsia.app).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_assets` | Search the media library by keyword, with optional type filter (`video`, `image`, `audio`) |
+| `download_asset` | Download an asset by ID (deducts credits from your balance) |
+| `check_balance` | Check your remaining credit balance |
+
+## Usage Example
+
+Once connected, your AI agent can:
+
+```
+Search for 3 drone nature videos suitable for a product intro
+→ Uses search_assets({ api_key: "alib_...", query: "drone nature", type: "video" })
+
+Download the best match
+→ Uses download_asset({ api_key: "alib_...", asset_id: 42 })
+
+Check remaining credits
+→ Uses check_balance({ api_key: "alib_..." })
+```
+
+## API Reference
+
+All tools accept an `api_key` parameter (or read `AILIBRARY_API_KEY` from the environment).
+
+### `search_assets`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `api_key` | string | yes* | Your AILibrary API key |
+| `query` | string | yes | Search terms |
+| `type` | string | no | Filter by type: `video`, `image`, `audio` |
+| `limit` | number | no | Max results (default: 10) |
+
+### `download_asset`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `api_key` | string | yes* | Your AILibrary API key |
+| `asset_id` | number | yes | ID from search results |
+
+### `check_balance`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `api_key` | string | yes* | Your AILibrary API key |
+
+*\* Or set `AILIBRARY_API_KEY` environment variable*
+
+## License
+
+MIT
+

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const API_BASE_URL = "https://ailibrary-m43k.polsia.app";
+// ── HTTP helper ───────────────────────────────────────────────────────────────
+async function apiPost(path, apiKey, body) {
+    const response = await fetch(`${API_BASE_URL}${path}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "x-api-key": apiKey,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const err = (await response
+            .json()
+            .catch(() => ({ error: response.statusText })));
+        throw new Error(`AILibrary API error ${response.status}: ${err.error ?? JSON.stringify(err)}`);
+    }
+    return response.json();
+}
+// ── Server setup ──────────────────────────────────────────────────────────────
+const server = new Server({ name: "ailibrary", version: "1.0.0" }, { capabilities: { tools: {} } });
+// ── tools/list ────────────────────────────────────────────────────────────────
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "search_assets",
+            description: "Search the AILibrary media library for videos, images, and audio. " +
+                "Returns assets with IDs, titles, types, preview URLs, and credit costs. " +
+                "Use the asset ID from results to call download_asset.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    api_key: {
+                        type: "string",
+                        description: "Your AILibrary API key (starts with 'alib_')",
+                    },
+                    query: {
+                        type: "string",
+                        description: "Search query (e.g. 'office background', 'nature drone shot', 'upbeat corporate music')",
+                    },
+                    type: {
+                        type: "string",
+                        enum: ["video", "image", "audio"],
+                        description: "Filter by asset type (optional)",
+                    },
+                    limit: {
+                        type: "number",
+                        description: "Max results (default 20, max 100)",
+                    },
+                },
+                required: ["api_key", "query"],
+            },
+        },
+        {
+            name: "download_asset",
+            description: "Download a specific media asset by its ID. Deducts credits from your balance and returns the download URL.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    api_key: {
+                        type: "string",
+                        description: "Your AILibrary API key",
+                    },
+                    asset_id: {
+                        type: "number",
+                        description: "Asset ID obtained from search_assets results",
+                    },
+                },
+                required: ["api_key", "asset_id"],
+            },
+        },
+        {
+            name: "check_balance",
+            description: "Verify your AILibrary API key and check that it's working. Returns confirmation that the key is valid.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    api_key: {
+                        type: "string",
+                        description: "Your AILibrary API key",
+                    },
+                },
+                required: ["api_key"],
+            },
+        },
+    ],
+}));
+// ── tools/call ────────────────────────────────────────────────────────────────
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (!args) {
+        return {
+            content: [{ type: "text", text: "Error: no arguments provided" }],
+            isError: true,
+        };
+    }
+    try {
+        switch (name) {
+            case "search_assets": {
+                const { api_key, query, type, limit } = args;
+                if (!api_key)
+                    throw new Error("api_key is required");
+                if (!query)
+                    throw new Error("query is required");
+                const body = { query };
+                if (type !== undefined)
+                    body["type"] = type;
+                if (limit !== undefined)
+                    body["limit"] = limit;
+                const result = await apiPost("/v1/assets/search", api_key, body);
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result, null, 2) },
+                    ],
+                };
+            }
+            case "download_asset": {
+                const { api_key, asset_id } = args;
+                if (!api_key)
+                    throw new Error("api_key is required");
+                if (asset_id === undefined || asset_id === null)
+                    throw new Error("asset_id is required");
+                const result = await apiPost(`/v1/assets/${asset_id}/download`, api_key, {});
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result, null, 2) },
+                    ],
+                };
+            }
+            case "check_balance": {
+                const { api_key } = args;
+                if (!api_key)
+                    throw new Error("api_key is required");
+                // Use a minimal search to verify the key works
+                await apiPost("/v1/assets/search", api_key, {
+                    query: "a",
+                    limit: 1,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                valid: true,
+                                message: "API key is valid. Use search_assets to find media assets.",
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            default:
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Unknown tool: ${name}`,
+                        },
+                    ],
+                    isError: true,
+                };
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ── Connect and run ───────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,oCAAoC,CAAC;AAE5C,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAmCzD,iFAAiF;AAEjF,KAAK,UAAU,OAAO,CACpB,IAAY,EACZ,MAAc,EACd,IAA6B;IAE7B,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,YAAY,GAAG,IAAI,EAAE,EAAE;QACrD,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,WAAW,EAAE,MAAM;SACpB;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC3B,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,CAAC,MAAM,QAAQ;aACxB,IAAI,EAAE;aACN,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,CAAqB,CAAC;QACtE,MAAM,IAAI,KAAK,CACb,uBAAuB,QAAQ,CAAC,MAAM,KAAK,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAC9E,CAAC;IACJ,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,EAAgB,CAAC;AACvC,CAAC;AAED,iFAAiF;AAEjF,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,EACvC,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAC;AAEF,iFAAiF;AAEjF,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IAC5D,KAAK,EAAE;QACL;YACE,IAAI,EAAE,eAAe;YACrB,WAAW,EACT,oEAAoE;gBACpE,0EAA0E;gBAC1E,uDAAuD;YACzD,WAAW,EAAE;gBACX,IAAI,EAAE,QAAiB;gBACvB,UAAU,EAAE;oBACV,OAAO,EAAE;wBACP,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,8CAA8C;qBAC5D;oBACD,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,WAAW,EACT,wFAAwF;qBAC3F;oBACD,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAQ;wBACd,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC;wBACjC,WAAW,EAAE,iCAAiC;qBAC/C;oBACD,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,mCAAmC;qBACjD;iBACF;gBACD,QAAQ,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC;aAC/B;SACF;QACD;YACE,IAAI,EAAE,gBAAgB;YACtB,WAAW,EACT,4GAA4G;YAC9G,WAAW,EAAE;gBACX,IAAI,EAAE,QAAiB;gBACvB,UAAU,EAAE;oBACV,OAAO,EAAE;wBACP,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,wBAAwB;qBACtC;oBACD,QAAQ,EAAE;wBACR,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,8CAA8C;qBAC5D;iBACF;gBACD,QAAQ,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;aAClC;SACF;QACD;YACE,IAAI,EAAE,eAAe;YACrB,WAAW,EACT,wGAAwG;YAC1G,WAAW,EAAE;gBACX,IAAI,EAAE,QAAiB;gBACvB,UAAU,EAAE;oBACV,OAAO,EAAE;wBACP,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,wBAAwB;qBACtC;iBACF;gBACD,QAAQ,EAAE,CAAC,SAAS,CAAC;aACtB;SACF;KACF;CACF,CAAC,CAAC,CAAC;AAEJ,iFAAiF;AAEjF,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;IAChE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAEjD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,8BAA8B,EAAE,CAAC;YAC1E,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,eAAe,CAAC,CAAC,CAAC;gBACrB,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAKvC,CAAC;gBACF,IAAI,CAAC,OAAO;oBAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;gBACrD,IAAI,CAAC,KAAK;oBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;gBAEjD,MAAM,IAAI,GAA4B,EAAE,KAAK,EAAE,CAAC;gBAChD,IAAI,IAAI,KAAK,SAAS;oBAAE,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;gBAC5C,IAAI,KAAK,KAAK,SAAS;oBAAE,IAAI,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;gBAE/C,MAAM,MAAM,GAAG,MAAM,OAAO,CAC1B,mBAAmB,EACnB,OAAO,EACP,IAAI,CACL,CAAC;gBACF,OAAO;oBACL,OAAO,EAAE;wBACP,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;qBACjE;iBACF,CAAC;YACJ,CAAC;YAED,KAAK,gBAAgB,CAAC,CAAC,CAAC;gBACtB,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,IAG7B,CAAC;gBACF,IAAI,CAAC,OAAO;oBAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;gBACrD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI;oBAC7C,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;gBAE1C,MAAM,MAAM,GAAG,MAAM,OAAO,CAC1B,cAAc,QAAQ,WAAW,EACjC,OAAO,EACP,EAAE,CACH,CAAC;gBACF,OAAO;oBACL,OAAO,EAAE;wBACP,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;qBACjE;iBACF,CAAC;YACJ,CAAC;YAED,KAAK,eAAe,CAAC,CAAC,CAAC;gBACrB,MAAM,EAAE,OAAO,EAAE,GAAG,IAA2B,CAAC;gBAChD,IAAI,CAAC,OAAO;oBAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;gBAErD,+CAA+C;gBAC/C,MAAM,OAAO,CAAiB,mBAAmB,EAAE,OAAO,EAAE;oBAC1D,KAAK,EAAE,GAAG;oBACV,KAAK,EAAE,CAAC;iBACT,CAAC,CAAC;gBACH,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAClB;gCACE,KAAK,EAAE,IAAI;gCACX,OAAO,EACL,2DAA2D;6BAC9D,EACD,IAAI,EACJ,CAAC,CACF;yBACF;qBACF;iBACF,CAAC;YACJ,CAAC;YAED;gBACE,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,iBAAiB,IAAI,EAAE;yBAC9B;qBACF;oBACD,OAAO,EAAE,IAAI;iBACd,CAAC;QACN,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC;YAC/D,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,iFAAiF;AAEjF,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "ailibrary-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for AILibrary - AI-native video and media asset library",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ailibrary-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "media",
+    "video",
+    "assets",
+    "library"
+  ],
+  "author": "AILibrary",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Polsia-Inc/ailibrary.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://ailibrary-m43k.polsia.app",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "@types/node": "^20.11.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}