mirror of
https://github.com/bendtherules/ask262.git
synced 2026-08-18 21:31:46 +00:00
docs(AGENTS): rewrite overview, commands, and project structure to focus on MCP server usage and updated tooling information.
This commit is contained in:
@@ -2,216 +2,77 @@
|
|||||||
|
|
||||||
## Project Overview
|
## 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:
|
**Stack:** Vector search (LanceDB + Ollama/Fireworks embeddings) → Knowledge graph → LLM reasoning. Runs as MCP server (stdio or HTTP) for Claude Desktop, OpenCode, etc.
|
||||||
- **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
|
|
||||||
```
|
|
||||||
|
|
||||||
## Commands
|
## Commands
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
bun run ingest # Ingest spec HTML into vector index
|
bun run ingest # Ingest spec HTML into vector DB
|
||||||
bun run build # Build knowledge graph (spec → code mappings)
|
bun run build # Build knowledge graph
|
||||||
bun run lint # Check code with Biome
|
bun run lint # Biome check
|
||||||
bun run lint:fix # Fix auto-fixable issues
|
bun run type-check # TypeScript strict check
|
||||||
bun run format:fix # Format code with Biome
|
bun test # Run all Bun tests
|
||||||
bun run type-check # TypeScript check (no emit)
|
bun run ask262-stdio # Stdio transport
|
||||||
bun test # Run all tests
|
bun run ask262-http # HTTP transport (port 8081)
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 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 |
|
**Setup:**
|
||||||
|------|-------------|
|
`src/setup/ingest.ts` - Creates vector DB from spec
|
||||||
| `ask262_search_spec_sections` | Vector search ECMAScript spec for relevant sections |
|
`src/setup/buildGraph.ts` - Maps spec sections to code
|
||||||
| `ask262_get_section_content` | Retrieve full content from a spec section |
|
|
||||||
| `ask262_evaluate_in_engine262` | Execute JS in engine262 and capture spec sections |
|
|
||||||
|
|
||||||
### 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`):**
|
**Formatting (Biome):** 2 spaces, 80 char width, LF endings. Excludes: `spec-built/`, `engine262/`, `graphology/`.
|
||||||
```json
|
|
||||||
{
|
|
||||||
"mcpServers": {
|
|
||||||
"ask262": {
|
|
||||||
"command": "bun",
|
|
||||||
"args": ["run", "/path/to/ask262/src/mcp-server-stdio.ts"],
|
|
||||||
"cwd": "/path/to/ask262"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**OpenCode (`.opencode/mcp.json` or `~/.config/opencode/opencode.json`):**
|
**TypeScript:** Strict mode enabled. Explicit return types. Avoid `any`. Target: ES2022.
|
||||||
|
|
||||||
*stdio (local process):*
|
**Naming:** Folders kebab-case (`agent-tools`). Files camelCase (`buildGraph.ts`). Functions camelCase (`createTool`). Constants UPPER_SNAKE_CASE. Types PascalCase.
|
||||||
```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"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
*http (stateless JSON server):*
|
**Error Handling:** Try/catch with meaningful messages. Validate env vars. Log warnings for missing config.
|
||||||
```json
|
|
||||||
{
|
|
||||||
"$schema": "https://opencode.ai/config.json",
|
|
||||||
"mcp": {
|
|
||||||
"ask262": {
|
|
||||||
"type": "remote",
|
|
||||||
"url": "http://localhost:8081/mcp",
|
|
||||||
"enabled": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Start the HTTP server first:
|
**Comments & Documentation:**
|
||||||
```bash
|
- JSDoc for public functions: purpose, params, return values, examples
|
||||||
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
|
|
||||||
- Use `/** */` for documentation blocks
|
- Use `/** */` for documentation blocks
|
||||||
- Use `//` for inline implementation notes
|
- Use `//` for inline implementation notes
|
||||||
- Document complex logic or non-obvious decisions
|
- Document complex logic or non-obvious decisions
|
||||||
|
|
||||||
### Error Handling
|
## Environment
|
||||||
- Use `try/catch` for async operations with meaningful error messages
|
|
||||||
- Validate environment variables
|
Copy `.env.example` to `.env`:
|
||||||
- Check file existence before reading
|
- `ASK262_EMBEDDING_PROVIDER` - `ollama` or `fireworks`
|
||||||
- Log warnings for missing configuration rather than failing silently
|
- `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
|
## Key Dependencies
|
||||||
|
|
||||||
- **LangChain**: Agent framework and LLM integration (`langchain`, `@langchain/*`)
|
- **LanceDB** - Vector storage
|
||||||
- **LanceDB**: Vector storage for embeddings (`@lancedb/lancedb`)
|
- **Ollama** / **Fireworks** - Embeddings
|
||||||
- **Ollama**: Local embeddings (`@langchain/ollama`)
|
- **LangChain** - LLM framework
|
||||||
- **Graphology**: Knowledge graph library (`graphology`)
|
- **Hono** - HTTP server
|
||||||
- **Cheerio**: HTML parsing (`cheerio`)
|
- **Biome** - Lint/format
|
||||||
- **Biome**: Linting and formatting (`@biomejs/biome`)
|
|
||||||
|
|
||||||
## Important Notes
|
## Important Notes
|
||||||
|
|
||||||
1. Always use TypeScript for implementation - no plain JavaScript
|
- TypeScript only - no plain JS
|
||||||
2. Run type-check before committing: `bun run type-check`
|
- Run `bun run type-check` before committing
|
||||||
3. Ingest and build commands can take significant time due to local embedding generation
|
- Ingest/build are slow (local embedding generation)
|
||||||
4. External directories (`spec-built/`, `engine262/`, `graphology/`) should not be modified by linting/formatting
|
- Don't lint/format external dirs (`engine262/`, `spec-built/`, `graphology/`)
|
||||||
|
|||||||
Reference in New Issue
Block a user