Vindhem Server

WIP

Vindhem Server runs your music library independently of the applications you use to work with it. It implements the Vindhem 0.1.2 specification, with HTTP, command-line and MCP access to the same library.

The intended way to use Vindhem Server is through an agent over MCP. Give an agent with terminal access to your computer this repository and ask:

Set up and run Vindhem Server for me, then connect to it through MCP. Ask me which music folder I want to use.

Keep music files, save references to music you find, organize collections, and attach notes and structured data. Applications and agents work with the same library.

Run From Source

Requires Node.js 24 or newer and npm.

git clone https://github.com/Hallmane/vindhem-server.git
cd vindhem-server
npm ci
npm run build
node bin/vindhem.mjs setup

setup installs and starts a local server. It prints its address, data directory and installed command. Subsequent runs reuse that installation. Setup needs npm registry access to install runtime dependencies; it does not import music.

The commands below run from this checkout. You can also use the installed command printed by setup.

Set Up With An Agent

After building, choose a music folder and enable access through MCP:

node bin/vindhem.mjs setup --import-root /absolute/path/to/music
node bin/vindhem.mjs agent guide
node bin/vindhem.mjs agent call getService
node bin/vindhem.mjs agent call listLibraries

agent is a bundled MCP client that a local agent can use through its terminal. It works without restarting the agent application. --import-root chooses a folder the adapter may read for imports. Repeat it for additional folders, or use --no-local-imports. Choosing a folder does not import its contents.

The MCP guide covers direct connections from MCP-compatible applications, tools, resources and configuration.

Use Your Library

Create a library:

node bin/vindhem.mjs create-library 'My music'

Replace LIBRARY_ID with the returned ID to import a music folder and inspect the catalogue:

node bin/vindhem.mjs import LIBRARY_ID /absolute/path/to/music
node bin/vindhem.mjs snapshot LIBRARY_ID

Imports copy audio into managed storage and leave the originals unchanged. Tracks can also hold metadata and source links without an audio file.

Export a Portable Library package:

node bin/vindhem.mjs export LIBRARY_ID /absolute/path/to/library.zip

Portable exports contain the catalogue and selected media. Companion data is stored separately and is not included in this format. For a full backup, preserve the data directory with the server stopped.

The CLI guide covers metadata edits, collections, imports and exports. operations lists the API operations; invoke calls them directly.

Storage And Operation

Metadata lives in SQLite; audio and artwork are stored as files. On macOS, the default data directory is ~/Library/Application Support/Vindhem. On Linux, it follows XDG_DATA_HOME or defaults to ~/.local/share/vindhem. --data DIRECTORY selects another installation; use it consistently for that installation's commands.

The server listens on 127.0.0.1 and uses a generated credential. This is a local, single-owner installation.

node bin/vindhem.mjs status
node bin/vindhem.mjs stop
node bin/vindhem.mjs start

start runs in the background. serve runs in the foreground. After restarting your computer, run start again. Stopping the server preserves your library.

Development

See Contributing for the source layout, build, tests and package checks, and Security for access boundaries and reporting vulnerabilities.

License

Apache License 2.0. Contributions are licensed under the same terms without copyright assignment. Third-party material retains its own notices and license terms.