mcp-djbooth 0.0.1

package/README.md

@@ -0,0 +1,24 @@
+# mcp-djbooth
+
+DJ booth running-order and set-time planning over MCP.
+
+Initial release by [OurMixtape](https://ourmixtape.org). Requires Node.js 20.19 or later.
+All calculations run locally. This release does not play audio, analyze audio files,
+control DJ hardware, or connect to streaming services.
+
+## Run as an MCP stdio server
+
+```sh
+npx --yes mcp-djbooth@0.0.1
+```
+
+This is a public package.
+Configure your MCP client with command `npx` and args `["--yes", "mcp-djbooth@0.0.1"]`.
+
+## Tools
+
+`booth_schedule`: provide `sets`, each with a nonempty `dj` and positive `durationMinutes`. Optional nonnegative `changeoverMinutes` defaults to 0. Returns relative start/end minutes and total duration, including changeovers between sets.
+
+## License
+
+UNLICENSED. All rights reserved.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "mcp-djbooth",
+  "version": "0.0.1",
+  "description": "DJ booth running-order and set-time planning over MCP.",
+  "type": "module",
+  "main": "./utilities.js",
+  "exports": "./utilities.js",
+  "bin": {
+    "mcp-djbooth": "server.js"
+  },
+  "files": [
+    "server.js",
+    "utilities.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "license": "UNLICENSED",
+  "author": "OurMixtape",
+  "homepage": "https://ourmixtape.org",
+  "keywords": [
+    "mcp",
+    "music",
+    "dj",
+    "mixtape"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/server.js

@@ -0,0 +1,35 @@
+#!/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 { tempoMatch, mixtapeTimeline, exportM3u, boothSchedule } from './utilities.js';
+
+const number = { type: 'number', exclusiveMinimum: 0 };
+const text = { type: 'string', minLength: 1 };
+const object = (properties, required) => ({ type: 'object', properties, required, additionalProperties: false });
+const array = (properties, required) => ({ type: 'array', minItems: 1, maxItems: 1000, items: object(properties, required) });
+const definitions = {
+  tempo_match: { description: 'Calculate direct tempo-match playback rate, pitch percentage and beat duration.', inputSchema: object({ sourceBpm: number, targetBpm: number, beats: number }, ['sourceBpm', 'targetBpm']), run: tempoMatch },
+  mixtape_timeline: { description: 'Calculate relative track timings with a constant overlap in seconds.', inputSchema: object({ tracks: array({ title: text, durationSeconds: number }, ['title', 'durationSeconds']), overlapSeconds: { type: 'number', minimum: 0 } }, ['tracks']), run: mixtapeTimeline },
+  export_m3u: { description: 'Generate extended M3U playlist text from supplied track metadata without reading files or URLs.', inputSchema: object({ tracks: array({ title: text, durationSeconds: number, location: text }, ['title', 'durationSeconds', 'location']) }, ['tracks']), run: exportM3u },
+  booth_schedule: { description: 'Calculate a DJ running order in relative minutes, including changeovers.', inputSchema: object({ sets: array({ dj: text, durationMinutes: number }, ['dj', 'durationMinutes']), changeoverMinutes: { type: 'number', minimum: 0 } }, ['sets']), run: boothSchedule },
+};
+const selected = ["booth_schedule"];
+const server = new Server({ name: 'mcp-djbooth', version: '0.0.1' }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: selected.map(name => {
+  const { run, ...definition } = definitions[name];
+  return { name, ...definition, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } };
+}) }));
+server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+  try {
+    if (!selected.includes(params.name)) throw new Error(`Unknown tool: ${params.name}`);
+    const args = params.arguments ?? {};
+    const definition = definitions[params.name];
+    if (Object.keys(args).some(key => !(key in definition.inputSchema.properties))) throw new Error('Unexpected argument');
+    const value = definition.run(args);
+    return { content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value) }] };
+  } catch (error) {
+    return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'Invalid input' }] };
+  }
+});
+await server.connect(new StdioServerTransport());

package/utilities.js

@@ -0,0 +1,57 @@
+const positive = (value, label) => {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) throw new Error(`${label} must be a positive finite number`);
+  return value;
+};
+const nonnegative = (value, label) => {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) throw new Error(`${label} must be a nonnegative finite number`);
+  return value;
+};
+const line = (value, label) => {
+  if (typeof value !== 'string' || !value.trim() || /[\r\n\x00]/.test(value)) throw new Error(`${label} must be nonempty single-line text`);
+  return value;
+};
+const items = (value, label) => {
+  if (!Array.isArray(value) || value.length < 1 || value.length > 1000) throw new Error(`${label} must contain 1 to 1000 items`);
+  for (const item of value) if (!item || typeof item !== 'object' || Array.isArray(item)) throw new Error(`${label} entries must be objects`);
+  return value;
+};
+const finiteResult = (value) => {
+  if (!Number.isFinite(value)) throw new Error('Calculation exceeds numeric range');
+  return value;
+};
+export function tempoMatch({ sourceBpm, targetBpm, beats = 4 }) {
+  positive(sourceBpm, 'sourceBpm'); positive(targetBpm, 'targetBpm'); positive(beats, 'beats');
+  const rate = finiteResult(targetBpm / sourceBpm);
+  return { playbackRate: rate, pitchPercent: finiteResult((rate - 1) * 100), beatDurationSeconds: finiteResult(60 / targetBpm), durationSeconds: finiteResult((60 / targetBpm) * beats) };
+}
+export function mixtapeTimeline({ tracks, overlapSeconds = 0 }) {
+  items(tracks, 'tracks'); nonnegative(overlapSeconds, 'overlapSeconds');
+  let end = 0;
+  const timeline = tracks.map((track, index) => {
+    line(track.title, 'title'); positive(track.durationSeconds, 'durationSeconds');
+    if (overlapSeconds >= track.durationSeconds) throw new Error('overlapSeconds must be smaller than every track duration');
+    const startSeconds = index === 0 ? 0 : end - overlapSeconds;
+    end = finiteResult(startSeconds + track.durationSeconds);
+    return { title: track.title, startSeconds, endSeconds: end };
+  });
+  return { tracks: timeline, totalDurationSeconds: end };
+}
+export function exportM3u({ tracks }) {
+  items(tracks, 'tracks');
+  return '#EXTM3U\n' + tracks.map(track => {
+    line(track.title, 'title'); positive(track.durationSeconds, 'durationSeconds'); line(track.location, 'location');
+    if (track.location.trimStart().startsWith('#')) throw new Error('location must not start with an M3U directive');
+    return `#EXTINF:${Math.round(track.durationSeconds)},${track.title}\n${track.location}\n`;
+  }).join('');
+}
+export function boothSchedule({ sets, changeoverMinutes = 0 }) {
+  items(sets, 'sets'); nonnegative(changeoverMinutes, 'changeoverMinutes');
+  let end = 0;
+  const schedule = sets.map((set, index) => {
+    line(set.dj, 'dj'); positive(set.durationMinutes, 'durationMinutes');
+    const startMinutes = finiteResult(end + (index ? changeoverMinutes : 0));
+    end = finiteResult(startMinutes + set.durationMinutes);
+    return { dj: set.dj, startMinutes, endMinutes: end };
+  });
+  return { sets: schedule, totalDurationMinutes: end };
+}