ShayneP/livekit-python-examples-mcp

LiveKit Examples MCP Server

This repository wraps the in a Model Context Protocol (MCP) server so MCP-compatible clients can explore the catalog programmatically. The server can run either over HTTP (for hosted deployments) or stdio (for CLI integrations like Codex).

Project Layout

• app.rb – CLI entrypoint. Parses flags / env vars, chooses the transport, and boots the MCP server.
• server.rb – Declares the MCP server and its tools for browsing the example catalog.
• http_server.rb – Small Sinatra app that exposes the MCP JSON-RPC endpoint at POST /mcp plus a /health probe.
• transports/content_length_stdio_transport.rb – A stdio transport that understands Content-Length framed messages so editors and CLIs can stream requests reliably.
• python-agents-examples/ – Upstream LiveKit Agents examples, including docs/index.yaml with the metadata the tools surface.
• config.ru – Rack entry for bundle exec rackup deployments.

Setup

bundle install

The project depends on the mcp gem plus Sinatra/Rack components for the HTTP transport. Ensure your $GEM_HOME and $GEM_PATH are writable; app.rb attempts to fall back to standard per-user gem directories when they are unset.

Running the MCP Server

HTTP transport (default)

bundle exec ruby app.rb --http

• Listens on Sinatra's default localhost:4567 unless you override it.
• Configure with --port / --bind CLI flags or environment variables PORT / BIND.
• POST /mcp accepts JSON-RPC 2.0 requests targeting the MCP server.
• GET /health returns a JSON readiness payload: { "status": "ok", "name": "livekit_examples_server" }.
• Suitable for hosting behind a reverse proxy or running under Rack via bundle exec rackup (uses config.ru).

Stdio transport

bundle exec ruby app.rb --stdio

• Streams JSON-RPC requests and responses via stdin/stdout, framing each payload with a Content-Length header when provided.
• Designed for MCP clients that communicate over pipes (e.g., editors or terminal-based agents).

The transport mode can also be selected with --transport http|stdio or the MCP_TRANSPORT environment variable. When omitted, HTTP is used.

MCP Tools

server.rb registers four tools on an MCP::Server instance named livekit_examples_server:

• ReadExampleIndexFile – Returns the entire docs/index.yaml catalog as YAML so clients can inspect the available examples.
• ReadExampleFile – Reads a specific example file by its file_path (as listed in the index). Paths are sanitized to stay within the python-agents-examples directory.
• ListExampleCategories – Extracts distinct categories from the index for quick discovery.
• SearchExamples – Performs a keyword search across example titles, descriptions, tags, and demonstrations, returning matching entries.

All tools wrap their responses in MCP::Tool::Response objects and include defensive error messages for missing files or malformed input.

Working With the Example Catalog

The bundled python-agents-examples directory is pulled from LiveKit's official examples repository. The tools expect the structure shipped here, particularly docs/index.yaml for metadata. If you update or replace the catalog, keep the directory layout consistent so the sanitization checks in ReadExampleFile continue to allow only in-repo paths.

Development Notes

• The stdio transport extends MCP::Server::Transports::StdioTransport, adding support for Content-Length framed messages and newline-delimited fallbacks.
• Exceptions raised while handling HTTP requests surface as 500 responses with a JSON error payload so clients can log meaningful diagnostics.
• To integrate with other Rack tooling (e.g., Puma), rely on config.ru and the gems specified in Gemfile (puma, rackup).