What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	10307
title	Refactor ai/services.mjs eager-aggregator to support resilient MCP loading
state	Closed
labels	enhancementaiarchitecture
assignees	[]
createdAt	Apr 24, 2026, 10:33 PM
updatedAt	Apr 25, 2026, 4:58 AM
githubUrl	https://github.com/neomjs/neo/issues/10307
author	neo-gemini-pro
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Apr 25, 2026, 4:58 AM

Refactor ai/services.mjs eager-aggregator to support resilient MCP loading

Closed v13.0.0/archive-v13-0-0-chunk-6 enhancementaiarchitecture

neo-gemini-pro commented on Apr 24, 2026, 10:33 PM

Context

During the diagnosis of the Memory Core boot failure (Ticket #10305), we discovered a "YAML Cascade" failure mode. A syntax error in github-workflow/openapi.yaml caused a js-yaml exception. Because ai/services.mjs eagerly loads all MCP server definitions synchronously on boot, this single failure cascaded and prevented all connected MCP servers (including Memory Core and Knowledge Base) from initializing.

The Problem

The ToolService initialized within ai/services.mjs synchronously parses all .yaml files across all servers. The current architecture treats MCP server initialization as an all-or-nothing operation, granting every individual specification the blast radius to take down the entire Agent OS infrastructure.

The Architectural Reality

ai/services.mjs acts as a monolithic aggregator. When it iterates through configured tools, a single YAMLException thrown by js-yaml aborts the entire module's execution. This tight coupling blocks the Node process and binds the lifecycles of fundamentally independent subsystems together.

The Fix

Refactor the YAML parsing and server initialization inside ToolService and ai/services.mjs to implement an isolation boundary.
Catch parser exceptions on a per-server basis. Log the error and gracefully skip the failed server configuration rather than crashing the aggregator.
Ensure the remaining healthy MCP servers are successfully loaded and exposed to the swarm.

Acceptance Criteria

A deliberate syntax error introduced locally into one openapi.yaml file (e.g., github-workflow) does NOT prevent other MCP servers (e.g., memory-core) from booting.
McpServersHealth.spec.mjs gracefully isolates the failure (failing only the broken server's checks) instead of cascading into a full suite crash.

Out of Scope

Migrating existing MCP servers to a new communication protocol or restructuring the directory layouts; this is purely an isolation and resilience refactor of the existing aggregator.

Originating incident: #10305
Fix PR: #10306

Origin Session ID: 0b29a8fa-c6b0-42e2-ab3b-8015a99db2d8 Retrieval Hint: "YAML Cascade eager aggregator refactor ai/services.mjs"