AGENTS.md

This file provides guidance to agents when working with code in this repository.

Build & Run

• Build: npm run build (compiles TypeScript to dist/)
• Dev mode: npm run dev (runs source directly with tsx)
• Test MCP: npm run inspector (opens MCP inspector)
• Generate embeddings: npx tsx src/generate-embeddings.ts (one-time setup, requires Qdrant)

Architecture (Non-Obvious)

• MCP server: src/index.ts - Stdio transport only, no HTTP
• Embedding script: src/generate-embeddings.ts - Standalone, run once
• Documentation: docs/ - AI-summarized from cairo_coder_AI, not raw Cairo docs
• Examples: examples/ - Full Scarb projects, not just .cairo files
• Qdrant: Must be running on localhost:6333 for semantic search to work

Critical Dependencies

• Gemini API key required for embeddings (not OpenAI, despite what cairo-coder uses)
• Qdrant Docker container must be running before generating embeddings or using semantic search
• @google/genai SDK (not Google's older APIs)
• MCP SDK v1.20.1+ (uses stdio transport, not SSE)

MCP Tools (4 Total)

1. get-cairo-docs - Keyword-based markdown search (fast, no embeddings)
2. get-cairo-example - Returns full Cairo source code
3. list-cairo-resources - Lists all available docs/examples
4. semantic-search-cairo - Natural language search via Gemini embeddings + Qdrant (slower but more accurate)

Semantic Search Parameters (Simplified API)

Two parameters only:

• score_threshold (0.0-1.0, default: 0.5) - Controls relevance cutoff
• max_tokens (number, default: 50000) - Controls total output size

Automatic rounding (NEW):

• Each chunk = ~500 tokens (from size-based chunking)
• max_tokens automatically rounds up to nearest 500
• Examples:
  • 290 → 500 (minimum: 1 chunk)
  • 750 → 1000 (2 chunks)
  • 10000 → 10000 (20 chunks)

Why this works:

• No confusing max_results vs max_tokens dual system
• Prevents fetching 100 results when only 10 fit in token budget
• Automatic optimization: limit = Math.ceil(maxTokens / 500)

Key Gotchas

• Embedding dimension: MUST be 768 (not 3072) - normalized for cosine similarity accuracy
• Chunk size: MUST be 500 tokens (~2000 chars) - enforced in generate-embeddings.ts
• Chunking strategy: Size-based (not just header-based) - prevents massive sections
• File paths: Use relative paths from __dirname (e.g., ../docs/cairo_book_summary.md)
• Task type: RETRIEVAL_DOCUMENT for docs, RETRIEVAL_QUERY for queries (Gemini API requirement)
• Collection name: Hardcoded as cairo-docs in both scripts - must match exactly
• Score threshold: Higher = stricter (0.9 = nearly identical, 0.5 = moderate, 0.3 = loose)
• Token estimation: Character-based heuristic (1 token ≈ 4 chars) - conservative, no external tokenizer

Comparison to cairo-coder

This project intentionally differs from cairo-coder:

• No Docker (except external Qdrant)
• No PostgreSQL/pgvector (uses Qdrant instead)
• No HTTP API (MCP protocol only)
• No LLM for retrieval (just embeddings)
• Single API key (Gemini only, not OpenAI + Anthropic)
• Direct file access (no complex RAG pipeline)

Source Attribution

• Documentation extracted from KasarLabs/cairo-coder project (Python summarizer outputs)
• Architecture inspired by Upstash/context7 MCP server
• Built for Model Context Protocol (MCP) specification by Anthropic