Meeple Mind

Meeple Mind is an AI-powered board game companion that helps you find the perfect game, walks you through setup, and answers rules questions so you can spend less time preparing and more time playing!

Comment

Meeple Mind

Your always-ready board game companion, as a self-hosted MCP server for Alexa+.

Track: Alexa+ (self-hosted MCP server, MCP spec 2025-11-25, Streamable HTTP) Demo video: https://youtu.be/2VkRqgTk6LY Code: private GitHub repository, with the reviewers added as collaborators: https://github.com/habuma/meeple-mind Hosted server: https://mcp.meeple-mind.com/mcp (see Testing instructions)

Inspiration

I love playing board games. My personal collection has grown to more than 200 games, which creates a couple of problems. Sometimes I forget how to set up a game or can't remember a particular rule, bringing the game to a halt while I flip through a rulebook looking for clarification. Other times, the challenge starts before anything reaches the table: With so many games to choose from, deciding what to play can be surprisingly difficult. And once a game has been chosen, how do I set it up?

For years, I've wanted a voice-enabled Alexa experience that would let me simply ask questions about my games instead of searching through printed rulebooks. Building that kind of experience with the original Alexa SDK would have been difficult. With LLMs, retrieval-augmented generation (RAG), and Alexa+ adopting MCP as an integration model, the pieces are finally in place to build the board game companion I've always wanted.

What it does

Meeple Mind is an always-ready board game companion that helps you spend less time searching and more time playing. Whether you're staring at a shelf full of games wondering what to play or looking for something that fits your group and the time you have available, Meeple Mind can help narrow the choices. Tell it how many people are playing, how much time you have, or what kind of experience you're looking for, and it can help find the right game for the table. Results come back as a list of cards with box art, and tapping a publisher, category or mechanism on a card shows the other games that share it.

Once you've picked a game, Meeple Mind stays with you from setup through the final turn. Ask how many cards to deal, where pieces should go, or what changes with a different player count, and get the information you need without digging through a rulebook. The setup walkthrough is illustrated, so you can see where everything goes as well as hear it. During play, when an unusual situation brings the game to a halt, simply ask Meeple Mind how the rule works and get back to playing.

Meeple Mind turns the rulebooks and details for your game collection into an interactive companion that's there when you need it. From choosing tonight's game to getting everyone set up to settling that inevitable "Are you sure you can do that?" debate, Meeple Mind helps keep game night focused on the games and the people playing them.

It works in any MCP client. Clients that support MCP Apps (the mechanism I understand Alexa+ uses to show visual components on Echo Show) display the interactive cards; other clients get the same information as text.

How I built it

In addition to being a board game fanatic, I'm a longtime Java and Spring developer. Over the past few years, I've been heavily involved with Spring AI, a Java AI framework built on Spring and Spring Boot. Spring AI includes first-class support for building MCP servers, making it a natural foundation for Meeple Mind.

