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
|
||||
|
||||
**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/`)
|
||||
|
||||
Reference in New Issue
Block a user