perseus-mcp 1.0.0__tar.gz

perseus_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tony Jurg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

perseus_mcp-1.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+include server.json
+recursive-include docs *
+prune docs/_site

perseus_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,356 @@
+Metadata-Version: 2.4
+Name: perseus-mcp
+Version: 1.0.0
+Summary: MCP server for Perseus Greek and Latin text research
+Author: Tony Jurg
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tonyjurg/Perseus-mcp
+Project-URL: Documentation, https://tonyjurg.github.io/Perseus-mcp/
+Project-URL: Repository, https://github.com/tonyjurg/Perseus-mcp
+Project-URL: Issues, https://github.com/tonyjurg/Perseus-mcp/issues
+Keywords: mcp,model-context-protocol,perseus,classics,ancient-greek,latin,cts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=2.12.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Dynamic: license-file
+
+[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20708961-007ec6.svg)](https://doi.org/10.5281/zenodo.20708961) [![Python](https://img.shields.io/badge/Python-3.x-blue?logo=python)](https://www.python.org/) ![Jupyter](https://img.shields.io/badge/Jupyter-F37626?logo=jupyter&logoColor=white) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/tonyjurg/Perseus-mcp)
+
+# Perseus-mcp
+
+*Give Claude / Cursor / Windsurf direct access to the Perseus Digital Library* — ancient Greek and Latin texts, precise CTS navigation, plaintext, search, and more.
+
+A high-quality MCP server for Classical Greek and Latin literature. It runs as a local FastMCP server so MCP-capable applications can attach these Perseus tools to the LLM/model provider of your choice.
+
+## Features
+
+This server exposes twenty-three MCP tools. Every tool returns a text payload: some
+are raw Perseus CTS XML or Scaife JSON, while the discovery and plaintext
+helpers return locally shaped JSON or readable text.
+
+- `get_passage(urn)` — fetch a CTS passage by URN.
+- `get_passage_plus(urn)` — fetch passage text plus contextual metadata.
+- `get_passage_plaintext(urn)` — fetch a CTS passage as plain readable text.
+- `get_valid_references(urn, level=None)` — retrieve navigable citation references for a work or edition.
+- `get_valid_references_json(urn, level=None, limit=100, offset=0)` — retrieve paged citation references as JSON.
+- `count_valid_references(urn, level=None)` — count valid references without returning the full list.
+- `get_capabilities()` — list available texts/editions from Perseus CTS.
+- `get_cache_status()` — inspect local metadata cache state.
+- `refresh_metadata_cache()` — refresh cached CTS capabilities.
+- `clear_metadata_cache()` — clear in-memory and disk metadata cache entries.
+- `list_text_groups(language=None, query=None, limit=100)` — list matching authors/textgroups and works.
+- `get_author_resources(author, language=None)` — list works, editions, and translations for a matching author name or CTS textgroup URN.
+- `find_author_names(query, language=None, limit=100)` — find author/textgroup names by partial name match.
+- `get_work_resources(urn_or_title, language=None)` — list editions, translations, and resources for a work, optionally filtered by original language.
+- `get_label(urn)` — fetch human-readable metadata labels for a URN.
+- `get_first_urn(urn)` — get the first navigable URN under a work/edition.
+- `get_prev_next_urn(urn)` — get neighboring passage URNs for navigation.
+- `search_perseus(query, language="greek", query_format="auto", author=None, search_kind="form", preserve_operators=False, page_num=1, text_group=None, work=None, result_format="instances")` — search texts via Scaife search API. Greek queries may be entered as Unicode Greek (for example `μῆνιν`) or Beta Code (for example `mh=nin`).
+- `search_within_text(query, text_urn, ...)` — search within a single Scaife text/edition URN.
+- `get_passage_highlights(query, passage_urn, ...)` — get Scaife token highlight positions for one passage.
+- `get_scaife_library_metadata(urn)` — get Scaife JSON metadata for a library URN.
+- `get_scaife_passage_json(urn)` — get Scaife JSON for a passage URN.
+- `get_scaife_passage_text(urn)` — get Scaife plaintext for a passage URN.
+
+## Greek Search Input
+
+`search_perseus` normalizes Greek search terms before sending them to Scaife.
+You can pass Unicode Greek directly, or use Beta Code such as `mh=nin a)/eide`.
+The default `query_format="auto"` detects explicit Beta Code marks like `=`, `/`, `(`, `)`, and `*`, and also treats short unaccented Greek-looking queries such as `logos` as Beta Code.
+If an ASCII query is ambiguous, set `query_format="betacode"` to force conversion or `query_format="unicode"` to preserve it exactly.
+Search queries are normalized to composed Greek Unicode (NFC), matching sampled Perseus Greek text.
+The tool uses Scaife's JSON search route and returns the JSON response as text.
+The `language` argument controls Greek query normalization; it is not currently
+sent to Scaife as a corpus language filter.
+For CTS inventory discovery, `list_text_groups`, `find_author_names`,
+`get_author_resources`, and `get_work_resources` accept `language="greek"` or
+`language="latin"` (and common codes such as `grc` or `lat`) as an actual work
+language filter. Passage and navigation tools use CTS URNs, whose
+`greekLit`/`latinLit` namespace and edition identifier already select the text.
+Pass `author` to resolve a CTS author/textgroup name or URN. When it resolves
+to exactly one textgroup, Scaife receives a server-side `text_group` filter;
+ambiguous matches fall back to local CTS URN-prefix filtering of the current
+result page.
+Use `search_kind="lemma"` for lemma search; the default `search_kind="form"`
+keeps existing form-search behavior. For Scaife operator queries such as
+quoted phrases, `-`, `|`, `*`, or `~`, set `preserve_operators=True` so Beta
+Code auto-detection does not consume operator characters. For example:
+`search_perseus('"μῆνιν ἄειδε"', query_format="unicode", preserve_operators=True)`,
+`search_perseus("μῆνιν -ἄειδε", query_format="unicode", preserve_operators=True)`,
+or `search_perseus("λόγος | ἀνήρ", search_kind="lemma", query_format="unicode", preserve_operators=True)`.
+Use `page_num` for pagination and pass `text_group` or `work` to use Scaife's
+server-side scope filters. When `author` resolves to exactly one CTS textgroup,
+`search_perseus` sends that textgroup to Scaife instead of filtering only the
+returned page locally.
+
+## Local Metadata Cache
+
+Discovery and navigation tools cache stable CTS metadata locally to avoid
+repeated multi-megabyte `GetCapabilities` and `GetValidReff` requests. The
+default disk cache lives in `.cache/perseus-mcp` under the current working
+directory and also uses an in-memory cache for the running server process.
+Configure it with:
+
+- `PERSEUS_MCP_CACHE_DIR` — override the disk cache directory.
+- `PERSEUS_MCP_CACHE_TTL_SECONDS` — set cache TTL; default is 86400 seconds.
+- `PERSEUS_MCP_DISABLE_CACHE=1` — disable both memory and disk cache reads/writes.
+
+The current working directory is the directory from which the Python process is
+started. Running the MCP server from the repository root uses
+`.cache/perseus-mcp`; running a notebook from `examples/` would otherwise use
+`examples/.cache/perseus-mcp`. That is not a second server instance, only a
+second cache location for a separate Python process. To keep one cache location
+across notebooks and MCP clients, set `PERSEUS_MCP_CACHE_DIR` to an absolute
+path such as `/path/to/Perseus-mcp/.cache/perseus-mcp`.
+
+## URN Discovery
+
+Available edition URNs can differ between Perseus CTS and Scaife search results,
+and the live inventory can change. Use `get_author_resources`,
+`get_work_resources`, or `list_text_groups` before constructing
+edition-specific CTS passage URNs. The notebooks select advertised CTS editions
+from discovery results instead of assuming that a Scaife edition URN is valid
+for Perseus CTS.
+
+The live Perseus CTS implementation may return malformed HTML for
+`GetFirstUrn` and `GetPrevNextUrn`. The MCP tools detect that response and
+derive valid XML results from `GetValidReff`.
+
+## Setup
+
+### 1) Install dependencies
+
+Using `uv`:
+
+```bash
+uv sync
+```
+
+Or with `pip`:
+
+```bash
+pip install -e .
+```
+
+Once a release is published to PyPI, users can install it without cloning the
+repository:
+
+```bash
+pip install perseus-mcp
+```
+
+For development and tests:
+
+```bash
+pip install -e ".[dev]"
+```
+
+### 2) Run tests
+
+```bash
+pytest
+```
+
+With `uv`, use:
+
+```bash
+uv run --extra dev pytest
+```
+
+### 3) Run locally
+
+```bash
+uv run server.py
+```
+
+The installed console command and module entry point are equivalent:
+
+```bash
+perseus-mcp
+python -m perseus_mcp
+```
+
+### 4) Inspect tools (optional)
+
+```bash
+npx @modelcontextprotocol/inspector uv run server.py
+```
+
+
+## Example notebooks
+
+The `examples/` directory includes Jupyter notebooks that demonstrate both direct endpoint calls and MCP client usage with real Greek and Latin data:
+
+- `examples/01_basic_cts_workflow.ipynb` — minimal direct CTS requests.
+- `examples/02_search_and_navigation.ipynb` — direct Scaife JSON search and CTS navigation from valid references.
+- `examples/03_mcp_connection_homer_iliad.ipynb` — FastMCP client connection, Homer resource discovery, and *Iliad* Greek passage analysis.
+- `examples/04_mcp_greek_search_and_navigation.ipynb` — MCP Greek search with Unicode/Beta Code, valid references, and passage navigation.
+- `examples/05_mcp_all_tools.ipynb` — complete MCP tool catalog with descriptions and input schemas.
+- `examples/06_openrouter_llm_mcp_interaction.ipynb` — optional OpenRouter LLM tool-calling loop over the local MCP tools, using NVIDIA Nemotron 3 Super (free) by default.
+- `examples/07_mcp_advanced_search_options.ipynb` — MCP form/lemma search, Scaife operator queries, and author-scoped search examples.
+- `examples/08_mcp_cache_and_search_tools.ipynb` — advanced demonstration of cache tools, paged references, scoped search, reader search, highlights, and Scaife metadata/text retrieval.
+- `examples/09_openrouter_philo_politeia_analysis.ipynb` — OpenRouter-assisted, evidence-first analysis of `πολιτεία` in Philo of Alexandria using scoped MCP search results and cited passages.
+- `examples/10_mcp_latin_augustine_workflow.ipynb` — Latin-language discovery, CTS navigation, passage retrieval, and a small text analysis using Augustine's *Epistulae* selections.
+
+Run them after installing the project dependencies. The MCP notebooks use
+FastMCP's in-process client transport and call the same tools exposed to
+external MCP clients. The optional OpenRouter notebook also requires an
+OpenRouter API key; the MCP server itself does not.
+
+### Configure the OpenRouter API key
+
+For `examples/06_openrouter_llm_mcp_interaction.ipynb` and
+`examples/09_openrouter_philo_politeia_analysis.ipynb`, copy `.env.example` to
+`.env` in the project root and replace the placeholder:
+
+```dotenv
+OPENROUTER_API_KEY=sk-or-v1-...
+```
+
+Get your API key at [openrouter.ai](https://openrouter.ai/settings/keys). See
+[OpenRouter's API key documentation](https://openrouter.ai/docs/api-keys) for
+authentication details.
+The `.env` file is ignored by Git. You can also set `OPENROUTER_API_KEY` in your
+environment or enter it securely when the notebook prompts.
+
+Notebook `06_` can be saved and committed with its LLM and tool-call outputs so
+they render on GitHub. Python variables and kernel memory are not stored in an
+`.ipynb` file, and the notebook does not print the API key. Before committing a
+credentialed run, review the visible outputs and scan for a full OpenRouter key:
+
+```bash
+rg "sk-or-v1-[A-Za-z0-9_-]{20,}" examples/06_openrouter_llm_mcp_interaction.ipynb
+```
+
+The command should produce no output. It does not match the documented
+`sk-or-v1-...` placeholder.
+
+## Using with any MCP-capable LLM client
+
+This project does not require a specific LLM. Configure your client to launch the local MCP server with:
+
+```bash
+uv --directory /full/path/to/Perseus-mcp run server.py
+```
+
+Most MCP clients need the same pieces: server name `perseus`, command `uv`, args `--directory /full/path/to/Perseus-mcp run server.py`, and an empty environment unless you have local customizations. See `docs/enduser.md` for generic client guidance and `docs/architecture.md` for the architecture choices, including why FastMCP is used.
+
+### Claude Desktop and Claude Code
+
+The server runs with Claude over stdio, with no OpenRouter or API key required (OpenRouter is only needed for the optional demo client).
+
+**Claude Desktop** — add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "perseus": {
+      "command": "uv",
+      "args": ["--directory", "/full/path/to/Perseus-mcp", "run", "server.py"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop; the Perseus tools appear in the tools list.
+
+**Claude Code** — one line:
+
+```bash
+claude mcp add perseus -- uv --directory /full/path/to/Perseus-mcp run server.py
+```
+
+Verified against a stdio MCP handshake: all 23 tools register and live calls return (tested with `search_perseus` and `list_text_groups`).
+
+## Build a PyPI distribution
+
+Install the development dependencies, then build and validate both distribution
+formats:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m build
+python -m twine check dist/*
+```
+
+The build creates a wheel and source archive under `dist/`. Test the wheel in a
+clean virtual environment before publishing. Upload to TestPyPI first:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+After verifying installation from TestPyPI, upload the same artifacts to PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+PyPI does not allow replacing an existing release. Update `project.version` in
+`pyproject.toml`, rebuild from a clean `dist/` directory, and publish each
+version only once. The package build workflow also builds and checks artifacts
+in CI without publishing them.
+
+### Automated GitHub release and PyPI publishing
+
+The release automation follows the same trusted-publishing pattern as
+MorphKit:
+
+1. Set the release version in `pyproject.toml`, for example `1.0.0`.
+2. Merge the version change to the commit that should be released.
+3. Create and push the matching tag, for example `v1.0.0`.
+4. The `Build release artifacts` workflow verifies the tag/version match,
+   builds and validates both distributions, and attaches them to a generated
+   GitHub release.
+5. That workflow dispatches `Publish to PyPI`, which rebuilds and validates the
+   package before publishing through PyPI trusted publishing.
+
+Configure the repository once before the first automated upload:
+
+- Create a GitHub Actions environment named `pypi`.
+- In the existing PyPI project settings, or as a pending publisher before the
+  first upload, add a trusted publisher for owner `tonyjurg`, repository
+  `Perseus-mcp`, workflow `publish.yml`, and environment `pypi`.
+- Do not add a PyPI API token; the workflow uses GitHub OIDC with
+  `id-token: write`.
+
+The workflows reject a tag such as `v1.1.0` when `project.version` is still
+`1.0.0`. PyPI versions are immutable, so increment the version before retrying
+a release that was already uploaded.
+
+## Contributing and reporting issues
+
+Bug reports, documentation fixes, focused feature requests, and pull requests
+are welcome. Please report problems through the GitHub issue tracker and include
+the command, Python version, MCP client, tool arguments, traceback, and any
+relevant CTS URN or Greek search query when possible.
+
+See `docs/contributing.md` for contribution guidance.
+
+## Responsible disclosure
+
+This project was created with assistance from OpenAI Codex. The human
+maintainer remains responsible for reviewing, testing, and accepting all code
+and documentation changes.
+
+## License
+
+This project is released under the MIT License. See `LICENSE` for details.