feat(mcp): add MCP server for LLM tool integration via SSE

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: EstrellaXD

CHANGELOG.md

@@ -1,3 +1,17 @@
+# [3.2.3-beta.5] - 2026-02-22
+
+## Backend
+
+### Added
+
+- 新增 MCP (Model Context Protocol) 服务器，支持通过 Claude Desktop 等 LLM 工具管理番剧订阅
+  - SSE 传输层挂载在 `/mcp/sse`，支持 MCP 客户端连接
+  - 10 个工具：list_anime、get_anime、search_anime、subscribe_anime、unsubscribe_anime、list_downloads、list_rss_feeds、get_program_status、refresh_feeds、update_anime
+  - 4 个资源：anime/list、anime/{id}、status、rss/feeds
+  - 本地网络 IP 白名单安全中间件（RFC 1918 + 回环地址），无需 JWT 认证
+
+---
+
 # [3.2.3-beta.4] - 2026-02-22
 
 ## Backend

backend/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "auto-bangumi"
-version = "3.2.3-beta.4"
+version = "3.2.3-beta.5"
 description = "AutoBangumi - Automated anime download manager"
 requires-python = ">=3.13"
 dependencies = [
@@ -24,6 +24,7 @@ dependencies = [
     "sse-starlette>=1.6.5",
     "webauthn>=2.0.0",
     "urllib3>=2.0.3",
+    "mcp[cli]>=1.8.0",
 ]
 
 [dependency-groups]

backend/src/main.py

@@ -7,9 +7,11 @@
 from fastapi.responses import FileResponse, HTMLResponse, RedirectResponse
 from fastapi.staticfiles import StaticFiles
 from fastapi.templating import Jinja2Templates
+
 from module.api import v1
 from module.api.program import program
 from module.conf import VERSION, settings, setup_logger
+from module.mcp import create_mcp_app
 
 setup_logger(reset=True)
 logger = logging.getLogger(__name__)
@@ -45,6 +47,9 @@ def create_app() -> FastAPI:
     # mount routers
     app.include_router(v1, prefix="/api")
 
+    # mount MCP server (SSE transport for LLM tool integration)
+    app.mount("/mcp", create_mcp_app())
+
     return app
 
 
@@ -73,6 +78,7 @@ def html(request: Request, path: str):
         else:
             context = {"request": request}
             return templates.TemplateResponse("index.html", context)
+
 else:
 
     @app.get("/", status_code=302, tags=["html"])

backend/src/module/mcp/__init__.py

@@ -0,0 +1,13 @@
+"""MCP (Model Context Protocol) server for AutoBangumi.
+
+Exposes anime subscriptions, RSS feeds, and download status to MCP clients
+(e.g. Claude Desktop) over a local-network-restricted SSE endpoint.
+
+Usage::
+
+    from module.mcp import create_mcp_app
+
+    app = create_mcp_app()  # returns a Starlette ASGI app, mount at /mcp
+"""
+
+from .server import create_mcp_starlette_app as create_mcp_app

backend/src/module/mcp/resources.py

@@ -0,0 +1,108 @@
+"""MCP resource definitions and handlers for AutoBangumi.
+
+``RESOURCES`` lists static resources; ``RESOURCE_TEMPLATES`` lists URI
+templates for parameterised lookups. ``handle_resource`` resolves a URI
+to its JSON payload.
+"""
+
+import json
+import logging
+
+from mcp import types
+
+from module.conf import VERSION
+from module.manager import TorrentManager
+from module.models import Bangumi
+from module.rss import RSSEngine
+
+from .tools import _bangumi_to_dict
+
+logger = logging.getLogger(__name__)
+
+RESOURCES = [
+    types.Resource(
+        uri="autobangumi://anime/list",
+        name="All tracked anime",
+        description="List of all anime subscriptions being tracked by AutoBangumi",
+        mimeType="application/json",
+    ),
+    types.Resource(
+        uri="autobangumi://status",
+        name="Program status",
+        description="Current AutoBangumi program status, version, and state",
+        mimeType="application/json",
+    ),
+    types.Resource(
+        uri="autobangumi://rss/feeds",
+        name="RSS feeds",
+        description="All configured RSS feeds with health status",
+        mimeType="application/json",
+    ),
+]
+
+RESOURCE_TEMPLATES = [
+    types.ResourceTemplate(
+        uriTemplate="autobangumi://anime/{id}",
+        name="Anime details",
+        description="Detailed information about a specific tracked anime by ID",
+        mimeType="application/json",
+    ),
+]
+
+
+def handle_resource(uri: str) -> str:
+    """Return a JSON string for the given MCP resource URI.
+
+    Supported URIs:
+    - ``autobangumi://anime/list`` - all tracked anime
+    - ``autobangumi://status`` - program version and running state
+    - ``autobangumi://rss/feeds`` - configured RSS feeds
+    - ``autobangumi://anime/{id}`` - single anime by integer ID
+    """
+    if uri == "autobangumi://anime/list":
+        with TorrentManager() as manager:
+            items = manager.bangumi.search_all()
+        return json.dumps([_bangumi_to_dict(b) for b in items], ensure_ascii=False)
+
+    elif uri == "autobangumi://status":
+        from module.api.program import program
+
+        return json.dumps(
+            {
+                "version": VERSION,
+                "running": program.is_running,
+                "first_run": program.first_run,
+            }
+        )
+
+    elif uri == "autobangumi://rss/feeds":
+        with RSSEngine() as engine:
+            feeds = engine.rss.search_all()
+        return json.dumps(
+            [
+                {
+                    "id": f.id,
+                    "name": f.name,
+                    "url": f.url,
+                    "enabled": f.enabled,
+                    "connection_status": f.connection_status,
+                    "last_checked_at": f.last_checked_at,
+                }
+                for f in feeds
+            ],
+            ensure_ascii=False,
+        )
+
+    elif uri.startswith("autobangumi://anime/"):
+        anime_id = uri.split("/")[-1]
+        try:
+            anime_id = int(anime_id)
+        except ValueError:
+            return json.dumps({"error": f"Invalid anime ID: {anime_id}"})
+        with TorrentManager() as manager:
+            result = manager.search_one(anime_id)
+        if isinstance(result, Bangumi):
+            return json.dumps(_bangumi_to_dict(result), ensure_ascii=False)
+        return json.dumps({"error": result.msg_en})
+
+    return json.dumps({"error": f"Unknown resource: {uri}"})

backend/src/module/mcp/security.py

@@ -0,0 +1,48 @@
+"""MCP access control: restricts connections to local network addresses only."""
+
+import ipaddress
+import logging
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+logger = logging.getLogger(__name__)
+
+# RFC 1918 private ranges + loopback + IPv6 equivalents
+_ALLOWED_NETWORKS = [
+    ipaddress.ip_network("127.0.0.0/8"),
+    ipaddress.ip_network("10.0.0.0/8"),
+    ipaddress.ip_network("172.16.0.0/12"),
+    ipaddress.ip_network("192.168.0.0/16"),
+    ipaddress.ip_network("::1/128"),
+    ipaddress.ip_network("fe80::/10"),
+    ipaddress.ip_network("fc00::/7"),
+]
+
+
+def _is_local(host: str) -> bool:
+    """Return True if *host* is a loopback or RFC 1918 private address."""
+    try:
+        addr = ipaddress.ip_address(host)
+    except ValueError:
+        return False
+    return any(addr in net for net in _ALLOWED_NETWORKS)
+
+
+class LocalNetworkMiddleware(BaseHTTPMiddleware):
+    """Starlette middleware that blocks requests from non-local IP addresses.
+
+    Returns HTTP 403 for any client outside loopback, RFC 1918, or IPv6
+    link-local/unique-local ranges.
+    """
+
+    async def dispatch(self, request: Request, call_next):
+        client_host = request.client.host if request.client else None
+        if not client_host or not _is_local(client_host):
+            logger.warning("[MCP] Rejected non-local connection from %s", client_host)
+            return JSONResponse(
+                status_code=403,
+                content={"error": "MCP access is restricted to local network"},
+            )
+        return await call_next(request)

backend/src/module/mcp/server.py

@@ -0,0 +1,86 @@
+"""MCP server assembly for AutoBangumi.
+
+Wires together the MCP ``Server``, SSE transport, tool/resource handlers,
+and local-network middleware into a single Starlette ASGI application.
+
+Mount the app returned by ``create_mcp_starlette_app`` at a path prefix
+(e.g. ``/mcp``) in the parent FastAPI application to expose the MCP
+endpoint at ``/mcp/sse``.
+"""
+
+import logging
+
+from mcp import types
+from mcp.server import Server
+from mcp.server.sse import SseServerTransport
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.routing import Mount, Route
+
+from .resources import RESOURCE_TEMPLATES, RESOURCES, handle_resource
+from .security import LocalNetworkMiddleware
+from .tools import TOOLS, handle_tool
+
+logger = logging.getLogger(__name__)
+
+server = Server("autobangumi")
+sse = SseServerTransport("/messages/")
+
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return TOOLS
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
+    logger.debug("[MCP] Tool called: %s", name)
+    return await handle_tool(name, arguments)
+
+
+@server.list_resources()
+async def list_resources() -> list[types.Resource]:
+    return RESOURCES
+
+
+@server.list_resource_templates()
+async def list_resource_templates() -> list[types.ResourceTemplate]:
+    return RESOURCE_TEMPLATES
+
+
+@server.read_resource()
+async def read_resource(uri: str) -> str:
+    logger.debug("[MCP] Resource read: %s", uri)
+    return handle_resource(uri)
+
+
+async def handle_sse(request: Request):
+    """Accept an SSE connection, run the MCP session until the client disconnects."""
+    async with sse.connect_sse(
+        request.scope, request.receive, request._send
+    ) as streams:
+        await server.run(
+            streams[0],
+            streams[1],
+            server.create_initialization_options(),
+        )
+
+
+def create_mcp_starlette_app() -> Starlette:
+    """Build and return the MCP Starlette sub-application.
+
+    Routes:
+    - ``GET /sse`` - SSE stream for MCP clients
+    - ``POST /messages/`` - client-to-server message posting
+
+    ``LocalNetworkMiddleware`` is applied so the endpoint is only reachable
+    from loopback and RFC 1918 addresses.
+    """
+    app = Starlette(
+        routes=[
+            Route("/sse", endpoint=handle_sse),
+            Mount("/messages", app=sse.handle_post_message),
+        ],
+    )
+    app.add_middleware(LocalNetworkMiddleware)
+    return app