zotero-fulltext-mcp: Instructions file for Codex

AGENTS.md

Guidance for agents working in this repository.

Project Shape

This is a standalone, publishable project: a read-only-by-default pipeline that converts a Zotero library's linked PDF attachments to Markdown, builds a sidecar full-text search index, and exposes it through an MCP server (zotero-fulltext-mcp) plus a CLI (zotero-pdf-text).

• Source package: src/zotero_pdf_text.
• Tests: tests.
• Docs: docs (architecture, data dictionary, ingestion, operations, troubleshooting, library cleanup, debug-bridge setup, live Zotero test, planned figure extraction).
• What to work on next and why: ROADMAP.md.
• User-facing install/setup instructions: README.md.

This repository never contains anyone's actual Zotero data. A researcher's converted Markdown, FTS index, linked PDFs, and Zotero SQLite database all live in a separate location of their own choosing, referenced only through a config file. config.example.json is the only config file that belongs in this repo; real configs (config.json, config.<hostname>.json) are gitignored and must never be committed.

Configuration Contract

Do not invent a new config system — reuse what exists in src/zotero_pdf_text/config.py:

• ProjectConfig (frozen dataclass): zotero_root, zotero_data_directory, linked_attachments, output_root, plus tuning fields.
• resolve_config_path() resolution order: ZOTERO_PDF_TEXT_CONFIG env var → config.<hostname>.json (via platform.node()) next to cwd → config.json.
• validate_config() checks that all referenced paths exist on disk.

Because this repo's code and a researcher's config/data are expected to live in different locations (the code is a git clone, the data is wherever they keep their Zotero workspace), do not assume the config file lives next to the source tree. Prefer explicit --config/--db CLI arguments or the ZOTERO_PDF_TEXT_CONFIG env var over cwd-relative assumptions. The install-mcp CLI command (cli.py:_install_mcp) already generates MCP client registrations with both --db and --config baked in explicitly for exactly this reason — follow that pattern in any new code path that launches the server or CLI programmatically.