agora-plus MCP server
Commit Oct 30, 2026A self-hosted household assistant that uses Qloo signals to coordinate group decisions like movie nights or dining based on family preferences and constraints.
Also known as Ritesh-Root/agora-plus
- Stars
- 0
- Tools
- 3
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 30, 2026
- License
- MIT
What is agora-plus MCP?
agora-plus is a self-hosted household assistant that uses Qloo signals to coordinate group decisions like movie nights or dining based on family preferences and constraints. It exposes 3 tools, such as qloo_recommend, qloo_rank, qloo_capabilities.
Summary generated from the project's README
About agora-plus MCP server
Coordinating group activities like movie nights or dining out in multigenerational homes is what agora-plus enables by turning individual preferences into actionable group decisions. This self-hosted household assistant uses Qloo signals to rank options based on the specific tastes, age bands, and constraints of every family member. It functions as an MCP server compatible with clients like Claude, ChatGPT, or Gemini, allowing users to ask questions through a text or voice interface.
The system works by converting household facts into signals for the qloo_recommend and qloo_rank tools. It creates a shared shortlist of up to ten candidates and applies a maximin algorithm to ensure the final choice is one that nobody ranks poorly. A local component called Keeper automatically filters out suggestions that clash with documented allergies or dietary restrictions, such as vegetarian requirements. Users must provide a Qloo API key for the service to function, and the server manages household memory locally to maintain privacy.
What you can do with it
- 1Plan a family movie nightAsk the assistant to find a film that satisfies both a young child and an elderly relative based on their unique favorite genres.
- 2Select a restaurant for group diningRequest a dining recommendation that respects specific dietary constraints like vegetarianism or peanut allergies.
- 3Coordinate diverse entertainment preferencesUse the Taste Council to pick a book, artist, or TV show that balances the interests of different age demographics.
Written from the project's README. Every use case is checked against a quote from it.
agora-plus MCP tools 3
Detected from the READMEqloo_recommendqloo_rankqloo_capabilities
Configuration
AGORA_DEMO_SEEDAGORA_MCP_TOKENAGORA_SERVER_LLMAWS_REGION
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableritesh-root/agora-plus is public and reachablegithub.com/ritesh-root/agora-plus ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-30github.com/ritesh-root/agora-plus ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model3 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAGORA+ Taste Council
A household assistant that turns what it remembers about each person into Qloo signals, ranks one shortlist for each of them, and picks the option nobody ranks low.
Live demo: https://agora-plus-295478535981.us-central1.run.app (household passcode: tastecouncil — a fictional family is preloaded)
Submitted to the Qloo Agentic Hackathon ("Agents, but with taste"). Source code is MIT (LICENSE). The deep dive is docs/QLOO.md. Copy-ready submission text is docs/SUBMISSION_QLOO.md.
The problem
AGORA+ is a self-hosted household assistant. It keeps facts about each family member in a file on your server, every write comes back with a receipt, and anything with side effects waits for a person's yes. It is reachable as an MCP server (Claude, ChatGPT, Alexa+-style clients) and from a voice and text assistant on its Home page.
It already knew "Mia loves Encanto", "Dadi is 74" and "Arjun is vegetarian". But when someone asked "what should we watch tonight?", a language model alone could only guess. It tends to pick something generic, or something for whoever spoke last. It has no grounded way to say how a 74-year-old who loves Raj Kapoor films and a 9-year-old who loves Encanto would each rank the same five films.
That is a daily question in multigenerational homes, which are common in India and in many other places: movie night, dinner out, a road-trip playlist, a show to watch together, a family book club, a weekend outing. The Taste Council answers it with Qloo, and shows its work.
Try it in 60 seconds
On the live demo (a fictional family: Mia 9, Rohan 16, Arjun 41, Dadi 74):
- Open the link and enter the household passcode. Home opens.
- Find the Taste Council card. There is one chip per person, with their age band, what they love, and what Keeper watches for (for example "Keeper watches: vegetarian").
- Leave everyone in, choose Family movie night, and press Ask the council.
- The result sheet shows the pick, each person's rank for it ("#2 of 10"), who it suits least ("Lowest fit"), Qloo's tags, and the runners-up.
- Open Qloo calls at the bottom. Every call is listed: the tool, who it was for, the status, the result count, the time in ms, and the exact arguments sent.
- Choose Dinner out. If Qloo's candidates include a steakhouse or a satay place, Keeper sets it aside under "Keeper removed" and quotes the fact ("Arjun is vegetarian", "Mia is allergic to peanuts").
- Tap a chip to leave someone out, for example only Mia and Dadi, and ask again.
- In the assistant box, type "What should we watch tonight?". The model calls the
taste_councilMCP tool, and Under the hood shows thattools/call.
How the council decides
flowchart TD
mem["Household memory: 'Mia loves Encanto', 'Dadi is 74', 'Arjun is vegetarian'"]
parse["profile.ts: per person loves, likes, age band, constraints (no model)"]
rec["qloo_recommend, once per person: their loves as signals, plus age band and location"]
short["Shortlist: round-robin across people, deduplicated, at most 10"]
rank["qloo_rank, once per person, same shortlist: ordinal ranks"]
maximin["Maximin: best worst-rank, then best mean rank"]
keeper["Keeper: drop picks that clash with a diet, allergy or 'no X' fact, and quote it"]
out["Top 5 picks, one spoken sentence, every Qloo call"]
mem --> parse --> rec --> short --> rank --> maximin --> keeper --> out
home["Home page: POST /api/taste/council"] --> parse
mcp["MCP tool taste_council: Claude, ChatGPT, the Gemini voice assistant"] --> parse
- Facts become signals. server/taste/profile.ts reads household memory with plain rules. "Dadi loves Raj Kapoor films, Lata Mangeshkar and Mughal-e-Azam" gives three named loves. "Arjun likes thrillers" gives a tag. "Dadi is 74" gives the band
55+. "Mia is allergic to peanuts" gives a constraint. - Candidates per person. One
qloo_recommendcall per person, for the target type of the occasion (movie, tv_show, artist, book, or place). - One shared shortlist. Round-robin across people, so everyone's candidates get in. At most 10 options, because
qloo_rankaccepts at most 10. - Rank the same list per person. One
qloo_rankcall per person over that shortlist. Qloo says scores from separate calls are not comparable, so the council keeps only each person's order (1st, 2nd, ...). - Maximin. The winner is the option whose worst rank across people is best. Ties go to the better mean rank. Nobody gets their 9th choice so that someone else gets their 1st.
- Keeper. Picks that clash with a diet, allergy, or "no horror" fact are removed, and the fact is quoted. Here Keeper is plain code, not the model agent of the same name in the household team.
- Receipts. The result carries every Qloo call. The Home page keeps the last few councils after a reload.
The algorithm is in server/taste/council.ts. The contract shared by server and page is shared/taste.ts.
Qloo tools used, and why
The council talks to Qloo through Qloo's official harness, qloo mcp (package @qloo/qloo-harness@0.1.26), started as a child process over stdio (server/taste/qlooClient.ts). That is the route Qloo's hackathon kit recommends. There are no raw HTTP calls to Qloo in this repository.
| Tool | When | What we send | Why this tool |
|---|---|---|---|
qloo_recommend |
Once per person | target_type, limit: 8, the person's loves as signals (up to 4), likes as signal_tags, and, when a location is known, signal_location plus an age-band demographic. Places also get filter_location. |
Turns each person's favourites into candidates of the right type, across domains: an artist can be the signal for films. |
qloo_rank |
Once per person | The same options (Qloo entity ids from the shortlist), option_type, and that person's signals, signal_location and demographic. |
Ranks one fixed list against one person's taste. Comparing positions across people is what makes the choice fair. |
qloo_capabilities |
Before each council, and for the card's "ready" state | Nothing | Checks that qloo mcp started and has a credential. The harness answers it without contacting Qloo. |
The harness offers nine workflow tools. The council uses the two that fit a group decision. qloo_describe, qloo_entity_tags, qloo_find_tags, qloo_compare_audiences, qloo_audience_demographics, qloo_where_popular and qloo_trends are not used yet.
When Qloo cannot resolve a name, the harness returns needs_input with candidate matches. The council retries once with Qloo's first candidate id, and both calls show in the call list. Calls are cached for 30 minutes, and at most two are in flight at once. See docs/QLOO.md.
What is Qloo, what is code, what is Gemini
| Part | Done by |
|---|---|
| Resolving "Encanto" or "A. R. Rahman" to Qloo entities | Qloo (inside the harness) |
| Candidate options per person | Qloo qloo_recommend |
| Each person's ordering of the shared shortlist | Qloo qloo_rank |
| Tags, year, rating, address and images on a pick | Qloo result metadata |
| Reading facts into loves, likes, age bands and constraints | Deterministic code, no model |
| Shortlist, maximin, tie-breaks, Keeper vetoes, the spoken sentence | Deterministic code, no model |
Hearing "what should we watch tonight?", choosing taste_council and its arguments, saying the answer |
The agent's model. On the server that is Gemini on Vertex AI (AGORA_SERVER_LLM=vertex). Any MCP client brings its own model. |
No model chooses the winner. The Home page's Ask the council button runs with no model at all.
Why it needs Qloo
Take Qloo out and the council has nothing to rank with.
- Cross-domain taste. Dadi's signals are a filmmaker, a playback singer and a 1960 film. Mia's are two animated films and a pop star. Qloo's taste graph turns both into ranked films, books or restaurants. A model can name films, but it has no measured affinity behind the order.
- Audience demographics. An age band and a location become a Qloo demographic signal, so "seniors in Bengaluru" and "teens in Bengaluru" pull the ranking in different directions.
- Rank against a profile.
qloo_rankputs one fixed list in order for one person. That per-person order is the input to the fairness rule. A model has no grounded per-audience ranking to give.
Responsible use
- What goes to Qloo: entity names as written in memory ("Encanto"), abstract likes as tags ("thrillers"), an age-band phrase ("seniors", "adults 35-44"), a location string, the target type, and the shortlist's Qloo entity ids. An "avoid" fact such as "no horror" is sent as an exclude tag for films, shows, music and books.
- What stays on the server: first names, exact ages, allergies, diets, and the text of the facts. Names appear only in the local call log ("for Mia"). Keeper checks diets and allergies locally.
- The key is read by the
qloo mcpchild fromQLOO_API_KEYor the harness's own config. Our code never logs it or returns it, and scrubs it from error text. - Aggregate, not personal. Qloo results are aggregate cultural affinities, not predictions about any one person. The card and the result sheet both say so.
- Nothing is booked or bought. The council suggests. Adding a pick to the to-do list is a separate button.
- The demo family is fictional. It is written only when
AGORA_DEMO_SEED=1and memory is empty, and it is taggeddemo.
Limits
What a council result does not establish:
- That a person will enjoy the pick. "#2 of 10 for Dadi" means Qloo placed it second among those ten options for a profile built from Dadi's saved favourites.
- That the pick is the best option anywhere. Ranks are only within a shortlist of at most 10.
- That the pick is suitable for a child. There is no content-rating filter. The rating shows when Qloo returns one; a parent should check it.
- That a place is safe for an allergy or a diet. Keeper is a keyword check on names, tags and descriptions, not a menu or ingredient check.
- That "#2 for Mia" and "#2 for Dadi" mean the same strength of liking. Only order within one person's call is used.
Other limits:
- Under-18 maps to the phrase "teens", which Qloo's harness turns into its youngest age bucket (24 and younger). There is no "children" demographic, so a 9-year-old and a 16-year-old get the same age signal.
- Age and location signals are sent only when a location is known (the request, or
AGORA_TASTE_LOCATION). - A person with only abstract likes ("street food") and no named favourite or location cannot be ranked. The result says so.
- The fact parser is English pattern rules. Unusual phrasing is missed.
taste_profileshows what it understood. - Maximin is one fairness rule. It can choose a pick everyone ranks third over one most people rank first.
- When
needs_inputoffers several matches, the council takes Qloo's first candidate. It can be the wrong "Coco". - One household per server.
Run it yourself
Full setup from a clean machine, environment variables, and the Cloud Run command are in docs/QLOO.md. The short version:
npm install --global @qloo/qloo-harness@0.1.26
qloo setup --qloo # paste the key; it is hidden
qloo config set base-url https://hackathon.api.qloo.com
git clone https://github.com/Ritesh-Root/agora-plus.git && cd agora-plus
npm ci
AGORA_DEMO_SEED=1 AGORA_TASTE_LOCATION=Bengaluru npm run dev
Open http://127.0.0.1:3000/. The Taste Council card works without any language model. The assistant box needs one (see Quick start).
From Claude Code, with AGORA_MCP_TOKEN set (at least 32 characters):
claude mcp add --transport http agora http://127.0.0.1:3000/mcp --header "Authorization: Bearer $AGORA_MCP_TOKEN"
Then ask "What should the family watch tonight?" or "Where should Arjun and Mia eat in Bengaluru?".
The rest of AGORA+
The household layer was first built for the Amazon Developer Hackathon (Alexa+ track), on top of the AGORA office. The sections below describe that base. They are still accurate for this build.
Household memory is a file on a server you run. Every write returns a receipt whose verified flag is a second read of that file. Nothing with side effects starts until a person says yes, and that wait is in the tool result, not only in a prompt.
The surfaces that were run for the Alexa+ entry are the unofficial voice page at /alexa and the MCP server at /mcp, used from Claude Code with AGORA_MCP_TOKEN. MCP clients such as Alexa+ add-ons, Claude, and ChatGPT can connect to that same server. ChatGPT was not run against it, and a live Alexa+ add-on was not deployed. The add-on package in alexa-addon/addon.json is still a template: every URL contains <host>.