The Meeple Mind MCP server exposes five tools (search-games, list-categories-and-mechanisms, get-game-details, get-game-details-by-title and ask-rules-question) that allow an AI assistant to search a game collection, retrieve game details, and answer questions from game rulebooks. Game metadata is persisted in PostgreSQL using Spring Data JDBC. Rulebooks are broken into document chunks and stored in pgVector using Spring AI's vector store support, allowing Meeple Mind to retrieve the portions of a rulebook relevant to a player's question. Embeddings are calculated locally with all-MiniLM-L6-v2 (through Spring AI's Transformers/ONNX support), so no embedding API or API key is needed.

The MCP server is secured using OAuth 2.0 with Spring Security. For the hackathon demonstration, I use Claude Desktop as the conversational MCP client standing in for the Alexa+ experience, along with MCP Inspector for lower-level development and testing.

Meeple Mind runs locally with make and Docker, and it is also deployed to AWS: ECS Fargate for the server, RDS PostgreSQL with pgvector for the data, Amazon Cognito for OAuth sign-in, and a load balancer with HTTPS at mcp.meeple-mind.com. The deployment is described in CloudFormation templates and driven by one script. The project has around 90 automated tests, GitHub Actions CI that builds and tests every module, and a latency benchmark script.

Challenges I ran into

The biggest challenge was finding a suitable way to demonstrate the Alexa+ experience because Alexa+ developer tools are not yet broadly available. Claude Desktop turned out to be a great stand-in because it supports both MCP and MCP Apps, allowing me to demonstrate the same conversational interaction while exercising the real Meeple Mind MCP server behind it.

Another challenge was securing the MCP server with OAuth 2.0. I knew Spring Security provided the pieces I needed, but I hadn't previously applied them to an MCP server. That required some learning and experimentation before I had authentication working the way I wanted.

There was also an important design challenge: Meeple Mind needs to acknowledge when it doesn't know something. A rules assistant isn't useful if it confidently invents a ruling that isn't actually in the rulebook. Grounding answers in the supplied rulebooks lets Meeple Mind answer questions when the rules provide an answer while avoiding unsupported rulings when they don't.

Two smaller problems cost me time because they failed quietly. A tool whose filters were wrapped in a single object parameter worked when called one way and silently returned every game when a client sent the filters flat; I found it when the assistant listed all 10 games for a 5-player request, and fixed it by flattening the parameters. And the embedding model was being downloaded into a new temp folder on every start; a stable cache and a one-time make model step cut startup from about 14.6 s to 1.8 s. The full list is in FRICTION_LOG.md in the project repository.

Finally, I found (although not surprisingly) that the choice of LLM makes a difference. When testing using Sonnet 5.5, things would usually work the way I expected, but occasionally Sonnet would call the wrong tool or pass in an empty value for a tool's parameter. Although I added guidance in the tool descriptions, the LLM would still disregard those instructions and do what it thought best. When I started testing with Opus 5.5, I would get consistently good and expected behavior.

Accomplishments that I'm proud of

I'm especially proud of how much Meeple Mind can accomplish with only a handful of MCP tools. Those tools support the core game-night experience from beginning to end: finding a game that fits the group, getting the game set up, and answering rules questions once play begins.

I'm also pleased that the experience feels natural rather than technical. Players don't need to know anything about databases, vector stores, RAG, or MCP. They simply ask questions such as "What can five people play in under an hour?", "How do we set this game up?", or "Can I do this on my turn?" Meeple Mind handles the details behind the scenes.

Finally, I find the game setup feature to be incredibly useful and the centerpiece of the whole experience.

What I learned

The biggest takeaway from this project is how naturally MCP fits the Alexa+ programming model. I was already familiar with MCP and MCP Apps before starting Meeple Mind, but this project helped me see how well they can support conversational experiences that extend beyond a general-purpose AI assistant.

It also reinforced how valuable voice can be when the user's attention is somewhere else. At a board game table, nobody wants to stop playing, pick up a phone, search the web, or flip through a rulebook. Being able to simply ask a question and continue playing is exactly the kind of interaction where a conversational Alexa+ experience can shine.

Additionally, a technical lesson I learned is how much latency was involved in calculating embeddings when using a cloud-based embeddings API (OpenAI, specifically). Whenever I'd ask a question, the turnaround time was around 2 seconds. When I swapped in a local embeddings model (Transformers ONNX), it reduced the turnaround to well under half a second. I had no idea how much overhead was involved in calculating embeddings for the question being asked. Measured on a laptop with the server and database on one machine (200 calls per tool, one client), the server itself answers ask-rules-question, which embeds the question and searches the vectors, in 5.0 ms at p50 and 5.7 ms at p95; search-games takes 4.7 ms at p50 and 7.1 ms at p95. The AWS deployment adds network time on top of that.

What's next for Meeple Mind

Ultimately, I envision Meeple Mind as a multi-user service with a web-based hub for both gamers and game publishers. Today, its catalog is a single global collection populated manually using a rules-loader utility. A web hub would replace that process with two types of accounts:

  • Publishers could add games from their catalogs, including rulebooks, box art, and game metadata. Uploading a game would trigger background processing to extract game details, parse and chunk the rulebook, generate embeddings, and make the game available through Meeple Mind. Publishers could later update or retire their own titles.
  • Gamers could browse the available catalog and add games they own to their personal collections, allowing Meeple Mind to make recommendations based specifically on the games available on their shelves ("I liked Clockwork Cove, what else is like it?"), with suggestions both inside and outside the collection and an option to add or buy. Importing a collection export would make that quick to start.

Gamers could also add private rulebooks for homebrewed games, prototypes, out-of-print titles, or other games that aren't available through a participating publisher.

One significant gap in Meeple Mind's abilities right now is accounting for game expansions. When setting up or answering rules for a game for which an expansion may be used, it would be great if the answers and visuals were presented in a seamless manner as if the expansion were part of the game it expands.

I also see opportunity to leverage the work done in the step-by-step setup feature to create similar experiences to walk gamers through...

  • Example game play (e.g., what a user can do on each turn)
  • Special case rules where a simple answer could benefit from a visual
  • End of game scoring

Rulebook page citations in answers are another planned addition. These are described in the README's "Future work" section.

The goal is for Meeple Mind to grow from a useful game-night assistant into a bridge between publishers, players, and the games they love—while keeping the interaction as simple as asking a question.

How it uses the required technology

Meeple Mind is a self-hosted MCP server built with Spring AI and the MCP Java SDK 2.0. It implements MCP spec 2025-11-25 over Streamable HTTP (I checked that a client asking for 2025-11-25, or anything newer, is answered with 2025-11-25).

  • Five tools: search-games, list-categories-and-mechanisms, get-game-details, get-game-details-by-title, ask-rules-question.
  • Three prompts: recommend-games, explain-rules, game-details.
  • An MCP Apps UI resource (ui://meeplemind/game-app.html) rendered as interactive cards.
  • Two kinds of result for every search: compact text for the model, and structured data (with downscaled thumbnails) for the card.
  • OAuth2: the endpoint is an OAuth2 resource server. Locally it is backed by a small authorization server; on AWS, by Amazon Cognito. Clients are pre-registered. A clearly labeled development mode turns it off for local testing.

Built with

Java 25, Spring Boot, Spring AI (MCP server, Transformers embeddings, pgvector store), MCP Java SDK 2.0, MCP Apps, Spring Authorization Server, PostgreSQL with pgvector, Docker, Gradle, GitHub Actions, AWS (ECS Fargate, RDS, Cognito, Route 53, CloudFormation).

Demo and the Alexa+ experience

Amazon's documentation for building MCP add-ons for Alexa+ (the MCP toolkit quickstart and the MCP add-on design guide) covers requirements such as Streamable HTTP, OAuth 2.1 with PKCE and a 500 ms response budget, and I built to those and to the open MCP spec. Testing with Alexa+ itself is not widely available, and I did not have access to an Alexa+ device or the Alexa+ simulator, so I could not run Meeple Mind through Alexa+ end to end. The video shows the server working in Claude Desktop as the MCP client; a hackathon judge confirmed that it is suitable for the demo. The sample games, rulebooks and box art shown in the video are all AI-generated (see Sample content).

Testing instructions

The repository is private; the reviewers have been added as collaborators. The server is already running on AWS with the 10 sample games loaded, so the quickest way to try it is with Claude Desktop.

You need: Claude Desktop, Node.js (Claude Desktop connects through npx mcp-remote), python3, make, and a clone of the repository.

  • Server: https://mcp.meeple-mind.com/mcp (OAuth2 sign-in through Amazon Cognito)
  • Client id: 6f3q09p7uel4jjqppn56u315bk
  • Test login: gamer / mbKRf5717EsU4ZAa1

From the repository root:

MEEPLEMIND_URL=https://mcp.meeple-mind.com/mcp MEEPLEMIND_CLIENT_ID=6f3q09p7uel4jjqppn56u315bk make claude-desktop

Then quit and reopen Claude Desktop. The first connection opens a browser window on Cognito's sign-in page; sign in with the login above. MCP Jam and MCP Inspector also work: add the server URL, choose OAuth, and enter the client id (no client secret).

Things to try

  • "I have four friends coming over. What could we play in under an hour?"
  • "Which of these use worker placement?"
  • "How do you win Goblin IPO?"
  • "How do I set up Moonbase Farmers?"
  • Tap a category or publisher on a card to see related games.

Prefer to run it locally? No API keys or accounts are needed. You need Docker (running), make, Java 17 or newer (only to run Gradle; Gradle downloads JDK 25), and an MCP client. On Windows, use WSL 2. The first run downloads a ~87 MB embedding model from GitHub, so it needs internet access.

make setup           # checks Docker and Java, downloads the embedding model (once)
make load            # starts Postgres (pgvector) and loads the 10 bundled sample games
make server-insecure # starts the MCP server on http://localhost:3000/mcp, with OAuth turned off

Then connect an MCP client to http://localhost:3000/mcp (Streamable HTTP, no authentication). For example, MCP Jam: run npx @mcpjam/inspector@latest and add that URL. Goose, Claude Desktop (through mcp-remote) and LM Studio also work; see the README's "Testing the MCP server".

To test the OAuth-secured local server instead: make auth and make server, then sign in with the demo login gamer / letmein (see the README's "Security"). More detail is in QUICK_START.md in the project repository.

Sample content

The 10 bundled games, their rulebooks and their box art are fictional and were generated with AI, for a safe, copyright-free demo. I also tried the server with rulebooks from real, popular board games. Real rulebooks are not included because they are other people's copyrighted work.

Project timeline

The first commit is dated September 7, 2026, within the submission period; all of the work was done during it.

Product feedback

Tools and SDKs used: Spring AI 2.0.1, MCP Java SDK 2.0.0, MCP Apps, Spring AI Community MCP Security.

  • What worked well: the MCP annotations made a first server quick to build; protocol negotiation just worked; MCP Apps fits "text for the model, card for the person" results.
  • What needs work: defaults that fail quietly (entry 1 in the friction log), the model download behavior, and differences between MCP Apps hosts.
  • Onboarding experience: easy to start; harder for local OAuth setup and host differences.
  • Would I build with these again? Yes.

Built With

Share this project:

Updates

Submission history