How tubone24/midi-mcp-server works
Project Type and Purpose
• The project is a Node.js-based MCP server designed to enable AI models and other MCP clients (like Cline) to generate MIDI files from text-based, structured music compositions.
• Its main functionality is to parse JSON-based music data (with details like BPM, time signature, tracks, notes, etc.), process it, and generate MIDI files using external libraries such as midi-writer-js and @modelcontextprotocol/sdk.
• The project runs as a local process, communicating via standard input/output, and integrates seamlessly with MCP clients without any network configuration.
Analysis of the File Structure
• Top-level items like package.json, tsconfig.json, and src/ indicate that this is a TypeScript project structured for a Node.js runtime.
• The primary business logic likely resides in src/index.ts.
• The examples directory (specifically the "cline" subdirectory) shows sample configuration and usage (e.g., .cline-rules, JSON settings, and a markdown guide) to integrate this server with an MCP client.
• The docs directory contains useful documentation (including an image, a MIDI file sample, and other resources) that supports understanding the musical context and output.
• The presence of build and installation configuration files (package-lock.json, npm scripts in package.json) hints at standard Node.js project conventions.
a. Main Components:
• MCP Client(s): External tools (like Cline) which invoke the MIDI MCP Server via configured commands.
• MCP Server (Core Application): The core of the project, represented by the entry point (src/index.ts). It handles initialization, data parsing, and communication via stdio.
• MIDI Generation Module: Internally, this module (conceptually represented as the "create_midi" tool) is responsible for taking structured music data and generating corresponding MIDI files using the midi-writer-js library.
• External Libraries & SDKs:
• @modelcontextprotocol/sdk: Handles the MCP protocol for communication with clients.
• midi-writer-js: Used to construct and write out MIDI files.
• File System Storage: The module responsible for saving the generated MIDI files to specified locations.
b. Relationships and Data Flows:
• Input Processor: Handles text-based music data received from the client, validates, and parses JSON composition input.
• MIDI Generator: Uses the parsed data to generate MIDI files via the midi-writer-js library.
• MIDI Generator to an Output Module (or simply to “File System”), showing that the generated MIDI files are saved to disk.
c. Architectural Patterns & Design Principles:
• Modularity: Emphasize that the design divides responsibilities into clear modules (input processing, MIDI generation, SDK integration, file writing).
• Loose coupling: The server is designed to be easily integrated with various MCP clients without hard-wired custom network communication, relying on standard I/O.
• Extensibility: The separation between the core processing logic and the MIDI generation module suggests that additional musical features or alternative output formats could be integrated later.
• TypeScript (noted as part of the tech stack given tsconfig.json and the src/*.ts files).
• External libraries (midi-writer-js and @modelcontextprotocol/sdk) can be annotated alongside the MIDI generation and communication components.
• MCP integration (as a label on interactions with external MCP clients).
Specific Elements
• Labels for each major component (MCP Client, MCP Server, Input Processor, MIDI Generator, File System, External Libraries).
• Annotations for the protocols and data structures (for example, labeling the input JSON structure and its conversion to MIDI).
• Use of notes to highlight key points such as “runs via Node.js”, “communicates through stdio”, and “configured via MCP client settings”.