Skip to main content
Glama

OpenAI Cookbook KG-RAG

A local retrieval toolkit that turns OpenAI Cookbook notebooks and Markdown into a searchable vector index and knowledge graph, then exposes the results through a CLI or MCP server.

The OpenAI Cookbook is an input corpus, not bundled source. This repository ships the ingestion, graph, retrieval, evaluation, CLI, and MCP implementation; cloned cookbooks, generated chunks, embeddings, caches, and SQLite databases remain local. Gemini is used for ingest-time embeddings and entity extraction, so live ingestion requires a Gemini API key. The smoke suite itself makes no live API calls.

Install and verify

Python 3.11 or newer is recommended. On Termux, --system-site-packages reuses native packages such as NumPy instead of attempting incompatible manylinux wheels.

python -m venv --system-site-packages .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
python smoke_test.py

In a fresh clone, data-integrity checks are reported as skipped because generated indexes are intentionally absent. All unit and source-level smoke checks should pass.

Related MCP server: docs-search-engine

Use it

Set GEMINI_API_KEY in the environment or in a gitignored .env.local, then ingest a local checkout of the Cookbook or another notebook/Markdown directory:

git clone https://github.com/openai/openai-cookbook.git openai-cookbooks
python openai-cookbook-agent.py --ingest --source ./openai-cookbooks --limit 10
python openai-cookbook-agent.py --build-kg
python openai-cookbook-agent.py --query "how do I stream responses?" --no-interactive

Run python openai-cookbook-agent.py --help for the complete CLI. Generated state is written beneath sources/, embeddings/, kg/, and .cache/; all are ignored.

MCP configuration

After installation and ingestion, add the server to your MCP client, replacing the placeholder with the checkout's absolute path:

{
  "mcpServers": {
    "openai-cookbook": {
      "command": "/absolute/path/to/openai-cookbook-kg-rag/.venv/bin/python",
      "args": [
        "/absolute/path/to/openai-cookbook-kg-rag/openai-cookbook-agent.py",
        "--serve-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "set-this-in-your-private-client-config"
      }
    }
  }
}

The server provides tools for semantic search, code exemplars, knowledge-graph statistics, and cached retrieval.

License

Apache-2.0. The separately cloned OpenAI Cookbook retains its own license and is not redistributed by this repository.

Available Tools

4 tools
find_exemplarA

Find canonical code examples for an OpenAI API pattern. Searches Jupyter code cells specifically. Use for: 'show me how to do X', 'canonical example of Y'.

Inputs: pattern (required), top_k.

get_docA

Retrieve a specific Cookbook document or chunk by its ID or partial source file path. Use after search_kg to read the full content.

Inputs: doc_id (required).

kg_statsA

Return corpus statistics: total chunks, KG nodes/edges, entity type breakdown, most-connected nodes.

Inputs: no named parameters.

search_kgA

Search the OpenAI Cookbook knowledge base using hybrid vector + KG-walk retrieval. Returns ranked passages with source references. Best for: API usage patterns, model comparisons, code examples.

Inputs: query (required), top_k.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation4/5

    search_kg and find_exemplar both handle code-example lookups, which could cause misselection, but their descriptions clarify the distinction (general retrieval vs. canonical Jupyter-cell examples). get_doc and kg_stats are clearly separate.

    Naming Consistency4/5

    Three tools follow a verb_noun pattern (search_kg, get_doc, find_exemplar), but kg_stats is a noun phrase, a minor deviation. Style is otherwise consistent (lowercase underscores).

    Tool Count5/5

    Four tools fit the server's read-only knowledge-base purpose well: search, retrieve, specialized search, and stats. Each earns its place without redundancy or bloat.

    Completeness5/5

    The domain is querying the OpenAI Cookbook, and the core workflow (search, retrieve full content, find code examples) is fully covered. kg_stats adds useful corpus metadata, and no obvious dead ends remain.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers