Contributing and Reporting Issues

Contributions, bug reports, documentation fixes, and reproducible examples are welcome. This project is intentionally small, so the most useful contributions are focused changes that improve reliability, documentation clarity, tool behavior, or test coverage.

Report Bugs or Errors

Please report problems through the repository issue tracker: github.com/tonyjurg/Perseus-mcp/issues. Use the issue template that best matches the problem:

• bug or error report;
• feature request;
• documentation issue;
• upstream data or service issue.

When reporting an error, include as much of the following as possible:

• the command you ran;
• your Python version;
• whether you used uv, pip, an MCP client, or MCP Inspector;
• the tool name and arguments, if the problem happened during a tool call;
• the full error message or traceback;
• a short example that reproduces the problem;
• whether the problem appears to come from the local server or from an upstream Perseus/Scaife response.

For Greek search or CTS passage issues, include the query text or URN you used. If the response looks wrong, include the relevant returned XML, JSON, or plain text excerpt.

Request Features

Feature requests are easiest to evaluate when they describe the research or client workflow they would support. Please include:

• the task you are trying to complete;
• the current workaround, if any;
• the expected tool behavior or output shape;
• links to upstream Perseus, Scaife, CTS, or MCP documentation when relevant.

Contribute Code

Before opening a pull request, install the development dependencies and run the test suite:

pip install -e ".[dev]"
pytest
ruff check src tests

With uv:

uv run --extra dev pytest
uv run --extra dev ruff check src tests

Keep pull requests narrowly scoped. A good pull request usually contains:

• a clear description of the change;
• tests for changed behavior;
• documentation updates when the user-facing tool surface changes;
• notes about any upstream Perseus or Scaife behavior that influenced the implementation.

Security and Credentials

Do not commit API keys, local .env files, notebook secrets, or private client configuration. The .env.example file documents expected environment variables without storing real credentials.

CI blocks pull requests and direct pushes to main or development that contain an OpenRouter key-like token matching sk-or-v1-[A-Za-z0-9_-]{20,} in tracked files. Feature branches run the same checks through their pull request without duplicating the workflow on push.