arcane-assets-mcp 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## [0.2.0] - 2026-02-10
+
+### Added
+- **Smart synonym search** - Automatically understands related terms (e.g., "kitty" → "cat", "unicorn" → "horse")
+- **Content-aware search** - Searches inside packs for specific sprites and assets
+- **Search suggestions** - Provides helpful recommendations when no results found
+- **Content metadata** - Added `contents` field to asset packs listing specific sprites inside
+- **Relevance scoring** - Search results now sorted by relevance (exact matches rank higher)
+- **5 new asset packs:**
+  - `animal-pack-redux` - 160 cute cartoon animals (cats, dogs, farm animals)
+  - `creature-mixer` - 100 mix-and-match monster parts
+  - `tiny-battle` - 234 medieval battle units and fantasy creatures
+  - `fish-pack` - 48 underwater creatures
+  - `toon-characters-1` - 16 cartoon characters
+
+### Changed
+- Expanded catalog from 24 to 25+ packs
+- Search algorithm now prioritizes content matches over description matches
+- Improved search response format with helpful messages for empty results
+
+### Fixed
+- Searches like "kitty", "unicorn", "wizard" now return relevant results
+- Search no longer limited to exact keyword matches in pack names
+
+## [0.1.0] - 2026-01-XX
+
+### Added
+- Initial release with 24 curated Kenney.nl asset packs
+- 6 MCP tools: list, search, get, download, types, tags
+- CC0 licensed assets (public domain)
+- HTTP download support with redirect handling

package/QUICKSTART.md

