Add MCP-spec-compliant FastMCP server provider v0.3.17

[trudenboy]

FastMCP Server provider v0.3.17

A new plugin provider that exposes Music Assistant as a Model Context Protocol server, accessible to Claude Code, Codex, ChatGPT Apps SDK, and any other MCP-aware LLM client.

Source: trudenboy/ma-provider-mcp

---

What this adds

• 8 sub-servers (library, queue, playback, players, playlists, volume, media, metadata) with 30+ tools, 3 URI-addressable resources (library://, player://, queue://), and canned prompts.
• ASGI bridge — FastMCP's Starlette app is mounted under MA's existing aiohttp webserver at /mcp/v1; no second port, no changes to MA core.
• MCP 2025-06-18 compliance: Origin allowlist, RFC 9728 protected-resource metadata, RFC 8707 audience binding, ToolAnnotations, per-tool timeouts, ctx.elicit confirmation on destructive ops.
• 16-permission tag-based RBAC (query / control / edit / delete × 4 categories); permission hot-swap without restart.
• Connect Wizard — one-click setup UI at /mcp/v1/connect. Mints a per-client long-lived MA token via the sanctioned auth.revoke_token / auth.get_user_tokens / auth.create_token API (no direct DB access from the provider) and renders ready-to-paste config for Claude Desktop, Claude Code, Cursor, Windsurf, VSCode, ChatGPT Connectors, Codex CLI, Gemini CLI, Cline, Zed. The flow is idempotent under repeat use: re-generating revokes the prior client token, the bootstrap is single-use, and stale MCP — wizard * rows are GC'd on each open. Ingress-aware end-to-end (reuses the active WS client's forwarded host + path for the wizard URL and the matching Origin on POST endpoints), so it works out-of-the-box under Home Assistant add-on ingress with no manual extra_allowed_origins config.

Config

Key	Default	Notes
require_auth	true	Strongly recommended on. Reject unauthenticated MCP clients.
mount_path	/mcp/v1	HTTP path prefix where the MCP server is mounted on MA's webserver. Advanced.
require_confirmation	true	Ask the client to confirm before destructive tools (clear_queue, remove_*); falls through to the permission flag if the client doesn't support elicitation.
enforce_audience	false	RFC 8707 audience binding. Advanced; leave off until MA-side issues audience-bound tokens.
extra_allowed_origins	(empty)	Comma-separated Origin headers to accept in addition to localhost / 127.0.0.1 / the MA base_url host / publish_ip. Advanced.
connect_external_url	(empty)	Explicit base URL for the Connect Wizard link. Only used when auto-detection from the active client's forwarded headers fails. Validated to start with http:// or https://. Advanced.
16 permission booleans	varies	Tag-driven RBAC. Toggling is hot-swapped without restart (except res_library / res_player / res_prompts, which rebuild the resource tree).

Tests

193 passing unit/integration tests + e2e bridge loop covering: HTTP / streamable transport (both /mcp/v1 bare and /mcp/v1/…), /.well-known/oauth-protected-resource, Connect Wizard endpoints (/connect, /connect/info, /connect/exchange, /connect/login, /connect/token), origin allowlist + ingress auto-accept, override sanitiser, player brief state / current_item shape, queue lookahead clamp, library-id resolution for media removes, resource template lookup, resource handler JSON serialisation, hot-swap vs restart routing, wizard token lifecycle (bootstrap single-use, server-side name dedup, wizard-row GC, best-effort revoke under failure modes).

Live smoke (against ghcr.io/music-assistant/server:nightly 2.9.0.dev2026050614 with this provider mounted)

End-to-end manual smoke driven by an MCP-aware LLM client (Claude Code) and curl JSON-RPC against http://localhost:8095/mcp/v1. Stand had 1 Web player, Yandex Music music provider, ~880 library tracks.

