greenroom

A python package containing an MCP server that coordinates outreach to multiple LLMs, integrates with external content providers, and provides custom tooling to agents with the goal of producing high-value, hybrid human-AI curation of entertainment recommendations.

As of 2026, greenroom provides recommendations on film and television content. I plan to integrate with additional data providers and LLM services to broaden the offering.

Discover films and television using hybrid human-AI curation

Compare outputs of multiple agents and models

Use Cases

The greenroom MCP server can be used to answer a wide range of questions related to entertainment. Below are some example prompts that will trigger the use of multiple MCP tools, but these are just examples.

Recommendations

• What kinds of entertainment can you recommend?

• I'm in the mood for something serious. Recommend some entertainment content.

• Recommend spanish language documentary films from the 2010s.

• I loved Atlanta and Black Mirror. Recommend other entertainment options that I would like.

Event Planning

• I'm hosting a French film night. Recommend highly-rated French films across genres.

• Plan a binge-watching weekend including recent dramas and comedies.

• Let's host a sci-fi movie marathon. Recommend 5 sci-fi films from different decades.

Industry Analysis

• Analyze which genres have the highest average ratings in film vs television.

• Compare action films made in the 1980s to those made in the 2020s.

• What are the top-rated spanish language television shows in each genre?

Compare the output of multiple agents

• Using compare_llm_responses, what makes a great science fiction film?

• Using the compare_llm_reponses tool, how is machine learning used in modern filmmaking?

Features

Tools

MCP tools are callable actions, analogous to POST requests, that an agent executes. They are annotated with @mcp.tool() in the FastMCP framework.

Tools for the greenroom server include:

• list_genres - Fetches all entertainment genres, returning a unified map showing which media types support each genre

• categorize_genres - Maps human moods to media genres to improve hit rate from human prompts

• discover_films - Retrieves films based on discovery criteria, returning metadata for informed reponses and improved categorization

• discover_television - Retrieves television shows based on discovery criteria, returning metadata for informed responses and improved categorization

NB: The

Coordination of Agents

This server supports the coordination of multiple agents to work on a single task.

• compare_llm_responses - Receives a prompt and fields it out to two agents. It constrains the responses by temperature and token limit.

To trigger this tool, ask Claude: Using the compare_llm_reponses tool, why is the ocean blue?

You should see: 
  Both Claude* and Ollama responses 
  Response lengths comparison
  Structured JSON output showing both LLM outputs side-by-side

As of 2026, this defaults to comparing the response from a resampling of the anthropic client to a response from a new ollama client. Generally, the resampled response will be null because anthropic forbids resampling. I hope to broaden the capabilities to a wider selection of LLM clients soon.

Contexts

Context-aware tools use FastMCP's Context parameter to access advanced MCP features like LLM sampling.

Example:

• list_genres_simplified - Returns a simplified list of genre names by using ctx.sample() to leverage the agent's LLM capabilities for data transformation.

Resources

These resources provide read-only data, analogous to GET requests. An agent reads the information but does not performa actions. Resources are annotated with @mcp.resource() in the FastMCP framework.

• config://version - Get server version

Error Handling

All errors raised by the greenroom server use a custom exception hierarchy rooted in GreenroomError. This means MCP callers can catch GreenroomError to handle any server-side failure, or catch a specific subclass for finer control:

• APIResponseError - HTTP errors, invalid JSON, unexpected response bodies from external APIs

• APIConnectionError - Network or connectivity failures when reaching external APIs

• APITypeError - Response had an unexpected Python type after deserialization

• SamplingError - Errors during LLL sampling

Built-in exceptions like ValueError are still raised for input validation (e.g., invalid parameters).

Architecture

Tools Layer (MCP Interface)
    ↓
Services Layer (Business Logic)
    ↓
Client Layer (Provider-specific HTTP Communication)
    ↓
Models Layer (Provider-agnostic Data Structures)

Project Structure

This project follows the python package src/ layout to support convenient packaging and testing. Below is a simplified diagram of the project.

greenroom/                          # project root
├── src/
│   └── greenroom/                   # python package
│       │
│       ├── server.py                # primary entry point to server
│       ├── config.py                # centralized configuration
│       ├── utils.py                 # shared utilities
│       │
│       │
│       ├── models/                  # data models     
│       │
│       ├── services/                # business logic 
│       │   ├── llm/                 # LLM agent services and clients
│       │   ├── tmdb/                # TMDB provider services and clients
│       │   └── protocols.py         # standardizes methods across media providers
│       │
│       └── tools/                   # MCP tools (exposed via FastMCP)
│            ├── agent_tools.py      # coordinate multiple agents and LLMs
│            ├── discovery_tools.py  # search for specific entertainment content
│            └── genre_tools.py      # optimize genre discovery and presentation to user
│
├── tests/greenroom/                 # test suite
│
├── pyproject.toml                   # configuration and dependencies
└── uv.lock                          # dependency lock file (auto-generated)

Dependencies

• Python 3.12

• FastMCP >=2.13.0 - MCP server framework; requires Python 3.10+

• uv - package manager; installation instructions

• Hatchling - build system

• httpx - for API calls to TMDB (community-driven database)

