Skip to main content
Glama
Private cookbook MCP

Private cookbook MCP

by rickono

Private cookbook MCP

A private Python MCP service with SQLite FTS5, source-bound citations, and immutable publications. The 59-book EPUB catalog, including Chop Chop, is uploaded to private R2 storage and active on the existing Fly service. Full remote checksum readback, exact hosted index/inventory validation, 298 local MCP calls, and authenticated catalog/search/read checks through the connected app pass. Fifty-eight EPUBs have searchable text; the Alain Passard EPUB is image-only and awaits the separate OCR follow-up. PDF/DjVu ingestion remains deferred. The earlier two-book trial passed ChatGPT linking, cited reading, section artifacts, and the inline image viewer; original EPUB downloads through MCP remain unavailable. See Chop Chop publication status, earlier full EPUB publication, hosted runtime, and OCR resource isolation.

Local setup

Python 3.12+ and uv are required locally. OCR ingestion and OCR tests require the resource-isolated launcher, which uses a capped local Linux VM and container. Native Mac OCR is disabled after a memory-pressure incident. The ingestion/test image includes Poppler, DjVuLibre and English Tesseract; the deployed runtime image remains separate.

uv sync --frozen
python3 scripts/ocr_sandbox.py doctor
# Prepare cookbook-ocr:safe as described in docs/ocr-resource-isolation.md, then:
python3 scripts/ocr_sandbox.py run --output "$HOME/cookbook-mcp-data/poc/tests-NEW" -- python -m pytest -q -p no:cacheprovider --basetemp=/tmp/pytest tests
uv run ruff check --select F src tests scripts
uv run ruff format --check src tests scripts

uv.lock pins dependencies, including MCP 2.2.0 and fontTools for PDF font decoding. The explicit PYTHONPATH=src below also avoids an observed editable-install path issue on this Mac. Docker installs the package without editable mode.

For selected Calibre records with multiple formats, the builder indexes EPUB when available and backs up every file in the selected record directory. An AZW3 plus EPUB record therefore preserves both files and exposes the EPUB content. AZW3 alone is not supported for indexing. Without EPUB, a single PDF or DjVu format is required; its ingestion remains subject to OCR isolation and review.

Related MCP server: pergamos

One-command local fixture publication

From the repository root:

scripts/publish-fixture.sh /Users/rick/cookbook-mcp-data/poc/manual-run

This command verifies the existing approved snapshot, processes Calibre IDs 5 and 40, stores private derivatives outside Git, builds the index, publishes to a local filesystem object store, fully reads back and hashes every object, and confirms local runtime activation. Tu Casa Mi Casa (6), The Professional Chef (9), and The World Atlas of Wine (45) are excluded from this trial; their original snapshot and earlier OCR builds remain available. Required extraction/OCR failure stops before activation. It neither accesses the live Calibre database nor copies additional source books. Failed build directories are preserved for inspection.

The fixture backup contains the two selected record directories plus the snapshot catalog/preferences files. It is not a complete 56-book library backup: the copied catalog still references unselected records whose originals are intentionally absent in this POC. The MCP index exposes only the two selected books; administrative backup files have no tool/resource route. Full-library backup and selection review belong to the later authorized publisher workflow.

A build with flagged OCR pages exits with status 3 and leaves a private review report in its build directory. Review those pages, then use finalize-local to produce a new build without repeating extraction. See the review commands. Existing schema-1 builds, including build-3, remain readable/restorable but cannot be newly published under the approved review policy. Rebuild them before their next publication.

Authenticated transport test

PYTHONPATH=src uv run python scripts/validate_fixture.py \
  --store /Users/rick/cookbook-mcp-data/poc/store \
  --runtime /Users/rick/cookbook-mcp-data/poc/runtime \
  --report /Users/rick/cookbook-mcp-data/poc/transport-report.json \
  --expected-books 5 40 --inspector

The script creates a short-lived RSA signing fixture in memory, binds only to loopback, checks the nine-tool listing and exercises applicable EPUB tools with the official MCP client, runs the pinned Inspector CLI, saves only metrics and private QA images, and stops the server. It creates no OAuth authorization server. Auth0/Google/ChatGPT login remains an end-to-end deployment gate.

Photo lookup now separates list_images (captions/context), inspect_image (candidate pixels without the viewer), and get_image (final displayed photo). See image selection and client verification.

