exyu-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@exyu-mcp Who said 'Vazduh gori ko da…'?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
exyu-mcp
An MCP server that gives AI agents (Claude, ChatGPT, and others) the ex-Yugoslav cultural context they're currently missing.
The problem
LLMs are fluent in ex-YU languages but culturally thin. They know the five most-famous lines of a cult film, not the 200th-most-quoted one, the exact wording, or who actually said it. The exact quote, the correct attribution, the slang meaning, the modern usage — that long tail is missing or hallucinated. This repo builds the layer that fills it: a factual, citable, safe-by-construction cultural-reference database exposed as an MCP server, so any connected agent (Claude, ChatGPT, others) can look it up instead of guessing.
Related MCP server: BENZEMA's Personal Knowledge Card
Scope
This repo is deliberately narrow: cultural reference resolution only —
quotes, attribution, timestamps, slang meaning, cultural weight. Safe,
factual, sourced. Full design in brainstorming/.
We don't try to convince or configure the host platforms — we build the data and the MCP, ship it, and let each platform decide whether to use it. The lever we control is trust: transparent sourcing and per-field provenance, not permission-seeking.
Explicitly out of scope here: shaping how a model talks — tone, directness, swearing as normal register rather than something to sanitize. That's a different kind of problem (what a model is willing to say, not what it knows) and needs a different delivery mechanism than an MCP tool call to someone else's chat app. Planned as a separate future project — a skills/harness layer for a custom chat app or direct API use, potentially reusing this repo's MCP/data. Not started; revisit once this repo's MVP is live.
Current-phase decisions
Copyright/licensing: deferred. We go bold on short-quote usage for now and treat it as a solved problem — there's no way around ingesting copyrighted subtitles/lyrics for the payload this project needs, and stalling on it blocks everything else. The full risk/tier analysis is kept in
brainstorming/09-risks-and-licensing.mdfor when this needs a real answer (before any wide/public distribution) — it's deferred, not forgotten.
Status
Working MVP, not yet through live acceptance. The Phases 0–2 build from the design spec is implemented and green in CI:
TypeScript MCP server exposing
resolve_referenceover Streamable-HTTP (src/server/http.ts) and an npx stdio twin (bin/exyu-mcp.ts).Postgres +
pgvector/pg_trgm/tsvectorstorage, with a trigram → FTS → vector cascade and fully-cited results (work, speaker, timestamps, countersign, meaning, modern usage, per-field provenance).YAML records validated against a locked JSON Schema, ingested into Postgres transactionally and idempotently.
Docker Compose deployment behind Caddy (TLS + rate limiting), with push-to-
mainCI/CD to a Hetzner box.
Not done yet: the live vertical-slice acceptance test — the Valter record is
still a stub with ⚠ TO-VERIFY fields (countersign, speaker, timestamps) that
need real subtitle data, and the 06-plan.md acceptance test (type
"Vazduh gori ko da…" into a real Claude/ChatGPT chat and get the resolved
record back) has not been run against a live deploy.
Full design: docs/superpowers/specs/ and
docs/superpowers/plans/; original design notes in
brainstorming/.
Quickstart
cp .env.example .env # then fill in the values below
npm ci
docker compose up -d db # or `docker compose up -d --build` for the full stack
npm run build # required: `npm run migrate` runs the compiled output
npm run migrate # apply db/migrations/
npm run validate # schema-check every records/**/*.yaml
npm run ingest -- records/film/ref_valter_vazduh_trepti.yaml
npm run dev # http://localhost:8787/mcp (or `npm start` after build)Other scripts: npm test (vitest; the DB-backed tests need Docker for
testcontainers), npm run migrate:dev (migrate via tsx, no build needed).
Environment variables
Variable | Required | Notes |
| yes | e.g. |
| no | HTTP transport port, default |
| ingest only |
|
| ingest only | key for the selected |
| yes |
|
| yes | credential for the selected |
| no | only for |
| production | public hostname Caddy terminates TLS for; falls back to |
The
refs.embeddingcolumn isvector(1536), matching the default OpenAItext-embedding-3-smallmodel. SwitchingEMBEDDING_PROVIDERto a different-dimension model (voyage-3 is 1024) requires altering that column; ingest and resolve both fail with an explicit dimension-mismatch error otherwise.
Available Tools
1 toolresolve_referenceARead-onlyIdempotent
Call this for ANY ex-YU film quote, song lyric, slang term, or meme reference — including partial, misremembered, or colloquial phrasings. The model's internal knowledge of ex-YU culture is unreliable for exact wording, attribution, and modern usage; do not answer from memory without calling this tool first.
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
Only one tool exists, so there is no possibility of confusion between tools. The tool's purpose is clearly defined and distinct.
The single tool name follows a verb_noun structure (resolve_reference), which is clear and consistent. With only one tool, there are no inconsistencies.
One tool is on the low end, but the server's scope is extremely narrow (ex-YU cultural reference resolution), making a single-tool design appropriate. It is slightly under the typical 3-15 range but not a deficiency.
The tool comprehensively covers the domain of ex-YU references, including quotes, lyrics, slang, and memes, with no obvious missing operations for the stated purpose.
Maintenance
Related MCP Connectors
Hosted MCP server for live public-data APIs and Skills for AI agents.
MCP server for AI agents: posts, messages and comments on WhatsApp, Instagram, TikTok and Facebook.
Social media MCP server: your Instagram, TikTok, YouTube, LinkedIn and Threads history for your AI.
MCP server for AI dialogue using various LLM models via AceDataCloud
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceSelf-hosted MCP server giving AI agents persistent memory for personalization and context across conversations.174 PyPI284Apache 2.0
- FlicenseNot gradedqualityDmaintenanceThis MCP server provides LLMs with a live, curated knowledge base of AI agent research, world models, and source-code reviews, enabling personalized and context-aware responses. Users can either connect to the hosted knowledge or build and host their own vault.-
- AlicenseNot gradedqualityDmaintenanceA local MCP server that gives AI coding agents persistent memory and context across sessions.4 npmMIT
- AlicenseAqualityBmaintenanceAn MCP server that gives AI agents cited, review-gated grounding in EU regulation.555 PyPIMIT