godot-docs-mcp: Instructions file for Codex

Agent Guidelines for godot-docs-mcp

This document provides coding guidelines and operational instructions for agents working on this codebase.

Project Overview

• Type: Cloudflare Workers MCP server (Model Context Protocol)
• Purpose: Provides AI agents with tools to search and retrieve Godot documentation
• Runtime: Cloudflare Workers (workerd) with Durable Objects
• Language: TypeScript (strict mode)
• Testing: Vitest with @cloudflare/vitest-pool-workers

Architecture

src/
├── index.ts          # Main entry point, MyMCP agent class, fetch handler
├── utils.ts          # Search and docs retrieval logic
└── indexes/         # Search index JSON files (stable/, latest/, 4.6/, 4.5/, 4.4/, 4.3/)
tests/
└── *.test.ts        # Vitest tests with Cloudflare Workers pool

MCP Server Configuration

The project uses Opencode MCP servers defined in opencode.json:

{
  "mcp": {
    "cloudflare-docs": {
      "enabled": true,
      "type": "remote",
      "url": "https://docs.mcp.cloudflare.com/mcp"
    },
    "cloudflare-worker-bindings": {
      "enabled": false,
      "type": "remote",
      "url": "https://bindings.mcp.cloudflare.com/mcp"
    }
  }
}

• cloudflare-docs: Enabled - provides tools to search Cloudflare documentation
• cloudflare-worker-bindings: Disabled by default - provides tools to query Worker bindings

Build, Lint, and Test Commands

# Install dependencies
npm install

# Development server (wrangler dev)
npm run dev
npm run dev:inspect    # With Node inspector for debugging

# Deploy to Cloudflare Workers
npm run deploy

# Type checking
npm run type-check     # tsc --noEmit

# Generate Cloudflare types
npm run cf-typegen    # wrangler types

# Formatting (Biome)
npm run format         # biome format --write
npm run lint:fix       # biome lint --fix

# Testing
npm test              # Run all tests (vitest)
npm test -- --run     # Run tests once (not watch mode)
npm test -- --run -t "test name"    # Run single test by name
npm test -- --run tests/search_docs.test.ts  # Run single test file