For a persistent local test server, cookbook serve-local --help describes the required public verification key, issuer, subject, store and runtime arguments. A private key or bearer token never belongs in Git. There is no static-key authentication mode and no public asset URL fallback.

Restore and rollback tests

PYTHONPATH=src uv run python -m cookbook.cli restore-local \
  --store /Users/rick/cookbook-mcp-data/poc/store \
  --destination /Users/rick/cookbook-mcp-data/poc/restored-copy

The destination must not exist. A complete restore verifies every manifest entry and reconstructs its logical tree. Runtime recovery restores only the index and lazily verifies content into a bounded cache. Runtime.activate(pointer) verifies/stages a chosen known pointer before switching. Runtime.rollback(pointer, expected_version=...) explicitly selects a retained publication, verifies its cached runtime and remote evidence, and conditionally updates the remote pointer before activation. Current withdrawals and approval revocations remain enforced when serving every retained version. Administrative restore paths never become MCP resources.

Use cookbook publication-status-local --store STORE --runtime RUNTIME to inspect remote and runtime pointers separately. recover-local with the same arguments verifies and activates the recorded remote version; rollback-local additionally requires --pointer FILE naming the retained publication and manifest digest. An activation acknowledgement failure after the remote write reports pending_activation; immutable staged objects and the previous runtime remain available for recovery. An unavailable hosted acknowledgement leaves runtime identity unconfirmed; local status reports the observed, verified runtime pointer. Neither recovery nor rollback creates an approval or undoes a review decision. New administrative revoke and confirm_error decisions require the shared serving object store (review-transcription --withdrawal-store STORE). A failed enforcement write can be retried using --withdrawal-id DECISION_ID. Legacy review history stays inspectable without inventing shared enforcement records.

The S3 adapter is exercised over HTTP against loopback Moto using synthetic data only. A gated publish-s3 CLI and authenticated acknowledgement are implemented; Mac browser PKCE login is implemented and live-verified; the EPUB trial upload and authenticated hosted acknowledgement have passed. Actual R2 permissions and conditional writes have passed synthetic provider tests. Multipart files above 5 GB remain unimplemented. The adapter refuses originals above 5 GB until multipart behavior is implemented and verified.

Container and sizing

docker build -t cookbook-mcp:poc .

The build context includes only code and dependency manifests. The image runs as an unprivileged user. scripts/benchmark.py is designed for a Docker run with --memory 1g --memory-swap 1g --cpus 1 --network none, a read-only object-store bind mount, and a fresh writable runtime mount. The default command runs the independent supervisor and hosted worker. HTTPS proxy settings, 60-second publication polling, and watchdog defaults are prepared in the trial deployment artifact; the approved existing-Machine cutover is complete.

Design seams

  • extract.py: EPUB spine/TOC/locators, conservative recipe structure, PDF/DjVu physical pages and bounded renders.

  • ocr.py / quality.py: corrected OCR copies, confidence triage, digest-bound human review, publication gate and new-build finalization.

  • build.py: snapshot validation, selected index, complete per-fixture inventory.

  • storage.py: streaming local/S3 storage, create-only writes and pointer preconditions.

  • publication.py: manifests, full verification, staged restore, atomic local activation, dry-run retention plans.

  • library.py: source-bound read-only queries and serialized bounded asset cache/rendering.

  • server.py: JWT resource-server checks, protected Streamable HTTP and embedded content.

  • hosted.py / supervisor.py: remote polling, authenticated activation acknowledgement and independent process recovery.

No cleanup of real snapshots, failed builds or publication objects is enabled. Retention deletion is tested only in disposable synthetic stores. Do not deploy this POC as production before resolving the report's deployment gates.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Provides a read-only API over a book catalogue, offering tools to search books, retrieve book details and series, and inspect provenance and source agreement data.
      -
    • F
      license
      A
      quality
      C
      maintenance
      Enables bibliographic research on a private local Calibre library by providing read-only metadata search, book inspection, and optional RAG-based content retrieval through MCP.
      5
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients to search a CWA book library, fetch titles from optional configured Z-Library sources, upload local EPUB/PDF files, and obtain verified CWA download links, with file transfer handled over short-lived authorized HTTP links rather than MCP messages. CWA itself performs ingestion and conversion, and write operations stay disabled until explicitly enabled.
      6
      22 npm
      MIT