openai-sdk-knowledge-org: Instructions file for Codex

AGENTS.md - Guide for AI Coding Agents

This file is a quick reference for AI coding agents such as Codex and Codex CLI. It summarises the project purpose, directory layout, development workflow, and verification steps required before submitting any patch.

Project Overview

• Name: OpenAI SDK Knowledge MCP
• Description: Serverless MCP (Model Context Protocol) server offering expert-level answers about OpenAI API usage, built with TypeScript, Cloudflare Workers, and OpenAI agents.
• Entry Point: src/index.ts (Cloudflare Worker)
• Documentation: See README.md for full project overview, architecture, and external guides.

Repository Structure

 src/
  ├─ agents/          # AI agent implementations (RAG, translation, summarization, etc.)
  ├─ pipeline/        # Data collectors and processors (GitHub, forums, embeddings)
  ├─ server/          # HTTP endpoints (MCP, web API) and middleware
  ├─ storage/         # Vector store and database initialization
  ├─ utils/           # Shared utilities (logger, rate limiter)
  └─ index.ts         # Worker bootstrap

src/__tests__/       # Unit and integration tests
package.json         # Scripts: build, dev, test, lint, deploy
wrangler.toml        # Cloudflare Workers configuration

Environment Setup

1. Ensure Node.js >=22 is installed.
2. Install dependencies:

   npm install
   

3. Copy env template and set keys:

   cp .dev.vars.example .dev.vars
   # Edit .dev.vars: add OPENAI_API_KEY, GITHUB_TOKEN (optional), etc.
   

Development Workflow

1. Start development environment:
   • Run npm run dev
2. Target endpoints:
   • Web UI: http://localhost:8787
   • MCP server: POST http://localhost:8787/mcp (requires an api token)
   • Web API: POST http://localhost:8787/api/query (requires a logged in session)

Note: Avoid running production scripts such as npm run deploy:prod or npm run db:migrate:prod from this environment.