Add WebMCP support to expose torrent index functionality to AI agents

[josecelano]

Summary

Integrate the WebMCP specification into the Torrust Index GUI so that AI agents (browser-based or external via MCP clients) can discover and interact with the application's functionality through structured, JavaScript-defined tools.

Note: An alternative (or complementary) approach would be to write a standalone MCP server for the Torrust Index backend API directly. That would let agents interact with the Index without requiring a browser at all. WebMCP is specifically useful when we do want to publish a website and let agents interact with the site alongside the user — for example, an AI assistant helping a user search, upload, or manage torrents within the browser UI. Both approaches are not mutually exclusive and could coexist.

What is WebMCP?

WebMCP is a Draft W3C Community Group specification that defines a JavaScript API (navigator.modelContext) allowing web applications to expose their functionality as tools that can be invoked by AI agents, browser agents, and assistive technologies. A web page implementing WebMCP acts as an MCP server with tools implemented in client-side script.

There is also an open-source polyfill library — webmcp.dev (source) — that works with MCP clients like Claude Desktop today, before browsers ship native support.

Why add this?

• AI-assisted torrent discovery — agents can search for torrents by keyword, category, or tags on behalf of the user.
• AI-assisted uploads — agents can populate and submit the upload form with appropriate metadata.
• Accessibility — assistive technologies leveraging WebMCP can interact with the application programmatically.
• Automation — MCP-compatible clients can interact with a running Torrust Index instance through a standardized protocol.

Proposed Tools

Tools to register via navigator.modelContext.registerTool() (or the polyfill), organized by domain:

Torrent Browsing & Search (read-only)

• search_torrents — Search and browse torrents with optional filters (query, category, tags, sort, pagination).
• get_torrent_details — Get full details of a torrent by info hash.
• list_categories — List all available torrent categories.
• list_tags — List all available torrent tags.

Torrent Actions

• download_torrent — Download a .torrent file by info hash (read-only; requires auth on private trackers).
• get_magnet_link — Get the magnet link for a torrent (read-only).
• upload_torrent — Upload a new torrent with metadata (requires auth + terms acceptance).
• edit_torrent — Edit a torrent's metadata (requires auth; must be uploader or admin).
• delete_torrent — Delete a torrent (requires auth; must be uploader or admin).

Authentication & User

• get_current_user — Get current authentication status and user info (read-only).
• sign_in — Sign in with username and password.
• sign_up — Register a new user account.
• change_password — Change the current user's password.

Admin (register only when user is admin)

• admin_add_category / admin_delete_category — Manage torrent categories.
• admin_add_tag / admin_delete_tag — Manage torrent tags.
• admin_get_settings — Get backend settings (read-only).

Implementation Notes

• Create a Nuxt client-side plugin (plugins/webmcp.client.ts) that registers tools on app load, calling the existing Rest API client.
• Dynamically register/unregister tools based on authentication and admin state.
• Use requestUserInteraction() for destructive or sensitive operations (delete, upload review, sign-in confirmation).
• Feature-detect navigator.modelContext for native browser support, falling back to the polyfill.
• The feature should be toggleable via configuration.

References

• WebMCP W3C Draft Spec
• webmcp.dev — polyfill library (source)
• Model Context Protocol
• WebMCP spec source

[da2ce7]

Subject: From WebMCP Integration to a Universal Torrent Interface Standard

Your WebMCP proposal is great for exposing Torrust's functionality. To maximize its impact and avoid vendor lock-in, we should generalize it into a formal, multi-protocol Torrent Profile specification.

The Core Idea: Define the torrent operations (search, details, upload, etc.) once in a TypeScript IDL, then derive everything else from it:

1. TypeScript Interfaces (primary source of truth for devs)
2. Generated JSON Schema (for validation & documentation)
3. Generated C Headers (for native bindings, e.g., desktop apps)
4. Conformance Test Suite (CTS) (like Web Platform Tests for interoperability)

Why? WebMCP and MCP then become just transport adapters. Torrust (or qBittorrent, Transmission, etc.) implements the spec once, and automatically gains WebMCP, MCP, REST API, and CLI support through generic, reusable bridges.

Proposed Architecture

┌─────────────────────────────────────────────────────────────┐
│         Torrent Profile Spec (TypeScript IDL)               │
│  • Source: TypeScript interfaces                            │
│  • Outputs: JSON Schema, C headers, Conformance Tests       │
└───────────────────────────┬─────────────────────────────────┘
                            │ implements │ validates
                            ↓            ↓
┌─────────────────────────────────────────────────────────────┐
│          Vendor Implementations (Backends)                  │
│  • @torrent-backends/torrust    (Torrust API)               │
│  • @torrent-backends/qbittorrent (qBittorrent WebUI)        │
│  • @torrent-backends/transmission (Transmission RPC)        │
└───────────────────────────┬─────────────────────────────────┘
                            │ wrapped by
                            ↓
┌─────────────────────────────────────────────────────────────┐
│           Protocol Bridges (Transport)                      │
│  • bridge-mcp      (MCP server)                             │
│  • bridge-webmcp   (WebMCP tools - your original idea!)     │
│  • bridge-http     (REST/OpenAPI)                           │
│  • bridge-cli      (Command Line)                           │
└───────────────────────────┬─────────────────────────────────┘
                            │
         「Any client uses its preferred protocol」
                            ↓
          [MCP Clients] [Browsers] [CLI] [Mobile Apps]

Key Benefits:

• Reusability: The bridge-webmcp package works with any spec-compliant backend, not just Torrust.
• Ecosystem Growth: Others can implement backends for their favorite clients, all interoperable.
• Future-Proof: New protocols (e.g., a future standard) just need a new bridge.
• Cleaner Torrust Code: Torrust's WebMCP plugin becomes a thin wrapper around @torrent-backends/torrust + bridge-webmcp.

Your WebMCP work becomes the critical first use-case and driving client for this specification. This approach gives us both the immediate AI-agent feature and a lasting, community-oriented foundation.

[da2ce7]

A few pragmatic thoughts from implementing MCP/WebMCP integrations:

1. Standards need adoption drivers first - The most successful standards (like USB-C) started with a compelling implementation that proved the value. Our WebMCP work could be that "reference implementation" that shows why standardization matters.

2. The 80/20 rule of protocol bridges - Building a spec-first approach is probably 5-10x more work initially. We'd need:

   • A working IDL with semantic versioning
   • Codegen pipelines for each target
   • CTS infrastructure and test runners
   • Maintenance overhead for each protocol bridge

3. A potential middle path:

   • Implement WebMCP as planned (immediate value)
   • Extract the TypeScript interfaces into a shared package
   • Design them with extension points for other backends
   • If other clients show interest, we can evolve toward your vision

What if we approach this incrementally?

Phase 1: WebMCP for Torrust (as spec'd)
Phase 2: Extract interface definitions to @torrust/types
Phase 3: If qBittorrent/Transmission developers want to collaborate, expand to @torrent-interface/spec

Your architecture diagram is actually the perfect long-term goal. The question is whether we should build the cathedral first, or start with a useful chapel and see if pilgrims come.

I'd vote for implementing WebMCP now (6-8 weeks of work) while structuring the code so we can later extract the interfaces without breaking changes. This gives us:

• ✅ Immediate AI agent functionality
• ✅ Learning from real usage
• ✅ Clear migration path if standardization gains traction