Prepare npm release

Readme.md

@@ -1,51 +1,124 @@
-# RAG Pipeline for Language Specification Exploration
+# Ask262
 
-This project implements a RAG-based AI chat agent to explore the ECMAScript specification and its implementation in `engine262`.
+MCP server for exploring the ECMAScript specification and its implementation in [engine262](https://github.com/bendtherules/engine262).
+
+## Features
+
+- **Vector search** ECMAScript specification sections using semantic queries
+- **Execute JavaScript** in engine262 and capture which spec sections are hit
+- **Knowledge graph** mapping spec sections to implementation functions
+- **1-second timeout** on code execution for safety
 
 ## Prerequisites
 
-- **Node.js**: Version 18+
+- **Bun**: Version 1.0.0 or higher ([install](https://bun.sh/docs/installation))
-- **Ollama**: Installed locally with an embedding model (e.g., `nomic-embed-text`)
+- **Ollama**: Installed locally with an embedding model (e.g., `qwen3-embedding:0.6b`)
-- **OpenAI-compatible Endpoint**: A hosted or local LLM service
+
+## Installation
+
+```bash
+# Install globally with bun
+bun install -g ask262
+
+# Or run directly without installing
+bunx ask262
+
+# Or clone and install
+git clone <repository-url>
+cd ask262
+bun install
+```
 
 ## Setup
 
-1. **Install dependencies**:
+1. **Prepare environment**:
    ```bash
-   bun install
+   export OPENAI_API_BASE="your_endpoint_base_url"  # Optional
+   export OPENAI_API_KEY="your_api_key"             # Optional
    ```
 
-2. **Prepare environment**:
+2. **Ensure spec is present** (only external requirement):
-   ```bash
+   - `./spec-built/multipage/` - ECMAScript spec HTML files
-   export OPENAI_API_BASE="your_endpoint_base_url"
+   
-   export OPENAI_API_KEY="your_api_key"
+   *Note: `storage/` (pre-built vectors), `engine262/lib/`, and `graphology/` are included in the package.*
-   ```
 
-3. **Clone specification**:
+3. **Build knowledge graph** (first time only, if using custom spec):
-   (Ensure `./spec-built/multipage` contains the HTML files)
-
-4. **Ingest data**:
-   ```bash
-   bun run ingest
-   ```
-    *Note: This will take significant time as it generates local embeddings via Ollama for both the spec and the implementation.*
-
-5. **Build graph**:
    ```bash
    bun run build
    ```
 
-6. **Run tests**:
+## MCP Configuration
-   ```bash
-   bun test
-   ```
 
-## Usage
+Add to your MCP client configuration:
 
-Ask the agent questions about how code relates to the specification:
+**Claude Desktop** (`claude_desktop_config.json`):
-
+```json
-```bash
+{
-bun run agent "Explain how the 'if' statement works and show its implementation."
+  "mcpServers": {
+    "ask262": {
+      "command": "bun",
+      "args": ["run", "/path/to/ask262/src/mcp-server.ts"]
+    }
+  }
+}
 ```
 
-The agent will use tools to search the specification, explore the implementation code, and navigate the relationships between them using the graph.
+**OpenCode** (`.opencode/mcp.json`):
+```json
+{
+  "servers": {
+    "ask262": {
+      "command": "bun",
+      "args": ["run", "src/mcp-server.ts"]
+    }
+  }
+}
+```
+
+**Via global install** (after `bun install -g ask262`):
+```json
+{
+  "mcpServers": {
+    "ask262": {
+      "command": "ask262"
+    }
+  }
+}
+```
+
+**Via bunx** (no installation required):
+```json
+{
+  "mcpServers": {
+    "ask262": {
+      "command": "bunx",
+      "args": ["ask262"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+| 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 section marks |
+
+## Testing
+
+```bash
+# Run MCP server tests
+bun run test-mcp-server
+
+# Test evaluate tool with timeout
+bun run test-evaluate-timeout
+
+# Test search functionality
+bun run test-search-spec-sections
+```
+
+## License
+
+ISC

package.json

@@ -1,8 +1,16 @@
 {
   "name": "ask262",
-  "packageManager": "bun@1.2.8",
   "version": "1.0.0",
-  "main": "index.js",
+  "description": "MCP server for exploring ECMAScript specification and engine262 JavaScript engine implementation",
+  "packageManager": "bun@1.2.8",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "type": "module",
+  "main": "src/mcp-server.ts",
+  "bin": {
+    "ask262": "bun run src/mcp-server.ts"
+  },
   "scripts": {
     "type-check": "tsc --noEmit",
     "lint": "biome check .",
@@ -14,17 +22,30 @@
     "test-evaluate": "bun run src/test/manual/test-evaluate-in-engine262.ts",
     "test-evaluate-timeout": "bun run src/test/manual/test-evaluate-timeout.ts",
     "test-search-spec-sections": "bun run src/test/manual/test-search-spec-sections.ts",
-    "agent": "bun run src/agent.ts",
-    "build": "bun run src/setup/buildGraph.ts",
-    "mcp-server": "bun run src/mcp-server.ts",
     "test-mcp-server": "bun run src/test/manual/test-mcp-server.ts",
     "test": "bun test"
   },
-  "keywords": [],
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "ecmascript",
+    "javascript",
+    "engine262",
+    "specification",
+    "js-engine"
+  ],
   "author": "",
   "license": "ISC",
-  "description": "",
+  "files": [
-  "type": "module",
+    "src/",
+    "storage/",
+    "engine262/lib/",
+    "graphology/",
+    "config.json",
+    "AGENTS.md",
+    "README.md"
+  ],
   "dependencies": {
     "@lancedb/lancedb": "^0.5.0",
     "@langchain/community": "0.2.0",