Example Notebooks
The examples/ directory contains Jupyter notebooks that demonstrate the
Perseus MCP workflow from direct endpoint exploration through full MCP tool
calling. Each notebook can be opened directly on GitHub or viewed through
nbviewer for a cleaner rendered notebook view.
00 Install and Run Perseus MCP
Explains the supported installation and launch options: PyPI with pip, isolated uv tools, repository-local development, MCP client configuration, verification, upgrades, uninstalling, and common setup failures.
01 Basic CTS Workflow
A minimal introduction to direct CTS requests. This notebook is useful for understanding the upstream CTS response shape before using the MCP tools.
02 Search and Navigation
Shows direct Scaife JSON search and CTS navigation using valid references. Use this notebook to see how search results and passage navigation relate.
03 MCP Connection: Homer Iliad
Demonstrates an in-process FastMCP client connection, Homer resource discovery, and Greek passage analysis for the Iliad.
04 MCP Greek Search and Navigation
Explores MCP Greek search with Unicode Greek and Beta Code input, valid references, and passage navigation through the exposed MCP tool surface.
05 MCP All Tools
Catalogs the full MCP tool set with descriptions and input schemas. This is a good reference notebook when learning what the server exposes to clients.
06 OpenRouter LLM MCP Interaction
Shows an optional OpenRouter LLM tool-calling loop over the local MCP tools,
using an OpenRouter API key supplied outside the repository and the
openrouter/free capability-aware router by default.
07 MCP Advanced Search Options
Demonstrates form search, lemma search, Scaife operator-preserving queries, and
author-scoped search through the search_perseus MCP tool.
08 MCP Cache and Search Tools
Demonstrates the advanced cache controls, paged reference helpers, server-scoped search, reader search, passage highlights, and Scaife metadata/text retrieval tools with runnable assertions.
09 OpenRouter Philo Politeia Analysis
Uses scoped Perseus MCP searches to collect cited evidence for πολιτεία in
Philo of Alexandria, then asks an OpenRouter-hosted LLM to synthesize the
evidence with URN citations and explicit limits on unsupported claims. It uses
the Free Models Router by default while recording the concrete resolved model.
10 MCP Latin Augustine Workflow
Uses language="latin" for CTS inventory discovery, selects Augustine’s
advertised Epistulae edition, retrieves valid references and Latin plaintext,
and performs a small reproducible token analysis.