feat(mcp-server): Add MCP server with tool registrations

Add MCP server implementation with support for:
- ask262_search_spec_sections tool
- ask262_get_section_content tool
- ask262_evaluate_in_engine262 tool
Includes proper error handling, input/output schemas, and structured
content responses.

src/agent-tools/evaluateInEngine262.ts

@@ -1,19 +1,45 @@
 /**
  * Evaluate JavaScript code in engine262 and capture spec section marks.
  * Executes code in the engine262 JavaScript engine and returns the captured
- * ECMAScript spec section marks as JSON.
+ * ECMAScript spec section marks.
  */
 
-import { DynamicStructuredTool } from "@langchain/core/tools";
 import { z } from "zod";
 
+// #region Zod schemas (not exported)
+
+const consoleEntrySchema = z.object({
+  method: z.string().describe("Console method name (log, warn, debug, error)"),
+  values: z.array(z.unknown()).describe("Values logged to console"),
+});
+
+const evaluateSuccessOutputSchema = z.object({
+  importantSections: z
+    .array(z.string())
+    .describe("Important spec sections hit during execution"),
+  otherSections: z
+    .array(z.string())
+    .describe("Other spec sections hit during execution"),
+  consoleOutput: z
+    .array(consoleEntrySchema)
+    .describe("Console output captured during execution"),
+});
+
+const evaluateErrorOutputSchema = z.object({
+  error: z.string().describe("Error message when execution fails"),
+});
+
+// #endregion
+
+// #region Exported Zod schemas
+
 /**
  * Tool metadata for reuse in OpenCode tools.
  */
 export const toolMetadata = {
   description:
     "Executes pure ECMAScript JavaScript code in the engine262 JavaScript engine and captures which ECMAScript specification sections are hit during execution. " +
-    "Returns JSON with importantSections, otherSections, and consoleOutput arrays. Useful for understanding how specific JavaScript operations map to the ECMAScript spec. " +
+    "Returns an object with importantSections, otherSections, and consoleOutput arrays. Useful for understanding how specific JavaScript operations map to the ECMAScript spec. " +
     "Code must be pure ECMAScript with no DOM, browser, or Node.js APIs (no fs, document, window, etc.). " +
     "console object with log/warn/debug/error methods and ask262Debug are available globally (no import needed). " +
     "Use ask262Debug.startImportant() and ask262Debug.stopImportant() to mark important sections. " +
@@ -23,10 +49,42 @@ export const toolMetadata = {
   },
 };
 
