diff --git a/AGENTS.md b/AGENTS.md index 6bbf1c1..d34b874 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,216 +2,77 @@ ## Project Overview -**Ask262** is a RAG-based AI chat agent for exploring the ECMAScript specification and its implementation in [engine262](https://github.com/bendtherules/engine262) (a JavaScript engine written in JavaScript). +**Ask262** is a RAG-based MCP server for exploring the ECMAScript specification via [engine262](https://github.com/bendtherules/engine262). Users ask questions like *"How does array.map work?"* and get answers grounded in the actual spec and implementation. -The agent combines: -- **Vector search** (via LanceDB + Ollama embeddings) to find relevant spec sections -- **Knowledge graph** (via Graphology) mapping spec sections to implementation functions -- **LLM reasoning** (via OpenAI-compatible API) to answer questions about JavaScript internals - -Users ask questions like: *"How does the if statement work?"* or *"Which function implements sec-if-statement?"* - -## Prerequisites - -- **Node.js** 18+ with Bun runtime (packageManager: bun@1.2.8) -- **Ollama** installed locally with embedding model (e.g., `qwen3-embedding:0.6b`) - -## Project Structure - -``` -ask262/ -├── src/ -│ ├── agent.ts # Main ReAct agent - answers user queries -│ ├── constants.ts # Directory paths and model configs -│ ├── agent-tools/ # Tool implementations (spec retriever, graph explorer) -│ │ ├── index.ts # Tool exports -│ │ ├── searchSpecSections.ts # Vector search tool -│ │ ├── getSectionContent.ts # Section chunk retrieval tool -│ │ ├── graphExplorer.ts # Knowledge graph navigation tool -│ │ ├── evaluateInEngine262.ts # Execute JS and capture spec marks -│ │ └── reranker.ts # Document reranking utility -│ └── setup/ # Data ingestion and graph building -│ ├── ingest.ts # Ingests spec HTML into vector index -│ ├── buildGraph.ts # Builds knowledge graph -│ ├── stripSpecContainer.ts # Cleans spec HTML files -│ ├── htmlAddInternalMethodLink.ts # Adds internal method links -│ ├── text-splitters/ # Text chunking utilities -│ └── utils/ # Formatting utilities -│ ├── mcp-server-stdio.ts # MCP server (stdio transport) -│ └── test/ # Manual verification tests -│ └── manual/ -│ ├── verify-db.ts # Verify database contents -│ ├── test-search-spec-sections.ts # Test vector search tool -│ └── test-evaluate-in-engine262.ts # Test evaluate tool -├── spec-built/multipage/ # ECMAScript spec HTML files -├── engine262/src/ # JavaScript engine implementation -├── storage/ # Vector index persistence (LanceDB) -├── graphology/ # Knowledge graph JSON file -├── biome.json # Biome formatter config -├── tsconfig.json # TypeScript strict config -└── package.json # Bun-based dependencies -``` +**Stack:** Vector search (LanceDB + Ollama/Fireworks embeddings) → Knowledge graph → LLM reasoning. Runs as MCP server (stdio or HTTP) for Claude Desktop, OpenCode, etc. ## Commands ```bash -bun run ingest # Ingest spec HTML into vector index -bun run build # Build knowledge graph (spec → code mappings) -bun run lint # Check code with Biome -bun run lint:fix # Fix auto-fixable issues -bun run format:fix # Format code with Biome -bun run type-check # TypeScript check (no emit) -bun test # Run all tests -bun run test-evaluate # Test evaluate in engine262 tool -bun run test-search-spec-sections "query" # Test vector search tool with query -bun run agent "Query" # Run agent with question -bun run ask262-stdio # Start MCP server (stdio transport) -bun run test-mcp-server # Test MCP server with all tools +bun run ingest # Ingest spec HTML into vector DB +bun run build # Build knowledge graph +bun run lint # Biome check +bun run type-check # TypeScript strict check +bun test # Run all Bun tests +bun run ask262-stdio # Stdio transport +bun run ask262-http # HTTP transport (port 8081) ``` -## MCP Server +## Project Structure -Ask262 can run as an MCP (Model Context Protocol) server, making its tools available to any MCP-compatible client (Claude Desktop, OpenCode, etc.). +**Core:** +`src/agent-tools/` - MCP tool implementations +`src/mcp-server-stdio.ts` - Stdio server entry +`src/mcp-server-http.ts` - HTTP server entry -### Available MCP Tools +**Data:** +`storage/` - LanceDB vector index +`spec-built/multipage/` - ECMAScript spec HTML +`engine262/` - JS engine implementation (git submodule, ignored) +`graphology/` - Knowledge graph JSON -| Tool | Description | -|------|-------------| -| `ask262_search_spec_sections` | Vector search ECMAScript spec for relevant sections | -| `ask262_get_section_content` | Retrieve full content from a spec section | -| `ask262_evaluate_in_engine262` | Execute JS in engine262 and capture spec sections | +**Setup:** +`src/setup/ingest.ts` - Creates vector DB from spec +`src/setup/buildGraph.ts` - Maps spec sections to code -### Configuration +## Code Style -Add to your MCP client configuration: +**Imports:** ES modules only. Node built-ins use `node:` prefix. Never CommonJS. -**Claude Desktop (`claude_desktop_config.json`):** -```json -{ - "mcpServers": { - "ask262": { - "command": "bun", - "args": ["run", "/path/to/ask262/src/mcp-server-stdio.ts"], - "cwd": "/path/to/ask262" - } - } -} -``` +**Formatting (Biome):** 2 spaces, 80 char width, LF endings. Excludes: `spec-built/`, `engine262/`, `graphology/`. -**OpenCode (`.opencode/mcp.json` or `~/.config/opencode/opencode.json`):** +**TypeScript:** Strict mode enabled. Explicit return types. Avoid `any`. Target: ES2022. -*stdio (local process):* -```json -{ - "$schema": "https://opencode.ai/config.json", - "mcp": { - "ask262": { - "type": "local", - "command": ["bun", "run", "src/mcp-server-stdio.ts"], - "enabled": true, - "environment": { - "OLLAMA_HOST": "http://localhost:11434" - } - } - } -} -``` +**Naming:** Folders kebab-case (`agent-tools`). Files camelCase (`buildGraph.ts`). Functions camelCase (`createTool`). Constants UPPER_SNAKE_CASE. Types PascalCase. -*http (stateless JSON server):* -```json -{ - "$schema": "https://opencode.ai/config.json", - "mcp": { - "ask262": { - "type": "remote", - "url": "http://localhost:8081/mcp", - "enabled": true - } - } -} -``` +**Error Handling:** Try/catch with meaningful messages. Validate env vars. Log warnings for missing config. -Start the HTTP server first: -```bash -bun run ask262-http # Development -ask262-http # After npm install -g -``` - -### Testing - -Test the MCP server before configuring your client: - -```bash -# Run automated tests for all MCP tools -bun run test-mcp-server -``` - -This tests: -- Tool listing -- Vector search (`ask262_search_spec_sections`) -- Section content retrieval (`ask262_get_section_content`) -- Code evaluation with console capture (`ask262_evaluate_in_engine262`) - -### Prerequisites - -Before running the MCP server: -1. Ensure `storage/` directory exists with ingested spec vectors (`bun run ingest`) -2. Ensure Ollama is running with `qwen3-embedding:0.6b` model - -## Code Style Guidelines - -### Imports & Modules -- Use ES modules (`import/export`), never CommonJS -- Node.js built-ins: `import fs from "node:fs"` (with `node:` prefix) -- Third-party: `import * as cheerio from "cheerio"` -- Package type: `"type": "module"` in package.json - -### Formatting (Biome) -- **Indent**: 2 spaces (not tabs) -- **Line width**: 80 characters -- **Line ending**: LF -- **Excluded directories**: `spec-built/`, `engine262/`, `graphology/` (external/vendor) - -### TypeScript -- **Target**: ES2022 -- **Strict mode**: Enabled with `strict: true` -- **Module resolution**: Node -- Explicit types for function parameters and return values -- Use `as const` for literal arrays -- Avoid `any` - use proper types or `unknown` -- JSON imports: `resolveJsonModule: true` - -### Naming Conventions -- **Folders**: kebab-case (e.g., `agent-tools`, `text-splitters`) -- **Files**: camelCase (e.g., `buildGraph.ts`, `specRetriever.ts`) -- **Functions**: camelCase (e.g., `createGraphExplorerTool`) -- **Constants**: UPPER_SNAKE_CASE or camelCase for exported constants -- **Types/Interfaces**: PascalCase with descriptive names - -### Comments & Documentation -- JSDoc for public functions explaining purpose, params, return values +**Comments & Documentation:** +- JSDoc for public functions: purpose, params, return values, examples - Use `/** */` for documentation blocks - Use `//` for inline implementation notes - Document complex logic or non-obvious decisions -### Error Handling -- Use `try/catch` for async operations with meaningful error messages -- Validate environment variables -- Check file existence before reading -- Log warnings for missing configuration rather than failing silently +## Environment + +Copy `.env.example` to `.env`: +- `ASK262_EMBEDDING_PROVIDER` - `ollama` or `fireworks` +- `FIREWORKS_API_KEY` - Required for Fireworks +- `OLLAMA_HOST` - Ollama URL (default: http://localhost:11434) +- `ASK262_PORT` - HTTP server port (default: 8081) +- `MCP_PUBLIC_URL` - Public URL for inspector ## Key Dependencies -- **LangChain**: Agent framework and LLM integration (`langchain`, `@langchain/*`) -- **LanceDB**: Vector storage for embeddings (`@lancedb/lancedb`) -- **Ollama**: Local embeddings (`@langchain/ollama`) -- **Graphology**: Knowledge graph library (`graphology`) -- **Cheerio**: HTML parsing (`cheerio`) -- **Biome**: Linting and formatting (`@biomejs/biome`) +- **LanceDB** - Vector storage +- **Ollama** / **Fireworks** - Embeddings +- **LangChain** - LLM framework +- **Hono** - HTTP server +- **Biome** - Lint/format ## Important Notes -1. Always use TypeScript for implementation - no plain JavaScript -2. Run type-check before committing: `bun run type-check` -3. Ingest and build commands can take significant time due to local embedding generation -4. External directories (`spec-built/`, `engine262/`, `graphology/`) should not be modified by linting/formatting +- TypeScript only - no plain JS +- Run `bun run type-check` before committing +- Ingest/build are slow (local embedding generation) +- Don't lint/format external dirs (`engine262/`, `spec-built/`, `graphology/`)