• python-dotenv - for API key management

• Ollama (optional) - local LLM runtime for multi-agent tools like compare_llm_responses; installation instructions

This project uses the See

Setup

1. Create local development environment

# Clone the repository
git clone <repository-url>
cd greenroom

# Install dependencies (uv will create a virtual environment automatically)
uv sync

2. Add TMDB api key as environment variable

• Get a free API key at TMDB by creating an account, going to account settings, and navigating to the API section.

• Create a file called .env at the top level of the project. (This file is gitignored to prevent committing secrets.)

• Copy the content of .env.example to your new file.

• Replace your_tmdb_api_key_here in .env with the actual TMDB API key.

(optional) Setup Ollama

To use Ollama as a second agent (in addition to Claude). An example of usage is the compare_llm_responses tool.

1. Install Ollama

# macOS
brew install ollama

# Or download from https://ollama.com/download

2. Start Ollama service

# macOS (Ollama runs as a background service after installation)
ollama serve

# Or simply open the Ollama application

3. Pull the default model

# The compare_llm_responses tool defaults to llama3.2:latest
ollama pull llama3.2

# Verify the model is available
ollama list

4. Test Ollama is working

 curl http://localhost:11434/api/generate -d '{"model": "llama3.2", "prompt": "Why is the sky blue?", "stream": false}'
 
 # expected response might be something like
 {
   "model":"llama3.2",
   "created_at":"2025-11-30T12:01:32.314915Z",
   "response":"The sky appears blue because of a phenomenon called Rayleigh scattering...
   ...
 }

Development

Run the MCP Server Locally

The server will start and communicate via stdin/stdout. It uses stdio by default, which is the standard transport for local MCP servers.

# best approach uses the MCP entry point
uv run greenroom

# alternative: via python
uv run python src/greenroom/server.py

NB: You should not run the server directly (e.g.

Inspect using MCP Inspector (web ui)

npx @modelcontextprotocol/inspector uv --directory /ABSOLUTE/PATH/TO/PROJECT run python src/greenroom/server.py

Run tests

uv run python -m pytest

# alternative to printout test names for quicker debugging
uv run python -m pytest -v

# only run static type checker
uv run mypy src/greenroom/

Interacting with the MCP Server

This project does not yet include a frontend with which to exercise the server, but you can use anthropic tooling to interact with the server.

via Claude Code

1. Start the server

   # update local claude settings and run the MCP server
   claude mcp add greenroom -- uv --directory /ABSOLUTE/PATH/TO/PROJECT run python src/greenroom/server.py

2. Open claude code

   • Enter /mcp to view available MCP servers.

   • Confirm that greenroom is one of them with status: connected.

3. Exercise the server

   • Resources can be referenced with @ mentions

   • Tools will automatically be used during the conversation

   • Prompts show up as / slash commands

   • To explicitly test a tool, ask claude to call the tool. e.g. Call the <name-of-tool> tool from the MCP server called greenroom.

When you update the methods on the MCP server, you must rerun the above steps in order for the updates to be available to the claude session.

via Claude Desktop

1. Download Claude Desktop app here.

2. Open the claude desktop app.

3. Confirm the desktop app is connected to the greenroom server:

   • Navigate to Settings.

   • Click on "Developer". Local MCP Servers should appear.

   • The greenroom server should be listed there and it should have status: running.

   • If it is not running, click on 'Edit Config'. Then follow the instructions in the Troubleshooting section below.

Troubleshooting

Confirm correctness of local claude settings / configuration.

When you run the set up command (claude mcp add), a configuration for that MCP server is added to your local claude settings. Claude stores them in a file called claude_desktop_config.json. These settings are what will be used by the claude desktop app to connect to the MCP server.

• Align your local configuration with the below.

• Replace /ABSOLUTE/PATH/TO/PROJECT with the actual path to the project directory (not the package directory) on your local machine.

• Replace /ABSOLUTE/PATH/TO/UV/LIBRARY with the actual path to uv on your local machine.

{
  "mcpServers": {
    "greenroom": {
      "command": "/ABSOLUTE/PATH/TO/UV/LIBRARY",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PROJECT",
        "run",
        "python",
        "src/greenroom/server.py"
      ]
    }
  }
}

When experiencing configuration issues, sometimes it helps to remove the mcp server from your local machine and add it back again.

# remove the local configuration
claude mcp remove greenroom

# update the local configuration and run the MCP server
claude mcp add greenroom -- uv --directory /ABSOLUTE/PATH/TO/PROJECT run python src/greenroom/server.py

How It Works

1. The pyproject.toml file declares the fastmcp dependency managed by uv

2. When an agent (e.g. claude code) starts, it launches this MCP server as a subprocess using the configured command

3. uv automatically manages the virtual environment and dependencies

4. The server advertises its available resources and tools (e.g. the tools/list JSON-RPC method)

5. During conversations, the agent can automatically call these tools when relevant

6. The server executes the requested tool and returns results to the agent

7. The agent incorporates the results into its response to you

Future Development

• Add more media types (e.g., podcasts, books)

• Add providers to augment data sources

• Create an entertainment concierge experience (e.g., manager agent flow)