Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@audio-analysis-dedupe check ~/Music/Crate for duplicate audio files and tell me which to keep"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that inspects an audio folder and answers two questions: what is inside these files?, and which of them are duplicates?
检查音频文件夹：文件里是什么（时长／采样率／声道／编码／码率），以及哪些是重复的 （完全重复、同音频不同容器、近似重复候选）。
Works with any MCP-compatible agent or client.
Library analysis. Size, duration, sample rate, channels, codec and bitrate for every file in a folder (recursively if you want).
Exact duplicates. Byte-identical files, grouped by SHA-256 with a suggested file to keep.
Same audio, different container. Files whose decoded PCM stream is identical (for example the same master exported as WAV, AIFF and AU) are reported separately.
Near-duplicate candidates. Name (with (1), - copy, （1） style suffixes normalised),
duration and size are compared, with an explicit list of differences for each candidate pair.
Read-only by design. It never deletes, moves, renames or rewrites a file, and never touches a vendor database.
Related MCP server: Audio Analysis MCP Server
OS | macOS, Linux or Windows |
Python | 3.9 or newer |
Optional |
|
codex plugin marketplace add shadowroommusic/audio-analysis-dedupe
codex plugin add audio-analysis-dedupe@shadowroom{
"mcpServers": {
"audio-analysis-dedupe": {
"command": "python3",
"args": ["mcp_server.py"],
"cwd": "/path/to/audio-analysis-dedupe"
}
}
}python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/shadow-audio-dedupe --helpOption | Default | Used for |
| auto-detected | path to |
|
| similarity threshold for near-duplicate candidates |
| stdout | write the JSON report to a file |
Tool | What it does |
| Analyse a single file (format, duration, sample rate, channels, bitrate) |
| Analyse a folder and group duplicates ( |
CLI equivalents: shadow-audio-dedupe analyze --path <file-or-folder> and
shadow-audio-dedupe dedupe --folder <folder>.
# what is in this crate?
.venv/bin/shadow-audio-dedupe analyze --path ~/Music/Crate --output analysis.json
# what is duplicated, and how do the versions differ?
.venv/bin/shadow-audio-dedupe dedupe --folder ~/Music/Crate --threshold 0.72 --output duplicates.jsonThe dedupe report contains exact_groups, identical_audio_groups, candidates (each with
reasons and differences) and a summary with the redundant file count and bytes.
Read-only: nothing is modified, and no vendor database is opened.
Reports are written only to the path you pass with --output (or to stdout).
Symptom | What to do |
Metadata unavailable for MP3/FLAC | Install |
Everything looks like a near-duplicate | Raise |
Very large folders are slow | Narrow the folder, or run |
See CONTRIBUTING.md. Implementation notes live in docs/internals.md.
AGPL-3.0 — see LICENSE. Optional ffprobe usage is subject to the license of your local
FFmpeg installation.
Report size, duration, sample rate, channels, codec and bitrate for one audio file.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to an audio file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and only partially discharges it: enumerating the reported fields implies a pure read/inspection operation, but it never states that the tool is read-only, side-effect free, or how it behaves on unreadable/non-audio paths. Adequate for a trivial inspection tool, but real behavioral gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with no filler; every listed field corresponds to something the tool actually returns, so nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description usefully enumerates the returned fields, which is the key information an agent needs. It is nearly complete for such a simple read tool, missing only error/failure behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter is documented as an absolute path, so the baseline is 3. The description's 'for one audio file' reinforces that the parameter identifies a single file but adds no format or constraint detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (report) and resource (one audio file) and enumerates exactly which properties are returned (size, duration, sample rate, channels, codec, bitrate). It is immediately distinguishable from the only sibling, dedupe_folder, but does not explicitly contrast itself with any alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for one audio file' scopes the tool to a single-file inspection, which is mild implicit guidance. There is no explicit statement of when to use this versus other tools, no prerequisites, and no mention of what happens with unsupported or missing files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Group exact SHA-256 duplicates and list near-duplicate candidates in a folder. Never deletes files.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | Yes | Absolute path to the folder to scan. | |
| recursive | No | ||
| threshold | No | ||
| max_candidates | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Never deletes files' is a genuinely useful and non-obvious disclosure given the dedupe name, but it omits whether the tool is read-only, what permissions are needed, and what the output looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the core action and followed by the key safety constraint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A four-parameter tool with no output schema and no annotations needs more than two sentences. The threshold value, candidate cap behavior, and return shape are entirely unexplained, leaving the agent under-informed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (just 'folder'); the description adds no meaning for recursive, threshold, or max_candidates, leaving three parameters undocumented in both places. It does not compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: groups exact SHA-256 duplicates and lists near-duplicate candidates in a folder. The scope is unambiguous, though it does not distinguish itself from the sibling analyze_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the description (scanning a folder for duplicates), and 'Never deletes files' hints at safety, but there is no explicit when-to-use, when-not-to-use, or alternative routing versus analyze_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0analyze_filededupe_folderScored across 2 tools
analyze_file targets a single file's metadata, while dedupe_folder scans a folder for duplicates. The two purposes are clearly distinct with no overlapping behavior.
Both tools follow a consistent verb_noun snake_case pattern: analyze_file and dedupe_folder. The naming is predictable and readable.
Only two tools for a server named audio-analysis-dedupe feels thin. The core actions are covered, but the surface is minimal and could benefit from more analysis options.
The server can analyze one file and detect duplicates, but it offers no batch analysis and no way to resolve duplicates (e.g., delete or move). This is a notable gap for a 'dedupe' tool, even if the no-delete behavior is intentional.
Read-only local AI advice, shared reports and website audits. No PC scan or local actions.
Audit any App Store or Google Play listing: measured ranks, keyword gaps, draft copy. Read-only.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Podcast and media analysis: transcripts, captions, chapters, ad markers and show notes.
