🪴 Bonsai

• A local catalog tool for managing aggregates.
• An aggregate groups one or more Bangumi subjects and their torrent hashes under a local short name and category; it is not necessarily a one-to-one subject mapping.
• An MCP server provides agents with an interface for managing the local collection.

Setup

Install dependencies:

uv sync

Create a local .env file from the sanitized template, then fill in credentials and other site-specific values:

cp env.example .env
uv run pre-commit install

Usage

Configure as an MCP server, OpenCode as an example:

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "bonsai-manager": {
            "command": [
                "uv",
                "run",
                "python",
                "src/main.py",
                "--",
                "mcp"
            ],
            "cwd": "<path to project root>",
            "enabled": true,
            "environment": {
                "UV_WORKING_DIR": "<path to project root>"
            },
            "type": "local"
        }
    }
}

On first use, initialize SQLite and the semantic search index:

uv run ./src/main.py -- sync

Database-backed MCP tools are gated until health checks pass. MCP clients can use sync to initialize or repair the index, refresh the configured Bangumi user's anime collection mirror after its six-hour default TTL, and run configured audit checks. Use sync --force to bypass remote freshness checks and recompute all embeddings. The specialized check_health and rebuild_search_index tools remain available for diagnostics and targeted repair.

The MCP server provides tools to:

• add and remove aggregates
• update Bangumi subjects and add, move, group, or remove torrent hashes
• resolve torrent hashes to live qBittorrent names and metadata
• list aggregates using SQLite filters
• search aggregates semantically
• run configured aggregate audits
• synchronize the Bangumi collection mirror and search index, then run audits
• check health and rebuild the search index directly

The bonsai://aggregates/ resource returns the current aggregate count.

Launch the interactive TUI:

uv run ./src/main.py -- tui

Search semantically:

uv run ./src/main.py -- search "query"

Refresh configured sources, synchronize the search index, and run audits:

uv run ./src/main.py -- sync

Other maintenance commands:

uv run python -m unittest discover -s src/tests -t src
uv run ./src/main.py -- list
uv run ./src/main.py -- audit
uv run ./src/main.py -- db validate
uv run ./src/main.py -- db import-json --input path/to/legacy-db.json
uv run ./src/main.py -- serve

Bonus

To enable OpenCode to directly interact with Bangumi, BangumiMCP can be added:

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "bangumi": {
            "command": [
                "uv",
                "run",
                "python",
                "main.py"
            ],
            "enabled": true,
            "environment": {
                "UV_WORKING_DIR": "<path to BangumiMCP>"
            },
            "type": "local"
        }
    }
}

Roadmap

• Database
  • Migrate aggregate storage to SQLite
  • Remove the JSON runtime backend
  • Add legacy JSON import and database validation
  • Add schema migrations for future SQLite changes
• Search
  • Add LanceDB-backed semantic search index
  • Incrementally update the index after aggregate changes
  • Add consistency health checks and explicit index repair
• MCP
  • Expose aggregate management and semantic search tools
  • Expose search index rebuilding and health checks
  • Gate database tools until health checks pass
  • Expose aggregate collection summary resource
• Bangumi integration
  • Mirror a configured user's anime collections with TTL-controlled sync
  • Synchronize missing Bangumi collections to local catalog
• Torrent management
  • Group torrent hashes within aggregates
  • Prowlarr integration
  • Torrent location management