@@ -0,0 +1,209 @@
+# Quick Start: Asset MCP Server v0.2.0
+
+## What Changed
+
+The asset MCP server now reliably finds assets even when you use informal terms like "kitty" or "unicorn".
+
+### Before (v0.1.0)
+```
+Search "kitty" → No results ❌
+Search "unicorn" → No results ❌
+Search "xyz123" → Empty result, no help ❌
+```
+
+### After (v0.2.0)
+```
+Search "kitty" → Animal Pack Redux (contains cats) ✅
+Search "unicorn" → Animal Pack Redux (contains horses) ✅
+Search "xyz123" → Helpful suggestions ✅
+```
+
+## Installation
+
+1. **Rebuild the server** (if you haven't already):
+   ```bash
+   cd mcp/arcane-assets
+   npm install
+   npm run build
+   ```
+
+2. **Configure in Claude Code** (`~/.claude/mcp.json`):
+   ```json
+   {
+     "mcpServers": {
+       "arcane-assets": {
+         "command": "node",
+         "args": ["/Users/arkham/project/arcane/mcp/arcane-assets/dist/index.js"],
+         "disabled": false
+       }
+     }
+   }
+   ```
+
+3. **Restart Claude Code** to load the updated server
+
+## Example Usage
+
+### Searching for Animals
+
+**You say:** "I want to add kitty and unicorn sprites to my game"
+
+**Claude Code will:**
+```typescript
+// 1. Search for kitty sprites
+search_kenney_assets({ query: "kitty" })
+// → Finds Animal Pack Redux with cats
+
+// 2. Search for unicorn sprites
+search_kenney_assets({ query: "unicorn" })
+// → Finds Animal Pack Redux with horses (unicorns are fantasy horses)
+
+// 3. Download the pack
+download_kenney_asset({
+  id: "animal-pack-redux",
+  destination: "./assets"
+})
+// → Downloads animalpackredux.zip to ./assets/
+
+// 4. Extract and integrate
+// Claude extracts the ZIP and updates your game code
+```
+
+### Searching for Game Elements
+
+**You say:** "Add wizard and dragon sprites"
+
+**Claude Code will:**
+```typescript
+search_kenney_assets({ query: "wizard" })
+// → Finds: Tiny Battle, Roguelike RPG Pack
+
+search_kenney_assets({ query: "dragon" })
+// → Finds: Tiny Battle (highest relevance)
+
+download_kenney_asset({
+  id: "tiny-battle",
+  destination: "./assets"
+})
+```
+
+### Exploring the Catalog
+
+**You say:** "Show me all animal packs"
+
+**Claude Code will:**
+```typescript
+search_kenney_assets({ query: "animal" })
+// → Returns 4 packs:
+//   - Animal Pack Redux (160 assets)
+//   - Creature Mixer (100 assets)
+//   - Tiny Battle (234 assets)
+//   - Fish Pack (48 assets)
+```
+
+## What's Inside Packs
+
+The server now knows what's inside each pack:
+
+### Animal Pack Redux (160 assets)
+**Contains:** cat, dog, bird, chicken, cow, pig, sheep, horse, rabbit, mouse, bear, fox
+
+### Tiny Battle (234 assets)
+**Contains:** knight, archer, cavalry, wizard, dragon, skeleton, orc
+
+### Roguelike RPG Pack (1366 assets)
+**Contains:** knight, wizard, skeleton, orc, chest, potion, weapon, armor, tiles, ui
+
+### Platformer Pack Redux (360 assets)
+**Contains:** player, enemies, slime, bee, snail, tiles, coins, gems, spikes
+
+## Synonym Support
+
+The server understands these related terms:
+
+| You search for | Server understands as |
+|----------------|----------------------|
+| kitty, kitten | cat |
+| puppy | dog |
+| pony, unicorn | horse |
+| mage, sorcerer | wizard |
+| warrior, paladin | knight |
+| creature, beast | monster |
+| treasure, money | coin |
+| jewel, crystal | gem |
+
+## Helpful Suggestions
+
+When searches fail, you get guidance:
+
+```typescript
+search_kenney_assets({ query: "nonexistent" })
+```
+
+**Response:**
+```
+No results found for "nonexistent".
+
+Suggestions:
+  • Try browsing by type: 2d-sprites, audio, fonts, tilesets, ui, vfx
+  • Popular packs: platformer-pack-redux, tiny-dungeon, animal-pack-redux, ui-pack
+```
+
+## Testing
+
+Run the validation script to verify everything works:
+
+```bash
+cd mcp/arcane-assets
+node test-search.js
+```
+
+Expected output:
+```
+✅ PASS - Found packs containing cats/kitties
+✅ PASS - Found packs containing horses/unicorns
+✅ PASS - Found animal packs
+✅ PASS - Provided helpful suggestions when no results found
+
+Total packs: 25
+Packs with content metadata: 10
+```
+
+## New Asset Packs
+
+Five new packs added in this version:
+
+1. **Animal Pack Redux** - Cute cartoon animals (cats, dogs, farm animals)
+2. **Creature Mixer** - Mix-and-match monster parts
+3. **Tiny Battle** - Medieval units and fantasy creatures
+4. **Fish Pack** - Underwater creatures
+5. **Toon Characters 1** - Cartoon character sprites
+
+## Troubleshooting
+
+### "MCP server not found"
+- Make sure the path in `mcp.json` points to the correct location
+- Restart Claude Code after config changes
+
+### "No results for [query]"
+- Check the suggestions provided in the response
+- Try browsing all packs: `list_kenney_assets()`
+- Try searching by type: `search_kenney_assets({ query: "ui", type: "ui" })`
+
+### "Download failed"
+- Check destination directory exists and is writable
+- Verify internet connection (downloads from kenney.nl)
+- Check disk space
+
+## Next Steps
+
+1. Try searching for assets you need
+2. Download packs to your game's assets directory
+3. Extract ZIP files and integrate sprites into your game
+4. Share feedback on what works and what doesn't
+
+## Support
+
+- Documentation: `mcp/arcane-assets/README.md`
+- Testing guide: `mcp/arcane-assets/TESTING.md`
+- Changelog: `mcp/arcane-assets/CHANGELOG.md`

package/README.md

@@ -0,0 +1,247 @@
+# Arcane Assets MCP Server
+
+MCP server for discovering and downloading game assets for the Arcane game engine.
+
+## Features
+
+### Kenney.nl Integration ✅
+
+- **25+ curated asset packs** covering platformers, RPGs, shooters, puzzles, UI, audio, animals, and more
+- **CC0 (public domain)** - no attribution required, use in any project
+- **6 MCP tools** for browsing, searching, and downloading assets
+- **60,000+ total assets** across all packs
+- **Smart search** with synonym support (e.g., "kitty" finds cat assets, "unicorn" finds horse assets)
+- **Content-aware search** - searches inside packs for specific sprites (cat, dog, wizard, etc.)
+- **Helpful suggestions** when searches return no results
+
+### Coming Soon
+
+- Freesound.org integration (sound effects with API)
+- itch.io integration (community assets)
+
+## Installation
+
+From the `mcp/arcane-assets` directory:
+
+```bash
+npm install
+npm run build
+```
+
+## Configuration
+
+Add to your Claude Code MCP settings (`~/.claude/mcp.json` or project-specific `.claude/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "arcane-assets": {
+      "command": "node",
+      "args": ["/absolute/path/to/arcane/mcp/arcane-assets/dist/index.js"],
+      "disabled": false
+    }
+  }
+}
+```
+
+Replace `/absolute/path/to/arcane` with the actual path to your Arcane repository.
+
+## Available Tools
+
+### `list_kenney_assets`
+
+List all available Kenney.nl asset packs.
+
+**Returns:** Array of asset packs with metadata (name, description, type, license, download URL, tags)
+
+**Example:**
+```typescript
+// Lists all 24 curated packs
+list_kenney_assets()
+```
+
+### `search_kenney_assets`
+
+Search Kenney.nl asset packs by keyword.
+
+**Parameters:**
+- `query` (string, required): Search query
+- `type` (string, optional): Filter by asset type (`2d-sprites`, `ui`, `audio`, `fonts`, `vfx`, `tilesets`, `textures`)
+
+**Returns:** Search results with matching packs
+
+**Examples:**
+```typescript
+// Find platformer assets
+search_kenney_assets({ query: "platformer" })
+
+// Find UI elements
+search_kenney_assets({ query: "button", type: "ui" })
+
+// Find audio
+search_kenney_assets({ query: "impact", type: "audio" })
+```
+
+### `get_kenney_asset`
+
+Get detailed information about a specific asset pack.
+
+**Parameters:**
+- `id` (string, required): Asset pack ID
+
+**Returns:** Asset pack metadata
+
+**Example:**
+```typescript
+get_kenney_asset({ id: "tiny-dungeon" })
+```
+
+### `download_kenney_asset`
+
+Download an asset pack to a local directory.
+
+**Parameters:**
+- `id` (string, required): Asset pack ID
+- `destination` (string, required): Destination directory path
+
+**Returns:** Download result with success status and file path
+
+**Example:**
+```typescript
+// Download to project assets directory
+download_kenney_asset({
+  id: "platformer-pack-redux",
+  destination: "./assets"
+})
+```
+
+### `get_asset_types`
+
+Get all asset types available in the catalog.
+
+**Returns:** Array of asset type strings
+
+### `get_tags`
+
+Get all tags used in the catalog (useful for discovering search keywords).
+
+**Returns:** Array of tag strings
+
+## Search Features
+
+### Smart Synonym Search
+
+The search automatically understands related terms:
+
+```typescript
+// These all find the same Animal Pack Redux:
+search_kenney_assets({ query: "cat" })
+search_kenney_assets({ query: "kitty" })
+search_kenney_assets({ query: "kitten" })
+
+// These find packs with horses:
+search_kenney_assets({ query: "horse" })
+search_kenney_assets({ query: "pony" })
+search_kenney_assets({ query: "unicorn" })
+```
+
+### Content-Aware Search
+
+The server knows what's inside each pack:
+
+```typescript
+// Finds packs containing wizard sprites
+search_kenney_assets({ query: "wizard" })
+// Returns: Tiny Battle, Roguelike RPG Pack
+
+// Finds packs containing explosions
+search_kenney_assets({ query: "explosion" })
+// Returns: Space Shooter Redux, Particle Pack
+```
+
+### Helpful Suggestions
+
+When no results are found, get suggestions for:
+- Related search terms
+- Available asset types
+- Popular packs
+
+```typescript
+search_kenney_assets({ query: "xyz123" })
+// Returns suggestions: "Try browsing by type: 2d-sprites, ui, audio..."
+```
+
+## Asset Pack Highlights
+
+### Animals & Creatures
+- **animal-pack-redux** - 160 assets, cute cartoon animals (cats, dogs, farm animals)
+- **creature-mixer** - 100 assets, mix-and-match monster parts
+- **tiny-battle** - 234 assets, knights, wizards, dragons
+- **fish-pack** - 48 assets, underwater creatures
+
+### Platformers
+- **platformer-pack-redux** - 360 assets, complete platformer art
+- **pixel-platformer** - 220 assets, retro pixel art style
+- **abstract-platformer** - 250 assets, colorful abstract shapes
+
+### RPG / Roguelike
+- **tiny-dungeon** - 234 assets, micro roguelike tileset
+- **roguelike-rpg-pack** - 1366 assets, massive dungeon crawler pack
+- **tiny-town** - 239 assets, medieval town tileset
+
+### Shooters
+- **space-shooter-redux** - 384 assets, space shmup pack
+- **topdown-shooter** - 496 assets, top-down spacecraft
+- **topdown-tanks-redux** - 506 assets, tank warfare
+
+### UI
+- **ui-pack** - 322 assets, complete UI kit
+- **ui-pack-rpg-expansion** - 250 assets, fantasy RPG styling
+- **ui-pack-space-expansion** - 250 assets, sci-fi styling
+
+### Audio
+- **digital-audio** - 626 sounds, digital SFX
+- **impact-sounds** - 50 sounds, hits and punches
+- **music-jingles** - 35 tracks, short musical loops
+
+### Other
+- **particle-pack** - 284 assets, VFX particles
+- **kenney-fonts** - 11 fonts, pixel game fonts
+- **1-bit-pack** - 292 assets, monochrome tileset
+
+## Usage Examples
+
+### Agent-Driven Asset Discovery
+
+```typescript
+// Agent searches for assets based on game requirements
+const result = await search_kenney_assets({
+  query: "dungeon",
+  type: "tilesets"
+});
+
+// Agent reviews results and downloads selected pack
+const download = await download_kenney_asset({
+  id: "tiny-dungeon",
+  destination: "./demos/roguelike/assets"
+});
+
+// Agent extracts and integrates into game code
+```
+
+### Skill Integration
+
+Create a `/add-asset` skill that uses these MCP tools:
+
+```bash
+# User invokes skill
+/add-asset platformer sprites
+
+# Skill searches, presents options, downloads on selection
+```
+
+## License
+
+Apache 2.0 - See LICENSE file
+
+All Kenney.nl assets are CC0 (public domain) and require no attribution.

package/TESTING.md

@@ -0,0 +1,161 @@
+# Testing the Asset MCP Server
+
+## Quick Test
+
+Run the test script to validate all improvements:
+
+```bash
+node test-search.js
+```
+
+Expected output:
+```
+✅ PASS - Found packs containing cats/kitties
+✅ PASS - Found packs containing horses/unicorns
+✅ PASS - Found animal packs
+✅ PASS - Provided helpful suggestions when no results found
+```
+
+## Manual Testing with Claude Code
+
+Once the MCP server is configured in `~/.claude/mcp.json`, test these scenarios:
+
+### Test 1: Synonym Search (kitty → cat)
+
+**Prompt:** "Search for kitty sprites"
+
+**Expected:** Should find `animal-pack-redux` containing cats
+
+**MCP Call:**
+```typescript
+search_kenney_assets({ query: "kitty" })
+```
+
+**Result:**
+```json
+{
+  "packs": [
+    {
+      "id": "animal-pack-redux",
+      "name": "Animal Pack Redux (160 assets)",
+      "contents": ["cat", "dog", "bird", ...]
+    }
+  ],
+  "total": 1
+}
+```
+
+### Test 2: Content-Aware Search (wizard)
+
+**Prompt:** "Find packs with wizard sprites"
+
+**Expected:** Should find `tiny-battle` and `roguelike-rpg-pack`
+
+**MCP Call:**
+```typescript
+search_kenney_assets({ query: "wizard" })
+```
+
+**Result:** Multiple packs ranked by relevance (ones with "wizard" in contents ranked higher)
+
+### Test 3: Helpful Suggestions (no results)
+
+**Prompt:** "Search for zzz999" (nonsense query)
+
+**Expected:** Should provide helpful suggestions
+
+**MCP Call:**
+```typescript
+search_kenney_assets({ query: "zzz999" })
+```
+
+**Result:**
+```
+No results found for "zzz999".
+
+Suggestions:
+  • Try browsing by type: 2d-sprites, audio, fonts, tilesets, ui, vfx
+  • Popular packs: platformer-pack-redux, tiny-dungeon, animal-pack-redux, ui-pack
+
+{
+  "packs": [],
+  "total": 0,
+  "suggestions": [...]
+}
+```
+
+### Test 4: Type Filtering
+
+**Prompt:** "Find audio with impact sounds"
+
+**MCP Call:**
+```typescript
+search_kenney_assets({ query: "impact", type: "audio" })
+```
+
+**Result:** Should find `impact-sounds` pack only
+
+### Test 5: Download Flow
+
+**Prompt:** "Download the animal pack to ./assets"
+
+**MCP Calls:**
+```typescript
+// First, search
+search_kenney_assets({ query: "animal" })
+
+// Then download
+download_kenney_asset({
+  id: "animal-pack-redux",
+  destination: "./assets"
+})
+```
+
+**Result:** ZIP file downloaded to `./assets/animalpackredux.zip`
+
+## Common Search Terms to Test
+
+### Animals
+- `cat`, `kitty`, `kitten` → Animal Pack Redux
+- `dog`, `puppy` → Animal Pack Redux
+- `horse`, `pony`, `unicorn` → Animal Pack Redux
+- `dragon` → Tiny Battle, Roguelike RPG Pack
+- `fish` → Fish Pack
+
+### Characters
+- `wizard`, `mage` → Tiny Battle, Roguelike RPG Pack
+- `knight`, `warrior` → Tiny Battle, Roguelike RPG Pack, Platformer Pack Redux
+- `hero`, `player` → Multiple packs
+
+### Objects
+- `coin`, `treasure` → Platformer Pack Redux
+- `button` → UI Pack
+- `explosion` → Space Shooter Redux, Particle Pack
+
+### Styles
+- `pixel-art` → Tiny Dungeon, Pixel Platformer
+- `cartoon` → Animal Pack Redux, Toon Characters
+- `1-bit` → 1-Bit Pack
+
+## Performance Expectations
+
+- **Search latency:** < 1ms (in-memory catalog)
+- **Download latency:** Depends on file size and network (typically 1-5 seconds for most packs)
+- **Memory usage:** < 10MB (catalog is small)
+
+## Known Limitations
+
+1. **Catalog is curated** - Only includes selected Kenney packs, not the entire Kenney library
+2. **Content metadata is manual** - Not auto-generated from actual pack contents
+3. **No fuzzy matching** - "cet" won't find "cat" (only synonyms work)
+4. **Downloads are synchronous** - Large packs (>50MB) may take time
+5. **No extraction** - Downloads ZIP files, user must extract them
+
+## Future Improvements
+
+- [ ] Add fuzzy string matching for typos
+- [ ] Auto-generate content metadata from actual sprite filenames
+- [ ] Support automatic ZIP extraction
+- [ ] Add thumbnail URLs for visual browsing
+- [ ] Integrate Freesound.org for sound effects
+- [ ] Add itch.io integration for community assets