nanograph-mcp: Instructions file for Codex

nanograph-mcp

Scope

• This repository is a generic, source-agnostic toolkit for building and serving Nanograph graph databases over document corpora.
• It has two parts:
  1. a generic ingestion path that turns "here are papers" into a Nanograph seed and a loaded .nano database (a book is just one very large paper);
  2. a generic MCP wrapper that exposes Nanograph retrieval over one or more datasources to MCP clients.
• Nothing in the shared code should be specific to one named corpus.
• The wrapper is intended to be publicly reachable without authentication for public datasources. Confidential datasources must remain a separate datasource mounted only inside the confidentiality boundary and must never be exposed publicly.

Project Plans and State

• Plans are written in Org mode, not Markdown.
• nanograph-mcp plans live under ~/Org/plans/nanograph-mcp/.
• The main project note is ~/Org/nanograph_mcp.org.
• The resumable current-state note is ~/Org/agents/projects/nanograph-mcp-state.org.

These Org files may not all exist yet; create them in these canonical locations when planning begins rather than leaving design decisions only in chat or in local scratch files. Start from the plans/state notes before making non-trivial changes, and update them when the design or intended workflow changes.

Design Intent

Recorded so the separate planning work starts from a shared picture; settle the detail in the Org plan, not here.

• Generic ingestion. Input is a set of papers (PDFs or extracted text); output is a Nanograph seed and .nano. A single-book datasource is the degenerate single-paper case. Multi-paper corpora additionally want paper-level metadata (authors, year, identifier) and a real Cites: Paper -> Paper edge.
• Multi-datasource. One wrapper serves several .nano databases via a registry of datasource name to home / .nano path / embedding configuration.
• Binding strategy. Open question for the plan: a C ABI / library binding or a long-lived process versus the current per-call CLI shell-out. The CLI re-attaches the database per call, which is poor for interactive retrieval; a persistent binding keeps each .nano and its embedding client warm.
• Embedding consistency. Each datasource must be queried with the same embedding model it was built with; the registry carries per-source embedding configuration so queries are never embedded with the wrong model.