arcane-assets-mcp 0.2.1

package/USAGE_EXAMPLE.md

@@ -0,0 +1,284 @@
+# Usage Example
+
+This document demonstrates how an agent would use the `arcane-assets` MCP server to discover and download game assets.
+
+## Scenario: Building a Platformer Game
+
+An agent is tasked with creating a platformer demo and needs assets.
+
+### Step 1: Discover Available Assets
+
+**Agent searches for platformer assets:**
+
+```typescript
+// MCP Tool Call
+search_kenney_assets({
+  query: "platformer",
+  type: "2d-sprites"
+})
+```
+
+**Result:**
+```json
+{
+  "packs": [
+    {
+      "id": "platformer-pack-redux",
+      "name": "Platformer Pack Redux (360 assets)",
+      "description": "Complete platformer art pack with characters, tiles, items, and enemies",
+      "type": ["2d-sprites", "tilesets"],
+      "license": "CC0",
+      "tags": ["platformer", "character", "tiles", "pixel-art"]
+    },
+    {
+      "id": "pixel-platformer",
+      "name": "Pixel Platformer (220 assets)",
+      "description": "Pixel art platformer pack with characters, tiles, and decorations",
+      "type": ["2d-sprites", "tilesets"],
+      "license": "CC0",
+      "tags": ["platformer", "pixel-art", "retro"]
+    },
+    {
+      "id": "abstract-platformer",
+      "name": "Abstract Platformer (250 assets)",
+      "description": "Colorful abstract shapes for platformer games",
+      "type": ["2d-sprites"],
+      "license": "CC0",
+      "tags": ["platformer", "abstract", "shapes"]
+    }
+  ],
+  "total": 3
+}
+```
+
+### Step 2: Get Detailed Information
+
+**Agent examines the top result:**
+
+```typescript
+// MCP Tool Call
+get_kenney_asset({
+  id: "platformer-pack-redux"
+})
+```
+
+**Result:**
+```json
+{
+  "id": "platformer-pack-redux",
+  "name": "Platformer Pack Redux (360 assets)",
+  "description": "Complete platformer art pack with characters, tiles, items, and enemies",
+  "source": "kenney",
+  "type": ["2d-sprites", "tilesets"],
+  "license": "CC0",
+  "url": "https://kenney.nl/assets/platformer-pack-redux",
+  "downloadUrl": "https://kenney.nl/content/3-assets/145-platformer-pack-redux/platformerpackredux.zip",
+  "tags": ["platformer", "character", "tiles", "pixel-art"]
+}
+```
+
+### Step 3: Download the Asset Pack
+
+**Agent downloads to project assets directory:**
+
+```typescript
+// MCP Tool Call
+download_kenney_asset({
+  id: "platformer-pack-redux",
+  destination: "./demos/platformer/assets"
+})
+```
+
+**Result:**
+```json
+{
+  "success": true,
+  "path": "./demos/platformer/assets/platformerpackredux.zip"
+}
+```
+
+### Step 4: Extract and Organize
+
+**Agent extracts the downloaded archive:**
+
+```bash
+# Agent runs bash command
+cd demos/platformer/assets
+unzip platformerpackredux.zip
+rm platformerpackredux.zip
+```
+
+**Result structure:**
+```
+demos/platformer/assets/
+└── platformerpackredux/
+    ├── PNG/
+    │   ├── Players/
+    │   ├── Tiles/
+    │   ├── Items/
+    │   └── Enemies/
+    ├── Spritesheet/
+    │   └── spritesheet.png
+    └── License.txt
+```
+
+### Step 5: Integrate into Game Code
+
+**Agent updates the platformer demo to use the assets:**
+
+```typescript
+// demos/platformer/platformer-visual.ts
+import { loadTexture } from "../../runtime/rendering/texture.ts";
+import { drawSprite } from "../../runtime/rendering/sprites.ts";
+
+// Load sprite sheet
+const spriteSheet = loadTexture("./assets/platformerpackredux/Spritesheet/spritesheet.png");
+
+// Use in game
+function renderPlayer(state: GameState) {
+  const player = state.entities.player;
+
+  drawSprite({
+    textureId: spriteSheet,
+    x: player.position.x,
+    y: player.position.y,
+    width: 32,
+    height: 32,
+    // Calculate UV coordinates for player sprite in sheet
+    uvX: 0,
+    uvY: 0,
+    uvWidth: 32,
+    uvHeight: 32,
+  });
+}
+```
+
+### Step 6: Add UI Assets
+
+**Agent searches for UI elements:**
+
+```typescript
+// MCP Tool Call
+search_kenney_assets({
+  query: "ui",
+  type: "ui"
+})
+```
+
+**Agent downloads UI pack:**
+
+```typescript
+// MCP Tool Call
+download_kenney_asset({
+  id: "ui-pack",
+  destination: "./demos/platformer/assets"
+})
+```
+
+### Step 7: Add Sound Effects
+
+**Agent searches for audio:**
+
+```typescript
+// MCP Tool Call
+search_kenney_assets({
+  query: "impact",
+  type: "audio"
+})
+```
+
+**Agent downloads sound pack:**
+
+```typescript
+// MCP Tool Call
+download_kenney_asset({
+  id: "impact-sounds",
+  destination: "./demos/platformer/assets"
+})
+```
+
+## Scenario: Building a Roguelike
+
+An agent needs dungeon assets for a roguelike game.
+
+### Quick Search and Download
+
+```typescript
+// Search for dungeon assets
+search_kenney_assets({ query: "dungeon", type: "tilesets" })
+
+// Results: tiny-dungeon, roguelike-rpg-pack, 1-bit-pack
+
+// Download tiny-dungeon for minimal pixel art style
+download_kenney_asset({
+  id: "tiny-dungeon",
+  destination: "./demos/roguelike/assets"
+})
+```
+
+## Benefits for Agent Workflow
+
+1. **No manual browsing** - Agent searches programmatically
+2. **Metadata-driven decisions** - Agent evaluates options based on structured data
+3. **Automated downloads** - No copy-paste of URLs or manual clicks
+4. **Consistent organization** - Assets downloaded to specified directories
+5. **License-safe** - All Kenney assets are CC0, no attribution concerns
+
+## Interactive Discovery
+
+**Agent can explore the catalog systematically:**
+
+```typescript
+// List all available types
+get_asset_types()
+// Returns: ["2d-sprites", "3d-models", "audio", "fonts", "tilesets", "ui", "vfx"]
+
+// List all searchable tags
+get_tags()
+// Returns: ["1-bit", "abstract", "audio", "blocks", "button", "dungeon", ...]
+
+// Browse full catalog
+list_kenney_assets()
+// Returns: All 24 curated packs with metadata
+```
+
+## Error Handling
+
+**If asset not found:**
+
+```typescript
+get_kenney_asset({ id: "nonexistent-pack" })
+```
+
+**Result:**
+```json
+{
+  "content": [{ "type": "text", "text": "Asset pack 'nonexistent-pack' not found" }],
+  "isError": true
+}
+```
+
+**If download fails:**
+
+```typescript
+download_kenney_asset({
+  id: "platformer-pack-redux",
+  destination: "/invalid/path"
+})
+```
+
+**Result:**
+```json
+{
+  "success": false,
+  "error": "EACCES: permission denied, mkdir '/invalid/path'"
+}
+```
+
+## Next Steps
+
+1. **Test the MCP server** - Use Claude Code to interact with the tools
+2. **Extend catalog** - Add more Kenney packs as needed
+3. **Add Freesound.org** - Integrate sound effects API
+4. **Add itch.io** - Connect to community asset marketplace
+5. **Create `/add-asset` skill** - Build interactive CLI skill using MCP tools

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { listKenneyAssets, searchKenneyAssets, getKenneyAsset, downloadKenneyAsset, getAssetTypes, getTags, } from "./kenney.js";
+/**
+ * Arcane Assets MCP Server
+ *
+ * Provides tools for discovering and downloading game assets from:
+ * - Kenney.nl (CC0 assets)
+ * - Freesound.org (future)
+ * - itch.io (future)
+ */
+const server = new Server({
+    name: "arcane-assets",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+/**
+ * Define available tools
+ */
+const TOOLS = [
+    {
+        name: "list_kenney_assets",
+        description: "List all available Kenney.nl asset packs. Returns the full catalog with metadata for each pack.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "search_kenney_assets",
+        description: "Search Kenney.nl asset packs by keyword. Searches across pack names, descriptions, and tags.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search query (e.g., 'platformer', 'dungeon', 'ui')",
+                },
+                type: {
+                    type: "string",
+                    enum: [
+                        "2d-sprites",
+                        "3d-models",
+                        "ui",
+                        "audio",
+                        "fonts",
+                        "vfx",
+                        "tilesets",
+                        "textures",
+                    ],
+                    description: "Optional: filter by asset type",
+                },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "get_kenney_asset",
+        description: "Get detailed information about a specific Kenney.nl asset pack by ID.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: {
+                    type: "string",
+                    description: "Asset pack ID (e.g., 'platformer-pack-redux', 'tiny-dungeon')",
+                },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "download_kenney_asset",
+        description: "Download a Kenney.nl asset pack to a local directory. Returns the path to the downloaded file.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: {
+                    type: "string",
+                    description: "Asset pack ID (e.g., 'platformer-pack-redux', 'tiny-dungeon')",
+                },
+                destination: {
+                    type: "string",
+                    description: "Destination directory path (e.g., './assets', './downloads')",
+                },
+            },
+            required: ["id", "destination"],
+        },
+    },
+    {
+        name: "get_asset_types",
+        description: "Get a list of all asset types available in the Kenney catalog.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "get_tags",
+        description: "Get a list of all tags used in the Kenney catalog. Useful for discovering search keywords.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+];
+/**
+ * Handle list_tools request
+ */
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+});
+/**
+ * Handle call_tool request
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "list_kenney_assets": {
+                const packs = listKenneyAssets();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(packs, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "search_kenney_assets": {
+                const { query, type } = args;
+                const result = searchKenneyAssets(query, type);
+                let responseText = JSON.stringify(result, null, 2);
+                // Add helpful message if no results found
+                if (result.total === 0 && result.suggestions) {
+                    responseText = `No results found for "${query}".\n\nSuggestions:\n${result.suggestions.map(s => `  • ${s}`).join('\n')}\n\n` + responseText;
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: responseText,
+                        },
+                    ],
+                };
+            }
+            case "get_kenney_asset": {
+                const { id } = args;
+                const pack = getKenneyAsset(id);
+                if (!pack) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Asset pack '${id}' not found`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(pack, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "download_kenney_asset": {
+                const { id, destination } = args;
+                const result = await downloadKenneyAsset(id, destination);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                    isError: !result.success,
+                };
+            }
+            case "get_asset_types": {
+                const types = getAssetTypes();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(types, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "get_tags": {
+                const tags = getTags();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(tags, null, 2),
+                        },
+                    ],
+                };
+            }
+            default:
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Unknown tool: ${name}`,
+                        },
+                    ],
+                    isError: true,
+                };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+/**
+ * Start the server
+ */
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Arcane Assets MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/kenney-catalog.d.ts

@@ -0,0 +1,8 @@
+import { AssetPack } from "./types.js";
+/**
+ * Curated catalog of popular Kenney.nl asset packs
+ *
+ * All Kenney assets are CC0 (public domain) - no attribution required.
+ * Download URLs point to kenney.nl direct download links.
+ */
+export declare const KENNEY_CATALOG: AssetPack[];