-const evaluateSchema = z.object({
+/**
+ * Input schema for the evaluate tool.
+ */
+export const inputSchema = z.object({
   code: z.string().describe(toolMetadata.args.code),
 });
 
+/**
+ * Output schema for the evaluate tool (union of success and error outputs).
+ */
+export const outputSchema = z.union([
+  evaluateSuccessOutputSchema,
+  evaluateErrorOutputSchema,
+]);
+
+// #endregion
+
+// #region TypeScript types (inferred from Zod schemas)
+
+export type ConsoleEntry = z.infer<typeof consoleEntrySchema>;
+
+export type EvaluateSuccessOutput = z.infer<typeof evaluateSuccessOutputSchema>;
+
+export type EvaluateErrorOutput = z.infer<typeof evaluateErrorOutputSchema>;
+
+export type EvaluateToolOutput = z.infer<typeof outputSchema>;
+
+export type EvaluateToolInput = z.infer<typeof inputSchema>;
+
+// #endregion
+
+/**
+ * Tool name constant.
+ */
+export const toolName = "ask262_evaluate_in_engine262";
+
 // Type definitions for engine262 module
 interface MarkData {
   readonly sectionIds: string[];
@@ -35,12 +93,6 @@ interface MarkData {
   readonly important: boolean;
 }
 
-// Console log entry type
-interface ConsoleEntry {
-  method: string;
-  values: unknown[];
-}
-
 // biome-ignore lint/suspicious/noExplicitAny: engine262 is an external module without TypeScript types
 let engine262Module: any = null;
 
@@ -56,166 +108,148 @@ async function loadEngine262() {
 }
 
 /**
- * Creates the evaluateInEngine262 tool.
+ * Creates the evaluateInEngine262 tool function.
  * Executes JavaScript code in engine262 and captures spec section marks.
- * @returns The evaluate_in_engine262 tool instance
+ * @returns Function that executes code and returns structured output
  */
 export function createEvaluateInEngine262Tool() {
-  return new DynamicStructuredTool({
-    name: "ask262_evaluate_in_engine262",
-    description: toolMetadata.description,
-    schema: evaluateSchema,
-    func: async ({ code }) => {
-      try {
-        const engine = await loadEngine262();
-        const ask262Debug = engine.ask262Debug as {
-          marks: MarkData[];
-          startTrace: () => void;
-          stopTrace: () => void;
-          startImportant: () => void;
-          stopImportant: () => void;
-        };
-        const Agent = engine.Agent;
-        const ManagedRealm = engine.ManagedRealm;
-        const setSurroundingAgent = engine.setSurroundingAgent;
-        const OrdinaryObjectCreate = engine.OrdinaryObjectCreate;
-        const CreateBuiltinFunction = engine.CreateBuiltinFunction;
-        const CreateDataProperty = engine.CreateDataProperty;
-        const Value = engine.Value;
-        const skipDebugger = engine.skipDebugger;
+  return async ({ code }: EvaluateToolInput): Promise<EvaluateToolOutput> => {
+    const engine = await loadEngine262();
+    const ask262Debug = engine.ask262Debug as {
+      marks: MarkData[];
+      startTrace: () => void;
+      stopTrace: () => void;
+      startImportant: () => void;
+      stopImportant: () => void;
+    };
+    const Agent = engine.Agent;
+    const ManagedRealm = engine.ManagedRealm;
+    const setSurroundingAgent = engine.setSurroundingAgent;
+    const OrdinaryObjectCreate = engine.OrdinaryObjectCreate;
+    const CreateBuiltinFunction = engine.CreateBuiltinFunction;
+    const CreateDataProperty = engine.CreateDataProperty;
+    const Value = engine.Value;
+    const skipDebugger = engine.skipDebugger;
 
-        // Reset marks from previous runs
-        ask262Debug.marks = [];
+    // TODO: Add reset method, allow making instances and use that.
+    // Reset marks from previous runs
+    ask262Debug.marks = [];
 
-        // Array to capture console output
-        const consoleOutput: ConsoleEntry[] = [];
+    // Array to capture console output
+    const consoleOutput: ConsoleEntry[] = [];
 
-        // Set up agent and realm
-        const agent = new Agent();
-        setSurroundingAgent(agent);
-        const realm = new ManagedRealm();
+    // Set up agent and realm
+    const agent = new Agent();
+    setSurroundingAgent(agent);
+    const realm = new ManagedRealm();
 
-        // Expose ask262Debug and console to the evaluated code
-        realm.scope(() => {
-          const debugObj = OrdinaryObjectCreate(
-            agent.intrinsic("%Object.prototype%"),
-          );
-          skipDebugger(
-            CreateDataProperty(
-              realm.GlobalObject,
-              Value("ask262Debug"),
-              debugObj,
-            ),
-          );
+    // Expose ask262Debug and console to the evaluated code
+    realm.scope(() => {
+      const debugObj = OrdinaryObjectCreate(
+        agent.intrinsic("%Object.prototype%"),
+      );
+      skipDebugger(
+        CreateDataProperty(realm.GlobalObject, Value("ask262Debug"), debugObj),
+      );
 
-          const startImportant = CreateBuiltinFunction(
-            () => {
-              ask262Debug.startImportant();
-              return Value.undefined;
-            },
-            0,
-            Value("startImportant"),
-            [],
-          );
-          skipDebugger(
-            CreateDataProperty(
-              debugObj,
-              Value("startImportant"),
-              startImportant,
-            ),
-          );
+      const startImportant = CreateBuiltinFunction(
+        () => {
+          ask262Debug.startImportant();
+          // biome-ignore lint/suspicious/noExplicitAny: engine262 uses custom value types
+          return (Value as any)("undefined");
+        },
+        0,
+        Value("startImportant"),
+        [],
+      );
+      skipDebugger(
+        CreateDataProperty(debugObj, Value("startImportant"), startImportant),
+      );
 
-          const stopImportant = CreateBuiltinFunction(
-            () => {
-              ask262Debug.stopImportant();
-              return Value.undefined;
-            },
-            0,
-            Value("stopImportant"),
-            [],
-          );
-          skipDebugger(
-            CreateDataProperty(debugObj, Value("stopImportant"), stopImportant),
-          );
+      const stopImportant = CreateBuiltinFunction(
+        () => {
+          ask262Debug.stopImportant();
+          // biome-ignore lint/suspicious/noExplicitAny: engine262 uses custom value types
+          return (Value as any)("undefined");
+        },
+        0,
+        Value("stopImportant"),
+        [],
+      );
+      skipDebugger(
+        CreateDataProperty(debugObj, Value("stopImportant"), stopImportant),
+      );
 
-          // Create console object with methods (excluding 'clear')
-          const consoleObj = OrdinaryObjectCreate(
-            agent.intrinsic("%Object.prototype%"),
-          );
-          skipDebugger(
-            CreateDataProperty(
-              realm.GlobalObject,
-              Value("console"),
-              consoleObj,
-            ),
-          );
+      // Create console object with methods (excluding 'clear')
+      const consoleObj = OrdinaryObjectCreate(
+        agent.intrinsic("%Object.prototype%"),
+      );
+      skipDebugger(
+        CreateDataProperty(realm.GlobalObject, Value("console"), consoleObj),
+      );
 
-          // Add console methods: log, warn, debug, error
-          const consoleMethods = ["log", "warn", "debug", "error"];
-          for (const method of consoleMethods) {
-            const fn = CreateBuiltinFunction(
-              (args: unknown[]) => {
-                // Convert engine262 values to JavaScript values for the output
-                const jsValues = args.map((arg) => {
-                  // Handle engine262 Value types - convert to primitive JS values
-                  if (arg && typeof arg === "object") {
-                    // Try to get string value if it's a JSStringValue
-                    const strVal = (arg as { stringValue?: () => string })
-                      .stringValue;
-                    if (typeof strVal === "function") {
-                      return strVal.call(arg);
-                    }
-                    // Try other common properties
-                    const value = (arg as { value?: unknown }).value;
-                    if (value !== undefined) {
-                      return value;
-                    }
-                  }
-                  return arg;
-                });
-                consoleOutput.push({ method, values: jsValues });
-                return Value.undefined;
-              },
-              1,
-              Value(method),
-              [],
-            );
-            skipDebugger(CreateDataProperty(consoleObj, Value(method), fn));
-          }
-        });
-
-        // Start tracing
-        ask262Debug.startTrace();
-
-        // Execute the code
-        realm.evaluateScript(code);
-
-        // Stop tracing
-        ask262Debug.stopTrace();
-
-        // Get captured marks
-        const marks = ask262Debug.marks;
-
-        // Filter and group marks by important flag
-        const importantMarks = marks.filter((m) => m.important);
-        const otherMarks = marks.filter((m) => !m.important);
-
-        // Extract sectionIds, remove fileRelativePath and lineNumber
-        const result = {
-          importantSections: importantMarks.map((m) => m.sectionIds),
-          otherSections: otherMarks.map((m) => m.sectionIds),
-          consoleOutput: consoleOutput,
-        };
-
-        // Return compressed JSON
-        return JSON.stringify(result);
-      } catch (error) {
-        console.error(`[Tool: ask262_evaluate_in_engine262] Error: ${error}`);
-        const errorResult = {
-          error: error instanceof Error ? error.message : String(error),
-        };
-        return JSON.stringify(errorResult);
+      // Add console methods: log, warn, debug, error
+      const consoleMethods = ["log", "warn", "debug", "error"];
+      for (const method of consoleMethods) {
+        const fn = CreateBuiltinFunction(
+          (args: unknown[]) => {
+            // Convert engine262 values to JavaScript values for the output
+            const jsValues = args.map((arg) => {
+              // Handle engine262 Value types - convert to primitive JS values
+              if (arg && typeof arg === "object") {
+                // Try to get string value if it's a JSStringValue
+                const strVal = (arg as { stringValue?: () => string })
+                  .stringValue;
+                if (typeof strVal === "function") {
+                  return strVal.call(arg);
+                }
+                // Try other common properties
+                const value = (arg as { value?: unknown }).value;
+                if (value !== undefined) {
+                  return value;
+                }
+              }
+              return arg;
+            });
+            consoleOutput.push({ method, values: jsValues });
+            // biome-ignore lint/suspicious/noExplicitAny: engine262 uses custom value types
+            return (Value as any)("undefined");
+          },
+          1,
+          Value(method),
+          [],
+        );
+        skipDebugger(CreateDataProperty(consoleObj, Value(method), fn));
       }
-    },
-  });
+    });
+
+    // Start tracing
+    ask262Debug.startTrace();
+
+    try {
+      // Execute the code - only this part can fail
+      realm.evaluateScript(code);
+    } catch (error) {
+      return {
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+
+    // Stop tracing
+    ask262Debug.stopTrace();
+
+    // Get captured marks
+    const marks = ask262Debug.marks;
+
+    // Filter and group marks by important flag
+    const importantMarks = marks.filter((m) => m.important);
+    const otherMarks = marks.filter((m) => !m.important);
+
+    // Flatten sectionIds from all marks
+    return {
+      importantSections: importantMarks.flatMap((m) => m.sectionIds),
+      otherSections: otherMarks.flatMap((m) => m.sectionIds),
+      consoleOutput: consoleOutput,
+    };
+  };
 }

src/agent-tools/getSectionContent.ts

@@ -4,12 +4,25 @@
  */
 
 import type { Table } from "@lancedb/lancedb";
-import { DynamicStructuredTool } from "@langchain/core/tools";
 import { z } from "zod";
 
-/**
- * Tool metadata for reuse in OpenCode tools.
- */
+// #region Zod schemas (not exported)
+
+const sectionContentSchema = z.object({
+  text: z.string(),
+  sectionTitle: z.string().optional(),
+  partIndex: z.number().optional(),
+});
+
+const getSectionContentOutputSchema = z.object({
+  content: z.string(),
+  sectionCount: z.number(),
+});
+
+// #endregion
+
+// #region Exported Zod schemas
+
 export const toolMetadata = {
   description:
     "Retrieves all text chunks from a specific specification section by sectionid. " +
@@ -24,68 +37,88 @@ export const toolMetadata = {
   },
 };
 
-const getSectionContentSchema = z.object({
+export const inputSchema = z.object({
   sectionId: z.string().describe(toolMetadata.args.sectionId),
   recursive: z.boolean().default(true).describe(toolMetadata.args.recursive),
 });
 
+export const outputSchema = getSectionContentOutputSchema;
+
+export const toolName = "ask262_get_section_content";
+
+// #endregion
+
+// #region TypeScript types (inferred from Zod schemas)
+
+export type SectionContent = z.infer<typeof sectionContentSchema>;
+
+export type GetSectionContentOutput = z.infer<
+  typeof getSectionContentOutputSchema
+>;
+
+export type GetSectionContentInput = z.infer<typeof inputSchema>;
+
+// #endregion
+
 /**
- * Creates the get section content tool.
+ * Creates the get section content tool function.
  * Retrieves all text chunks from a specific specification section by sectionid.
  * Supports recursive fetching - if a section has children, it will fetch all descendants.
  * @param table - LanceDB table containing spec vectors
+ * @returns Function that retrieves content and returns structured output
  */
 export function createGetSectionContentTool(table: Table) {
-  return new DynamicStructuredTool({
-    name: "ask262_get_section_content",
-    description: toolMetadata.description,
-    schema: getSectionContentSchema,
-    func: async ({ sectionId, recursive }) => {
-      const allDocs: string[] = [];
-      const queue: string[] = [sectionId];
-      const visited = new Set<string>();
+  return async ({
+    sectionId,
+    recursive,
+  }: GetSectionContentInput): Promise<GetSectionContentOutput> => {
+    const allDocs: string[] = [];
+    const queue: string[] = [sectionId];
+    const visited = new Set<string>();
 
-      while (queue.length > 0) {
-        const currentId = queue.shift()!;
-        if (visited.has(currentId)) continue;
-        visited.add(currentId);
+    while (queue.length > 0) {
+      const currentId = queue.shift();
+      if (!currentId || visited.has(currentId)) continue;
+      visited.add(currentId);
 
-        const results = await table
-          .query()
-          .where(`sectionid = '${currentId}'`)
-          .limit(100)
-          .toArray();
+      const results = await table
+        .query()
+        .where(`sectionid = '${currentId}'`)
+        .limit(100)
+        .toArray();
 
-        // Sort by partindex to maintain order (nulls last for single-part sections)
-        const sortedResults = results.sort((a: unknown, b: unknown) => {
-          const aIndex = (a as { partindex?: number }).partindex ?? Infinity;
-          const bIndex = (b as { partindex?: number }).partindex ?? Infinity;
-          return aIndex - bIndex;
-        });
+      // Sort by partindex to maintain order (nulls last for single-part sections)
+      const sortedResults = results.sort((a: unknown, b: unknown) => {
+        const aIndex = (a as { partindex?: number }).partindex ?? Infinity;
+        const bIndex = (b as { partindex?: number }).partindex ?? Infinity;
+        return aIndex - bIndex;
+      });
 
-        for (const result of sortedResults) {
-          const typedResult = result as {
-            text?: string;
-            childrensectionids?: string[];
-            sectiontitle?: string;
-          };
+      for (const result of sortedResults) {
+        const typedResult = result as {
+          text?: string;
+          childrensectionids?: string[];
+          sectiontitle?: string;
+        };
 
-          if (typedResult.text) {
-            allDocs.push(typedResult.text);
-          }
+        if (typedResult.text) {
+          allDocs.push(typedResult.text);
+        }
 
-          // Add children to queue for recursive fetching only if recursive is true
-          if (
-            recursive &&
-            typedResult.childrensectionids &&
-            Array.isArray(typedResult.childrensectionids)
-          ) {
-            queue.push(...typedResult.childrensectionids);
-          }
+        // Add children to queue for recursive fetching only if recursive is true
+        if (
+          recursive &&
+          typedResult.childrensectionids &&
+          Array.isArray(typedResult.childrensectionids)
+        ) {
+          queue.push(...typedResult.childrensectionids);
         }
       }
+    }
 
-      return allDocs.join("\n\n---\n\n");
-    },
-  });
+    return {
+      content: allDocs.join("\n\n---\n\n"),
+      sectionCount: visited.size,
+    };
+  };
 }

src/agent-tools/index.ts

@@ -4,16 +4,35 @@
  */
 
 export {
+  type ConsoleEntry,
   createEvaluateInEngine262Tool,
+  type EvaluateErrorOutput,
+  type EvaluateSuccessOutput,
+  type EvaluateToolInput,
+  type EvaluateToolOutput,
+  inputSchema as evaluateInputSchema,
+  outputSchema as evaluateOutputSchema,
   toolMetadata as evaluateToolMetadata,
-} from "./evaluateInEngine262";
+  toolName as evaluateToolName,
+} from "./evaluateInEngine262.js";
 export {
   createGetSectionContentTool,
+  type GetSectionContentInput,
+  type GetSectionContentOutput,
+  inputSchema as getSectionInputSchema,
+  outputSchema as getSectionOutputSchema,
+  type SectionContent,
   toolMetadata as sectionContentToolMetadata,
-} from "./getSectionContent";
-export { createGraphExplorerTool } from "./graphExplorer";
-export { type RerankResult, rerankDocuments } from "./reranker";
+  toolName as sectionContentToolName,
+} from "./getSectionContent.js";
+export { createGraphExplorerTool } from "./graphExplorer.js";
 export {
   createSearchSpecSectionsTool,
+  inputSchema as searchSpecInputSchema,
+  outputSchema as searchSpecOutputSchema,
+  type SearchSpecInput,
+  type SearchSpecOutput,
+  type SearchSpecResult,
   toolMetadata as searchSpecToolMetadata,
-} from "./searchSpecSections";
+  toolName as searchSpecToolName,
+} from "./searchSpecSections.js";

src/agent-tools/searchSpecSections.ts

@@ -4,17 +4,32 @@
  */
 
 import type { Table } from "@lancedb/lancedb";
-import { DynamicStructuredTool } from "@langchain/core/tools";
 import type { OllamaEmbeddings } from "@langchain/ollama";
 import { z } from "zod";
 
-/**
- * Tool metadata for reuse in OpenCode tools.
- */
+// #region Zod schemas (not exported)
+
+const searchSpecResultSchema = z.object({
+  sectionId: z.string(),
+  sectionTitle: z.string(),
+  score: z.number(),
+  partIndex: z.number().nullable(),
+  totalParts: z.number().nullable(),
+  content: z.string(),
+});
+
+const searchSpecOutputSchema = z.object({
+  results: z.array(searchSpecResultSchema),
+});
+
+// #endregion
+
+// #region Exported Zod schemas
+
 export const toolMetadata = {
   description:
     "Vector search the ECMAScript specification for sections relevant to a query. " +
-    "Returns JSON array with sectionId, sectionTitle, score, partIndex, totalParts, and content. " +
+    "Returns an array of sections with sectionId, sectionTitle, score, partIndex, totalParts, and content. " +
     "partIndex and totalParts indicate which chunk of a multi-part section this is " +
     "(0-indexed, partIndex+1/totalParts), null if single-part.",
   args: {
@@ -23,42 +38,56 @@ export const toolMetadata = {
   },
 };
 
-const searchSpecSchema = z.object({
+export const inputSchema = z.object({
   query: z.string().describe(toolMetadata.args.query),
 });
 
+export const outputSchema = searchSpecOutputSchema;
+
+export const toolName = "ask262_search_spec_sections";
+
+// #endregion
+
+// #region TypeScript types (inferred from Zod schemas)
+
+export type SearchSpecResult = z.infer<typeof searchSpecResultSchema>;
+
+export type SearchSpecOutput = z.infer<typeof searchSpecOutputSchema>;
+
+export type SearchSpecInput = z.infer<typeof inputSchema>;
+
+// #endregion
+
 /**
- * Creates the search spec sections tool.
+ * Creates the search spec sections tool function.
  * Performs semantic vector search to find relevant spec sections.
  * @param table - LanceDB table containing spec vectors
  * @param embeddings - Ollama embeddings instance
+ * @returns Function that performs the search and returns structured output
  */
 export function createSearchSpecSectionsTool(
   table: Table,
   embeddings: OllamaEmbeddings,
 ) {
-  return new DynamicStructuredTool({
-    name: "ask262_search_spec_sections",
-    description: toolMetadata.description,
-    schema: searchSpecSchema,
-    func: async ({ query }) => {
-      // Generate embedding for the query
-      const queryVector = await embeddings.embedQuery(query);
+  return async ({ query }: SearchSpecInput): Promise<SearchSpecOutput> => {
+    // Generate embedding for the query
+    const queryVector = await embeddings.embedQuery(query);
 
-      // Search using LanceDB directly, limit to top 5 results
-      const results = await table.search(queryVector).limit(5).toArray();
+    // Search using LanceDB directly, limit to top 5 results
+    const results = await table.search(queryVector).limit(5).toArray();
 
-      // Return documents with metadata as JSON
-      const output = results.map((r: Record<string, unknown>) => ({
+    // Return documents with metadata as structured objects
+    const output: SearchSpecResult[] = results.map(
+      (r: Record<string, unknown>) => ({
         sectionId: String(r.sectionid || "unknown"),
         sectionTitle: String(r.sectiontitle || "unknown"),
         score: Number(r._distance || 0),
-        partIndex: r.partindex ?? null,
-        totalParts: r.totalparts ?? null,
+        partIndex: (r.partindex as number | undefined) ?? null,
+        totalParts: (r.totalparts as number | undefined) ?? null,
         content: String(r.text || ""),
-      }));
+      }),
+    );
 
-      return JSON.stringify(output);
-    },
-  });
+    return { results: output };
+  };
 }