Why memory with receipts
Other assistants already advertise family memory, shopping lists, and device control. This server keeps household facts on the machine you run, and a plan does not start until a person says yes. Lights, locks, calendars, and countdown timers are not in this build.
The Alexa+ entry was shaped by four complaints from an 8 Oct 2026 research pass: jobs that stop halfway, slow replies, stored facts that disappear, and people who want a checkpoint before an agent acts. Quotes and sources are in docs/research/alexa-plus-voice-of-customer.md and docs/research/sources.json. In this build:
remember,recall, andforgetare backed bymemory.jsonand the MCP resourceagora://memory. A fact can name a person (who). The Household panel can edit it.forgetandplan_and_runreturnneeds_approval. Remembering a fact and adding a task do not wait. On/alexathe model cannot callapprove_action. A person says an exact yes or no, or uses a button.approve_actionstays an MCP tool for external clients.- A plan shows its steps and waits for a yes before the team starts. The receipt on a write is a separate thing:
verifiedis a read-back from disk.
What it does
- Household Home at
/(also/alexa). This is the page to open first. A greeting with the briefing, the assistant, the Taste Council, Today's reminders, the Shopping and To-do lists (tick, untick, remove, clear the basket), Family facts grouped by person with Allergy, Diet, and Medical badges, and Plans. While a plan runs, the Plans card shows each team member's step and its status; a finished plan opens in the page. Connect shows the/mcpendpoint and theclaude mcp addcommand. Under the hood opens the MCP trace beside the page. - Voice assistant on Home. Unofficial simulated Alexa+ experience. Type, or tap or hold to talk. Remember, recall ("What is Mia allergic to?"), the briefing, the shopping list, reminders, and an exact yes or no are routed with no model call (server/alexaSim/fastPath.ts). Other turns go to the server model, which calls tools through the real
/mcpendpoint. A plan asks the model once for the step list, and only after that preview returns steps does the page wait for a yes. Orders, purchases, bookings, payments, and phone calls are refused, with no approval id. The page shows an "Under the hood" trace of each MCPtools/call. While it is open it pollsGET /api/householdabout every 30 seconds and speaks "Reminder: <title>." once per due task per page load. - MCP server at
/mcp. Thirteen tools always (includingtaste_councilandtaste_profile), andweb_researchas a fourteenth whenFIRECRAWL_API_KEYorEXA_API_KEYis set. Three resources (agora://memory,agora://tasks,agora://runs/{id}/document) and two prompts (morning-briefing,plan-a-week-of-meals). Streamable HTTP. The server negotiates protocol 2025-11-25 and newer (server/mcp/mcp.test.ts). Alexa's published client sample sends2025-03-26. The specification index on 8 Oct 2026 names 2026-07-28 as current (docs/council/reports/g4-spec-followup.md). OAuth is in server/mcp/oauth.ts.daily_briefingandlist_tasksput the MCP Apps card on the tool result as well as the tool definition (ui://daily_briefing/household-card.html). The tool reference is skills/agora-household/references/TOOLS.md. - People, lists, and reminders. A fact can store
who(a leading name such as "Mia is allergic to peanuts" is enough). A task can storewho,list(shoppingis its own list; absent means the main to-do list), anddueAt(ISO 8601 with a numeric offset). The free-textduestays. The briefing speaks one memory line, allergies and medicine first ("Remember: Mia is allergic to peanuts."). Recall says both facts when they tie. - Agent Skill skills/agora-household/SKILL.md. How to connect, which tool to call, and the rule that a
needs_approvalresult waits for a person. - Server model.
AGORA_SERVER_LLMpicks it.vertexcalls Gemini on Vertex AI through its OpenAI-compatible endpoint, with Application Default Credentials (server/llm/vertexProvider.ts).bedrockcalls Amazon Bedrock through the Claude Messages endpoint (server/llm/bedrockProvider.ts), only when AWS credentials are present.openaicalls any OpenAI-compatible endpoint (AGORA_LLM_*in .env.example, server/llm/openaiProvider.ts). - Household team: Agora, Scout, Planner, and Keeper (server/household/team.ts), on whichever server model is set. Keeper checks plans against memory. A step whose model call fails is marked for help and the rest of the team finishes. The plans recorded during the Alexa+ hackathon used the
openaimode with open Qwen models on Featherless, because no AWS credentials were present. A live Bedrock call was not recorded in this workspace. - Polly speaks when AWS credentials are present (server/alexaSim/tts.ts). The browser voice speaks when Polly returns 503. A successful Polly synthesize was not recorded, so time to first audio was not measured.
- Approvals and receipts.
forgetandplan_and_runwait. Remembering and adding a task do not. Every write can show{ action, id, verified, at }.verifiedis a follow-up read. A failed yes leaves the approval pending so it can be retried. Waiting approvals still live in the process and expire after ten minutes. - 3D office at
/office. The Household cast is the roster. A household run is written toruns/<id>.jsonwithstatus: "running"when it starts, and again when it ends. The Society panel showsspokenSummarywhen the run has one. - Alexa+ add-on package in alexa-addon/addon.json, plus public/privacy.html and public/terms.html. Account linking is enabled in the file (authorization code, PKCE S256). The manifest lists the United States only, and every URL is still
https://<host>/....alexa-aiwas not deployed from this workspace.
The file map is docs/ARCHITECTURE.md.
Screenshots
Captured from the running app on 10 and 12 Oct 2026, before the Taste Council was added.
Claude Code, a separate MCP client, answering from the same household. The output of a real claude -p run, set as text:

A forget request sent over MCP comes back as needs_approval and waits on the Home page for a person:

Quick start
You need Node.js and npm. The Dockerfile uses Node 22. Qloo's harness asks for Node 22.19.0 or newer. The repository does not declare an engines field.
git clone https://github.com/Ritesh-Root/agora-plus.git
cd agora-plus
npm ci
cp .env.example .env
The voice page, remember, the briefing, the shopping list, recall, and the Taste Council card do not need a language model. The Taste Council needs Qloo (docs/QLOO.md).
For Gemini on Vertex AI, sign in with gcloud auth application-default login and start the server with these in the shell. npm run dev copies only AGORA_*, AWS_*, BEDROCK_*, POLLY_*, QLOO_* and a few other named settings from .env into the server, so GOOGLE_CLOUD_PROJECT and VERTEX_* must come from the shell:
AGORA_SERVER_LLM=vertex GOOGLE_CLOUD_PROJECT=your-project npm run dev
Defaults are google/gemini-3.8-flash, and google/gemini-3.5-flash-lite for spoken turns. Override with VERTEX_MODEL and VERTEX_FAST_MODEL, or set ALEXA_SIM_MODEL=google/gemini-3.8-flash to use Flash for spoken turns too.
For Amazon Bedrock instead, with AWS credentials on the standard chain (aws login, a profile, or a task role), in .env (values only, never commit the file):
AGORA_SERVER_LLM=bedrock
AWS_REGION=us-east-1
Bedrock defaults are anthropic.claude-sonnet-5 and anthropic.claude-haiku-4-5. Override with BEDROCK_MODEL and BEDROCK_FAST_MODEL if you need to.
Claude Code needs a development token of at least 32 characters. A shorter value is ignored.
AGORA_MCP_TOKEN=choose-at-least-32-random-characters
OAuth also needs AGORA_OAUTH_CLIENT_ID, AGORA_OAUTH_CLIENT_SECRET, and AGORA_TOKEN_SECRET (at least 32 characters). A public process also needs AGORA_PUBLIC_URL and AGORA_HOUSEHOLD_PASSCODE. If the OAuth secrets are empty, those routes return 503 and the development token is the one that can call tools. The token is ignored when NODE_ENV=production or AGORA_PUBLIC_URL is https, unless AGORA_ALLOW_DEV_TOKEN=1. The voice assistant reaches its tools through /mcp, so it needs OAuth or an accepted development token too.
npm run dev
npm run dev starts Vite on port 3000 and binds 127.0.0.1, with the room relay and /mcp. Open http://127.0.0.1:3000/ for the household Home. The optional 3D team view is http://127.0.0.1:3000/office. /alexa is the same Home. npm run dev:lan binds 0.0.0.0. On that bind, /mcp and OAuth return 503 until AGORA_PUBLIC_URL is set, and household routes from another machine return 403 until AGORA_HOUSEHOLD_PASSCODE is set.
agora-plus MCP questions
What tools does agora-plus MCP provide?
It exposes 3 tools, including qloo_recommend, qloo_rank, qloo_capabilities.
What does the Taste Council do?
It turns personal preferences into Qloo signals to rank a shortlist of options, picking the choice that best satisfies everyone in a group.
Is the assistant's decision-making handled by an AI model?
No, the core decision logic, including the ranking algorithm and constraint checking, is performed by deterministic code rather than a language model.
Can I use this with Claude or ChatGPT?
Yes, it is reachable as an MCP server for clients like Claude and ChatGPT.