dank-meme-sounds 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +62 -2
  2. package/index.mjs +171 -0
  3. package/package.json +36 -4
  4. package/play.mjs +26 -0
package/README.md CHANGED
@@ -1,3 +1,63 @@
1
- # Temporary Holding Version
1
+ # dank-meme-sounds
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Give your AI agent a meme soundboard. Search, fetch and **play** 1,500+ meme sound buttons from [DankMachine](https://dankmachine.com), each with its own pixel-art icon.
4
+
5
+ ## Remote server (no install)
6
+
7
+ ```bash
8
+ claude mcp add --transport http dank-meme-sounds https://dankmachine.com/mcp
9
+ ```
10
+
11
+ Any MCP client: `{ "mcpServers": { "dank-meme-sounds": { "url": "https://dankmachine.com/mcp" } } }`. Docs: https://dankmachine.com/developers/
12
+
13
+ ## Local install (adds `play_sound` on your speakers)
14
+
15
+ Claude Code:
16
+
17
+ ```bash
18
+ claude mcp add dankmachine -- npx -y dank-meme-sounds
19
+ ```
20
+
21
+ Any MCP client (Claude Desktop, Cursor, …):
22
+
23
+ ```json
24
+ {
25
+ "mcpServers": {
26
+ "dankmachine": { "command": "npx", "args": ["-y", "dank-meme-sounds"] }
27
+ }
28
+ }
29
+ ```
30
+
31
+ ## Tools
32
+
33
+ | Tool | What it does |
34
+ | --- | --- |
35
+ | `find_reaction_sound` | Describe a moment ("my code finally compiled") and get fitting sounds with what they mean |
36
+ | `get_trending_sounds` | What people are playing right now (1h, 24h, 7d) |
37
+ | `search_sounds` | Search by title, tags, category or vibe |
38
+ | `random_sound` | Random sound, optionally by category or vibe |
39
+ | `get_sound` | One sound by slug or best match |
40
+ | `list_categories` | Categories with counts |
41
+ | `play_sound` | Plays the sound on your speakers (afplay, Windows MediaPlayer, mpg123/ffplay/paplay) |
42
+
43
+ Try: *"play vine boom when the tests pass"*, *"find me a sad trombone"*, *"random cursed sound"*.
44
+
45
+ ## Config
46
+
47
+ `DANKMACHINE_API` points at another catalog (default `https://dankmachine.com/api/v1`).
48
+
49
+ ## Claude Code hooks (sound effects for your agent)
50
+
51
+ `npx dank-meme-sounds play "<query>"` plays a sound from the terminal, so hooks can use it. Add to `~/.claude/settings.json`:
52
+
53
+ ```json
54
+ {
55
+ "hooks": {
56
+ "Stop": [{ "hooks": [{ "type": "command", "command": "npx -y dank-meme-sounds play \"vine boom\"" }] }],
57
+ "Notification": [{ "hooks": [{ "type": "command", "command": "npx -y dank-meme-sounds play \"discord notification\"" }] }],
58
+ "SessionStart": [{ "hooks": [{ "type": "command", "command": "npx -y dank-meme-sounds play \"windows xp startup\"" }] }]
59
+ }
60
+ }
61
+ ```
62
+
63
+ Sounds are cached in your temp folder after the first play.
package/index.mjs ADDED
@@ -0,0 +1,171 @@
1
+ #!/usr/bin/env node
2
+ // DankMachine MCP server (stdio). Reads the public catalog from DANKMACHINE_API (default https://dankmachine.com/api/v1).
3
+ import fs from 'node:fs';
4
+ import os from 'node:os';
5
+ import path from 'node:path';
6
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
7
+ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
8
+ import { z } from 'zod';
9
+ import { playFile } from './play.mjs';
10
+
11
+ const API = (process.env.DANKMACHINE_API ?? 'https://dankmachine.com/api/v1').replace(/\/$/, '');
12
+ const CACHE_DIR = path.join(os.tmpdir(), 'dankmachine-mcp');
13
+
14
+ /** @type {Promise<any[]> | null} */
15
+ let catalog = null;
16
+ function sounds() {
17
+ catalog ??= fetch(`${API}/sounds.json`)
18
+ .then((r) => {
19
+ if (!r.ok) throw new Error(`catalog fetch failed: HTTP ${r.status}`);
20
+ return r.json();
21
+ })
22
+ .then((j) => j.sounds)
23
+ .catch((e) => {
24
+ catalog = null;
25
+ throw e;
26
+ });
27
+ return catalog;
28
+ }
29
+
30
+ const norm = (s) => s.toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '');
31
+
32
+ function search(list, query, category) {
33
+ const words = norm(query).split(/\s+/).filter(Boolean);
34
+ return list
35
+ .filter((s) => !category || s.category === category)
36
+ .map((s) => {
37
+ const title = norm(s.title);
38
+ const hay = `${title} ${norm(s.tags.join(' '))} ${s.category} ${s.vibe}`;
39
+ if (!words.every((w) => hay.includes(w))) return null;
40
+ return { s, score: words.reduce((n, w) => n + (title.startsWith(w) ? 3 : title.includes(w) ? 2 : 0), 0) };
41
+ })
42
+ .filter(Boolean)
43
+ .sort((a, b) => b.score - a.score || b.s.views - a.s.views)
44
+ .map((x) => x.s);
45
+ }
46
+
47
+ const brief = (s) => ({ slug: s.slug, title: s.title, category: s.category, tags: s.tags, vibe: s.vibe, audio: s.audio, image: s.image, page: s.page });
48
+ const text = (data) => ({ content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }] });
49
+
50
+ async function findOne(slugOrQuery) {
51
+ const list = await sounds();
52
+ return list.find((s) => s.slug === slugOrQuery) ?? search(list, slugOrQuery)[0] ?? null;
53
+ }
54
+
55
+ /** Downloads (once) and plays a sound. Shared by the play_sound tool and the `play` CLI used by hooks. */
56
+ async function playSound(query) {
57
+ const s = await findOne(query);
58
+ if (!s) return `No sound found for "${query}".`;
59
+ fs.mkdirSync(CACHE_DIR, { recursive: true });
60
+ const file = path.join(CACHE_DIR, `${s.slug}.mp3`);
61
+ if (!fs.existsSync(file)) {
62
+ const r = await fetch(s.audio);
63
+ if (!r.ok) return `Could not download ${s.audio}: HTTP ${r.status}`;
64
+ fs.writeFileSync(file, Buffer.from(await r.arrayBuffer()));
65
+ }
66
+ const ok = await playFile(file);
67
+ return ok ? `▶ Played "${s.title}" (${s.page})` : `Downloaded "${s.title}" to ${file}, but no audio player was found on this system.`;
68
+ }
69
+
70
+ // CLI mode for hooks and scripts: `npx dank-meme-sounds play "sad violin"`.
71
+ if (process.argv[2] === 'play') {
72
+ // Hooks must never fail loudly: report the problem and exit 0.
73
+ console.log(await playSound(process.argv.slice(3).join(' ') || 'vine boom').catch((e) => `dankmachine: ${e.message}`));
74
+ process.exit(0);
75
+ }
76
+
77
+ const server = new McpServer({ name: 'dank-meme-sounds', version: '0.3.0' });
78
+
79
+ async function apiJson(p) {
80
+ const r = await fetch(`${API}${p}`);
81
+ if (!r.ok) throw new Error(`DankMachine API ${p}: HTTP ${r.status}`);
82
+ return r.json();
83
+ }
84
+
85
+ server.registerTool(
86
+ 'find_reaction_sound',
87
+ {
88
+ title: 'Find a reaction sound for a moment',
89
+ description: 'Describe a situation ("my code finally compiled", "awkward silence", "someone got roasted") and get the best-fitting meme sounds, with what each one means and when to use it.',
90
+ inputSchema: {
91
+ situation: z.string().describe('The moment to react to, in plain words'),
92
+ limit: z.number().int().min(1).max(20).optional().describe('Max results (default 5)'),
93
+ },
94
+ },
95
+ async ({ situation, limit = 5 }) => text(await apiJson(`/reaction?situation=${encodeURIComponent(situation)}&limit=${limit}`)),
96
+ );
97
+
98
+ server.registerTool(
99
+ 'get_trending_sounds',
100
+ {
101
+ title: 'Trending meme sounds',
102
+ description: 'Sounds people are playing most on DankMachine right now.',
103
+ inputSchema: {
104
+ window: z.enum(['1h', '24h', '7d']).optional().describe('Time window (default 24h)'),
105
+ limit: z.number().int().min(1).max(50).optional().describe('Max results (default 10)'),
106
+ },
107
+ },
108
+ async ({ window = '24h', limit = 10 }) => text(await apiJson(`/trending?window=${window}&limit=${limit}`)),
109
+ );
110
+
111
+ server.registerTool(
112
+ 'search_sounds',
113
+ {
114
+ title: 'Search meme sounds',
115
+ description: 'Search DankMachine meme sound buttons by words in the title, tags, category or vibe. Returns audio URLs, pixel-art images and pages.',
116
+ inputSchema: {
117
+ query: z.string().describe('Words to match, e.g. "vine boom", "sad violin", "minecraft"'),
118
+ category: z.string().optional().describe('Optional category slug from list_categories'),
119
+ limit: z.number().int().min(1).max(50).optional().describe('Max results (default 10)'),
120
+ },
121
+ },
122
+ async ({ query, category, limit = 10 }) => text(search(await sounds(), query, category).slice(0, limit).map(brief)),
123
+ );
124
+
125
+ server.registerTool(
126
+ 'random_sound',
127
+ {
128
+ title: 'Random meme sound',
129
+ description: 'Pick a random sound, optionally from one category or with one vibe (funny, hype, cursed, wholesome, scary, sad, annoying, epic, chill, dramatic).',
130
+ inputSchema: { category: z.string().optional(), vibe: z.string().optional() },
131
+ },
132
+ async ({ category, vibe }) => {
133
+ const pool = (await sounds()).filter((s) => (!category || s.category === category) && (!vibe || s.vibe === vibe));
134
+ if (!pool.length) return text('No sounds match that filter.');
135
+ return text(brief(pool[Math.floor(Math.random() * pool.length)]));
136
+ },
137
+ );
138
+
139
+ server.registerTool(
140
+ 'get_sound',
141
+ {
142
+ title: 'Get one sound',
143
+ description: 'Get a sound by slug (or the best match for a query).',
144
+ inputSchema: { sound: z.string().describe('Slug like "vine-boom-sound-70972", or a search query') },
145
+ },
146
+ async ({ sound }) => {
147
+ const s = await findOne(sound);
148
+ return text(s ? { ...brief(s), views: s.views, lang: s.lang } : `No sound found for "${sound}".`);
149
+ },
150
+ );
151
+
152
+ server.registerTool(
153
+ 'list_categories',
154
+ { title: 'List categories', description: 'List DankMachine sound categories with counts.', inputSchema: {} },
155
+ async () => {
156
+ const r = await fetch(`${API}/categories.json`);
157
+ return text((await r.json()).categories);
158
+ },
159
+ );
160
+
161
+ server.registerTool(
162
+ 'play_sound',
163
+ {
164
+ title: 'Play a meme sound',
165
+ description: 'Play a sound out loud on the user\'s computer speakers. Use for celebrations, failures or comic timing when the user wants it.',
166
+ inputSchema: { sound: z.string().describe('Slug or search query, e.g. "vine boom", "sad violin", "airhorn"') },
167
+ },
168
+ async ({ sound }) => text(await playSound(sound)),
169
+ );
170
+
171
+ await server.connect(new StdioServerTransport());
package/package.json CHANGED
@@ -1,6 +1,38 @@
1
1
  {
2
2
  "name": "dank-meme-sounds",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.3.0",
4
+ "description": "MCP server for DankMachine meme sounds: search, find reaction sounds for any moment, trending, and play them on your speakers. Remote version: https://dankmachine.com/mcp",
5
+ "type": "module",
6
+ "bin": {
7
+ "dank-meme-sounds": "index.mjs",
8
+ "dankmachine-mcp": "index.mjs"
9
+ },
10
+ "files": [
11
+ "index.mjs",
12
+ "play.mjs",
13
+ "README.md"
14
+ ],
15
+ "engines": {
16
+ "node": ">=20"
17
+ },
18
+ "keywords": [
19
+ "mcp",
20
+ "model-context-protocol",
21
+ "meme",
22
+ "soundboard",
23
+ "sound effects",
24
+ "claude"
25
+ ],
26
+ "homepage": "https://dankmachine.com",
27
+ "license": "MIT",
28
+ "dependencies": {
29
+ "@modelcontextprotocol/sdk": "^1.32.2",
30
+ "zod": "^3.25.0"
31
+ },
32
+ "mcpName": "io.github.TanKucukhas/dank-meme-sounds",
33
+ "repository": {
34
+ "type": "git",
35
+ "url": "git+https://github.com/TanKucukhas/dankmachine.git",
36
+ "directory": "packages/mcp"
37
+ }
38
+ }
package/play.mjs ADDED
@@ -0,0 +1,26 @@
1
+ // Plays an MP3 file on the local machine with whatever player the OS has. Resolves when playback ends.
2
+ import { spawn } from 'node:child_process';
3
+
4
+ function run(cmd, args) {
5
+ return new Promise((resolve) => {
6
+ const child = spawn(cmd, args, { stdio: 'ignore', windowsHide: true });
7
+ child.on('error', () => resolve(false));
8
+ child.on('close', (code) => resolve(code === 0));
9
+ });
10
+ }
11
+
12
+ /** @param {string} file absolute path to an mp3 */
13
+ export async function playFile(file) {
14
+ if (process.platform === 'darwin') return run('afplay', [file]);
15
+ if (process.platform === 'win32') {
16
+ // WPF MediaPlayer plays MP3 without extra installs; wait until the clip ends (max 30 s).
17
+ const ps = `Add-Type -AssemblyName PresentationCore; $p = New-Object System.Windows.Media.MediaPlayer; $p.Open([uri]'${file.replace(/'/g, "''")}'); `
18
+ + `$i = 0; while (-not $p.NaturalDuration.HasTimeSpan -and $i -lt 50) { Start-Sleep -Milliseconds 100; $i++ }; $p.Play(); `
19
+ + `$ms = if ($p.NaturalDuration.HasTimeSpan) { [math]::Min($p.NaturalDuration.TimeSpan.TotalMilliseconds, 30000) } else { 5000 }; Start-Sleep -Milliseconds $ms; $p.Close()`;
20
+ return run('powershell', ['-NoProfile', '-NonInteractive', '-Command', ps]);
21
+ }
22
+ for (const [cmd, args] of [['mpg123', ['-q']], ['ffplay', ['-nodisp', '-autoexit', '-loglevel', 'quiet']], ['paplay', []], ['play', ['-q']]]) {
23
+ if (await run(cmd, [...args, file])) return true;
24
+ }
25
+ return false;
26
+ }