openai-cookbook
Provides semantic search and knowledge-graph retrieval over OpenAI Cookbook notebooks and Markdown, enabling agents to query cookbook content for code examples and explanations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@openai-cookbook find a code example for using the embeddings API"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.pyIn 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-interactiveRun 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 toolsfind_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
Scored across 4 tools
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.
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).
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.
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
Related MCP Connectors
Search and manage your team's knowledge from MCP clients.
Agent-driven search: build, import, tune, search, and score result quality — all over MCP.
Read-only MCP server for the OrchestKit docs: full-text search + Markdown fetch. No auth.
Knowledge coverage map and health score. Ingest docs into a governed knowledge graph via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides semantic search over markdown documentation using RAG, allowing natural language queries and integration with MCP clients.1MIT
- FlicenseAqualityDmaintenanceEnables searching documentation from GitHub repositories and web pages via MCP tools, with in-memory indexing and caching for fast retrieval.3-
- AlicenseNot gradedqualityAmaintenanceEnables semantic code search across indexed codebases using natural language queries, with support for CLI and MCP interfaces.1MIT
- FlicenseCqualityDmaintenanceEnables semantic search over knowledge-base articles and listing of sample support tickets using MCP tools.4-