Surface	Total	Pass	Skip	Fail	Notes
Tools — read-only (search, list, get, recommendations, lyrics)	16	16	0	0
Tools — mutations (favorites, library, playlists, queue, volume, players, playback, mark_played)	18	17	2	1	Skips structural (no sync-group, no second queue on stand); 1 client-side 15s timeout on media_remove_from_favorites against a Yandex round-trip (server-side mutation completed)
Resources (URI templates) — library://artist|album|track|playlist/{id}, player://{id}, queue://{id}	6	6	0	0	Each returns full domain object or *Brief as JSON text
Prompts	3	3	0	0	find_and_play, curate_party_playlist, now_playing_summary
Auth — /.well-known/oauth-protected-resource/<mount> + bearer	4	4	0	0	200 on well-known + valid; 401 on no-auth + garbage bearer with correct WWW-Authenticate
Permission gating (config hot-swap)	1	1	0	0	control_volume toggle: 44 → 39 → 44 tools listed, no restart
Player state — brief vs raw MA REST	6	6	0	0	state, powered, current_item match players/get payload at playing and post-stop+clear_queue
Total	54	53	2	1

State after the smoke run: baseline restored (player idle, volume 100, queue empty, no leftover playlist / favorite). Server log clean of unexpected error / traceback.

Screenshots

[github-actions]

🔒 Dependency Security Report

📦 Modified Dependencies

music_assistant/providers/fastmcp_server/manifest.json

Added:

• ✅ fastmcp ==3.2.4

The following dependencies were added or modified:

diff --git a/requirements_all.txt b/requirements_all.txt
index 8c1bca0e..25750eed 100644
--- a/requirements_all.txt
+++ b/requirements_all.txt
@@ -35,6 +35,7 @@ deezer-python-async==0.3.0
 defusedxml==0.7.1
 deno==2.7.12
 duration-parser==1.0.1
+fastmcp==3.2.4
 getmac==0.9.5
 gql[all]==4.0.0
 hass-client==1.2.3

New/modified packages to review:

• fastmcp==3.2.4

---

🔍 Vulnerability Scan Results

No known vulnerabilities found

Name	Skip Reason
torch	Dependency not found on PyPI and could not be audited: torch (2.11.0+cpu)
torchaudio	Dependency not found on PyPI and could not be audited: torchaudio (2.11.0+cpu)
✅ No known vulnerabilities found

---

Automated Security Checks

• ✅ Vulnerability Scan: Passed - No known vulnerabilities
• ✅ Trusted Sources: All packages have verified source repositories
• ✅ Typosquatting Check: No suspicious package names detected
• ⚠️ License Compatibility: Some licenses may not be compatible
• ✅ Supply Chain Risk: Passed - packages appear mature and maintained

Manual Review

Maintainer approval required:

• I have reviewed the changes above and approve these dependency updates

To approve: Comment /approve-dependencies or manually add the dependencies-reviewed label.

[Copilot]

Pull request overview

This PR introduces a new fastmcp_server plugin provider that exposes Music Assistant functionality (library/queue/playback/players/playlists/volume/media/metadata) as a FastMCP v3 streamable-HTTP MCP server mounted into MA’s existing aiohttp webserver (plus RFC 9728 well-known metadata support).

Changes:

• Add the music_assistant.providers.fastmcp_server provider: runtime composition, ASGI↔aiohttp bridge, auth verifier, tag-based permission filtering, resources, and prompts.
• Add a comprehensive tests/providers/fastmcp_server/ suite covering URI parsing, tags/config, origin allowlisting, middleware enforcement, elicitation, and e2e bridge behavior.
• Add fastmcp>=3.2,<4.0 to dependency aggregation (requirements_all.txt) and provider manifest requirements.

Reviewed changes

Copilot reviewed 42 out of 44 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/providers/fastmcp_server/init.py	Test package marker for the new provider test suite.
tests/providers/fastmcp_server/conftest.py	Shared fixtures + FakeWebserver for bridge/e2e tests.
tests/providers/fastmcp_server/test_annotations.py	Verifies tool annotations/destructive/read-only hints across mounted sub-servers.
tests/providers/fastmcp_server/test_auth.py	Unit tests for token verification + audience binding behavior.
tests/providers/fastmcp_server/test_config_entries.py	Validates provider ConfigEntry schema and defaults.
tests/providers/fastmcp_server/test_constants.py	Sanity checks for constants/key sets.
tests/providers/fastmcp_server/test_context.py	Ensures Context-based logging/progress paths execute under FastMCP client.
tests/providers/fastmcp_server/test_e2e_http.py	End-to-end bridge tests (streaming chunks, DELETE forwarding, well-known).
tests/providers/fastmcp_server/test_e2e_smoke.py	Optional smoke test for building full runtime and listing namespaced tools.
tests/providers/fastmcp_server/test_elicitation.py	Confirms destructive-tool elicitation flows (accept/decline/disabled).
tests/providers/fastmcp_server/test_middleware.py	Validates TagFilterMiddleware blocks hidden tools/resources/prompts.
tests/providers/fastmcp_server/test_models.py	Tests brief model adapters (to_brief_*) and paging clamp logic.
tests/providers/fastmcp_server/test_origin.py	Tests origin normalization/allowlist and bridge enforcement + RFC9728 metadata.
tests/providers/fastmcp_server/test_tags.py	Tests Tag enum + config-to-tag mapping correctness.
tests/providers/fastmcp_server/test_uri.py	Tests parsing/validation of library://, player://, queue:// URIs.
requirements_all.txt	Adds fastmcp to the aggregated dependency set used in CI installs.
music_assistant/providers/fastmcp_server/init.py	Provider entrypoint (setup, get_config_entries).
music_assistant/providers/fastmcp_server/auth.py	TokenVerifier delegating to MA auth + optional RFC8707 audience enforcement.
music_assistant/providers/fastmcp_server/config.py	Provider configuration schema (server settings + permission toggles + resource toggles).
music_assistant/providers/fastmcp_server/constants.py	Defines config keys and key groupings (permissions/resources/hot-swappable).
music_assistant/providers/fastmcp_server/http_bridge.py	ASGI↔aiohttp bridge, origin allowlist enforcement, and RFC9728 well-known endpoint mounting.
music_assistant/providers/fastmcp_server/manifest.json	Provider manifest (plugin metadata + FastMCP requirement).
music_assistant/providers/fastmcp_server/middleware.py	TagFilterMiddleware to filter listings and block direct invocation of disabled components.
music_assistant/providers/fastmcp_server/models.py	Brief response dataclasses for tool outputs.
music_assistant/providers/fastmcp_server/prompts.py	Registers canned prompts gated by config toggle.
music_assistant/providers/fastmcp_server/provider.py	PluginProvider lifecycle wrapper over MCPServerRuntime + config update handling.
music_assistant/providers/fastmcp_server/resources/init.py	Resource registration entrypoint gated by config toggles.
music_assistant/providers/fastmcp_server/resources/_uri.py	Parser/validator for MCP resource URIs.
music_assistant/providers/fastmcp_server/resources/library_resources.py	Registers library://* read-only resources.
music_assistant/providers/fastmcp_server/resources/player_resources.py	Registers player://* and queue://* resources.
music_assistant/providers/fastmcp_server/server.py	MCPServerRuntime: composes sub-servers, installs middleware, mounts into MA webserver, hot-swap logic.
music_assistant/providers/fastmcp_server/tags.py	Tag enum + mapping from permission config keys to tags.
music_assistant/providers/fastmcp_server/tools/init.py	Exports sub-server builder functions.
music_assistant/providers/fastmcp_server/tools/_common.py	Shared tool helpers (timeouts, paging clamp, brief adapters, confirmation helper).
music_assistant/providers/fastmcp_server/tools/library.py	Library query tools (search/list/get) with ToolAnnotations/timeouts.
music_assistant/providers/fastmcp_server/tools/media.py	Favorites/library mutation + announcement + played-marking tools.
music_assistant/providers/fastmcp_server/tools/metadata.py	Metadata tools (recommendations, recently played, lyrics).
music_assistant/providers/fastmcp_server/tools/playback.py	Playback control tools (play/pause/stop/seek/skip/play_media/play_index).
music_assistant/providers/fastmcp_server/tools/players.py	Player listing/inspection + power/group control tools.
music_assistant/providers/fastmcp_server/tools/playlists.py	Playlist create/add/remove tools with bulk/per-item progress behavior.
music_assistant/providers/fastmcp_server/tools/queue.py	Queue querying/mutation tools (active queue, shuffle, clear, transfer).
music_assistant/providers/fastmcp_server/tools/volume.py	Volume control tools (set/up/down/mute/group volume).
music_assistant/providers/fastmcp_server/icon.svg	Provider icon asset.
music_assistant/providers/fastmcp_server/icon_monochrome.svg	Provider monochrome icon asset.

[Copilot]

Pull request overview

Copilot reviewed 49 out of 51 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 49 out of 51 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 52 out of 54 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 52 out of 54 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 53 out of 55 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 53 out of 55 changed files in this pull request and generated 1 comment.