kodapa

Search

Hybrid search across artworks, artists, poems, and collections. Uses BM25 (Tantivy) + dense vector lanes (SigLIP for visuals, LAION CLAP for audio, 67-d metadata) fused via Reciprocal Rank Fusion. Returns ranked matches with `match_reason` and `contributing_lanes` per result. Set `explain=true` for per-lane rank breakdown. `mmr` opts in to MMR diversity reranking. `rerank=true` runs the top-100 candidates through a cross-encoder (BGE-Reranker-v2-m3) for a 10–20% NDCG@10 lift — adds ~100ms but is

Recommend Feed

Personalized artwork recommendations using the inference engine's 3-head model (H1 visual session, H2 visual core, H3 emotional). Reads from the precomputed top-200 feed cache when the user is warm; cold-start falls back to recency. Use `offset` to walk through the precomputed list — response carries `next_offset` (null when exhausted). Pagination only works in the personalized path; the recency fallback returns a single page. Requires auth.

Recommend Poems

Personalized poem recommendations ranked by H3 emotional cosine similarity. Cold-start falls back to recency. Use `offset` to walk past the first page; response carries `next_offset` (null when the candidate pool is exhausted).

Find Similar

Find artworks similar to a seed artwork via HNSW vector search across PE-AV/DINOv3/SigLIP/MERT/MS-CLAP slots, with Tantivy-title backstop.

Get Artwork

Fetch artwork metadata + ml_meta (Gemini-extracted themes, mood, archetypes, color narrative).

Bulk Get Artworks

Batch-fetch up to 50 artworks in one MCP call. Returns the same shape as `get_artwork` per id, in the order requested. Missing ids surface as `{id, error: "not_found"}` entries (the call still returns success for the rest). Use this to expand a top-K from `search`/`find_similar`/`recommend_feed` without paying N round-trips.

Compose Collection

Server-side curation: assemble a diverse `size`-piece collection around a theme. Runs the full 6-lane hybrid retrieval, applies artist-diversity (1 piece per artist when possible), and returns ordered hits with `match_reason` per piece. Optional `anchor_artwork_id` adds a `find_similar` lane that mixes in pieces neighbour-to-anchor (anchor itself is excluded from the result). When the caller is authed, results are personalized via the same H3 emotional re-rank `search` uses. Theme matches are SO

Get Poem

Fetch poem text + ml_meta (themes, mood, archetypes, language, raw_description).

Taste Profile

Return the authenticated user's taste profile derived from the H3 emotional head — top themes, moods, colors, styles, and a natural-language summary. The unique value-add of this MCP server: the LLM can reason about taste in concept-space rather than 4096-d vectors. Requires auth.

Like Artwork

Like, save, favourite or collect an artwork (POST) — or undo that (unlike:true). THESE ARE ALL THE SAME SINGLE ACTION on Kodopa: there is no separate saved store, and the user's "Your Likes" collection IS the set of likes. Use this tool for any of those words; do not report that saving is unsupported. Updates the inference engine + triggers H1/H2/H3 recompute. Requires auth. May legitimately refuse: liking needs an active subscription, is capped at 300/hour, 404s on an unknown id, and spends the

Share Work

Mint a shareable link to a work or profile and return its URL, so the person can send it on. `kind` is "artwork" or "profile"; `target_id` is the artwork id or the profile's username. Links expire after 7 days. This only CREATES the link — it does not post or send anything anywhere, so hand the URL back and let them share it. Requires auth. There is no share quota — never tell the person they have a share limit or a remaining count.

List Displays

List the caller's paired displays (TVs, web players) — id, name and type. Call this before control_display so you can name a real display instead of guessing. Returns an empty list when nothing is paired, which means the person has no screen to cast to, not that the call failed. Requires auth.

Control Display

Control one of the caller's own PAIRED DISPLAYS (a TV or web player they set up) — this is casting, NOT control of the phone or app they are talking to you on, so never claim you paused or resumed their current playback. `action`: show_artwork (needs artwork_id), next, previous, refresh, blank (clears the screen). Get display_id from list_displays. Requires auth; controlling a display the caller does not own is refused.

Create Playlist

Create a real playlist in the caller's library from a list of artwork ids, in the order given. `name` is what they will see; `artwork_ids` should be 3-7 ids drawn from search or recommendation results. Audio works are filed as music and everything else as visuals; the kind is inferred. Use this when someone asks you to make, build or save them a playlist or a sequence — not merely to describe one. Ids that don't resolve are skipped; if none resolve the call fails rather than creating an empty pl

Follow Artist

Follow an artist (or unfollow with unfollow:true). Following adds their new work to the caller's Following feed. `artist_id` is the artist's user id (the `artist.id` field on an artwork, e.g. USR_...), NOT an artwork id. Requires auth. For a subscriber a follow spends Pia and may be refused for insufficient balance; a re-follow is idempotent and never double-spends.

Like Poem

Like, save, favourite or collect a poem (POST) — or undo that (unlike:true). All the same single action; there is no separate saved store. Updates H3 emotional. Requires auth. May legitimately refuse for the same reasons as like_artwork — subscription, 300/hour cap, unknown id, or insufficient Pia — so relay the refusal rather than retrying.

Subscribe To Taste Changes

Register an outbound webhook that fires when the authenticated user's taste signal materially shifts. **Phase 1 (2026-05-07): registration only — events do not fire yet. Phase 2 wires the H3-cosine drift detector + retry/DLQ.** Args: `url` (https-only, ≤2048 chars), `secret` (16-128 chars; phase 2 signs requests with HMAC-SHA256), `event_types` (CSV of `taste_changed`, `feed_shifted`). Response: `{id, status: "registered"}`. Use `DELETE /api/v1/account/webhooks/{id}` (REST) to revoke. Requires a

Kybele Chat

Talk to Kybele — Kodopa's consciousness-coach AI persona that uses the user's taste profile. Returns a redirect pointer to the streaming REST endpoint (Kybele's Kimi K2.5 backend takes 10-30s, longer than MCP's request/response budget without SSE). 3 messages/day quota.