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	13268
title	MCP tool handbook: first server slice
state	Closed
labels	enhancementdeveloper-experienceaiarchitecturemodel-experience
assignees	neo-gpt
createdAt	Jun 14, 2026, 11:54 PM
updatedAt	Jun 15, 2026, 2:52 AM
githubUrl	https://github.com/neomjs/neo/issues/13268
author	neo-gpt
commentsCount	0
parentIssue	10757
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 15, 2026, 2:52 AM

MCP tool handbook: first server slice

Closed v13.1.0/archive-v13-1-0-chunk-2 enhancementdeveloper-experienceaiarchitecturemodel-experience

neo-gpt commented on Jun 14, 2026, 11:54 PM

Context

#10757 AC6 names V4.1 as MCP tool description compaction plus a meta-tool (getDescription / get_mcp_tool_handbook) and explicitly treats #9953 as prior art to supersede / merge. The parent still exposes V4.1 only as epic-body AC text, while #9953 remains broad enough to invite a repo-wide truncation PR without a first-slice contract.

I posted a Contract Ledger alignment comment on #9953 to separate the safe first slice from the broad original checklist: https://github.com/neomjs/neo/issues/9953#issuecomment-4703178943

Release classification: post-release / boardless (model-experience context-tax reduction; not a v13 release blocker).

Live latest-open sweep: checked the latest 20 open issues on 2026-06-14; no equivalent first-slice V4.1 child found. Exact live search for get_mcp_tool_handbook found only broad prior art #9953, parent #9950, and parent #10757. A2A in-flight claim sweep: latest 30 messages showed no competing claim for #9953 / V4.1 / MCP handbook scope. Knowledge Base semantic sweep was attempted and is currently unavailable (Failed to access collections), so this ticket is anchored to live GitHub + local source search.

The Problem

Current source search found no get_mcp_tool_handbook, get_*tool*handbook, or equivalent MCP progressive-disclosure endpoint. The existing MCP listing path still builds the always-loaded tools/list projection from OpenAPI operation metadata:

ai/mcp/ToolService.mjs:147-170 maps OpenAPI summary / description, schemas, and annotations into the listed MCP tool shape.
ai/mcp/ToolService.mjs:183-230 exposes the list projection, including projection filtering.
ai/mcp/server/BaseServer.mjs:325-329 serves ListToolsRequestSchema by returning that projection.
ai/mcp/server/BaseServer.mjs:353-382 serves CallToolRequestSchema, so any handbook endpoint must remain a normal MCP tool call rather than a separate side channel unless explicitly justified.

The unsafe interpretation of #9953 is "truncate all descriptions everywhere". That would reduce context tax, but it can silently remove the detailed usage text agents still need. The missing first slice is a bounded server implementation that proves where detailed text moves, how agents lazy-load it, and how unmigrated servers remain compatible.

The Architectural Reality

MCP servers in this repo declare operation contracts in ai/mcp/server/*/openapi.yaml and instantiate ToolService from per-server toolService.mjs files. ToolService already owns the transformation from OpenAPI operations to the MCP tools/list payload, including inputSchema, optional outputSchema, and annotations. BaseServer is the common request-handler boundary for tools/list and call_tool.

That means the first slice should stay inside the existing MCP service/listing seam instead of adding a parallel manifest format or client-only convention. OpenAPI remains the source of authority for the detailed handbook body in the first slice; dedicated handbook metadata can be a later additive refinement if the fallback proves too crude.

The Fix

Implement one representative server slice plus a shared projection seam:

Add a reusable tool-list projection / handbook lookup path in the existing MCP service layer, without dropping listed tool names, titles, input schemas, output schemas, or annotations.
Expose a get_mcp_tool_handbook MCP tool on one representative server.
Return bounded short descriptions from tools/list for that migrated server only.
Return the detailed per-tool handbook body through the new lazy-loaded tool.
Leave unmigrated servers unchanged unless they explicitly opt into the projection.

If the implementation introduces a new .mjs helper file, run the structural pre-flight before authoring it; otherwise keep the change inside existing sibling service boundaries.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback / Edge Case	Docs	Evidence
`tools/list` description projection for the migrated server	`#10757` AC6 + `#9953` prior art + `ai/mcp/ToolService.mjs:147-170`	Listed tools use bounded short descriptions while preserving `name`, `title`, `inputSchema`, optional `outputSchema`, and `annotations`.	If no dedicated short description exists, derive a bounded value from OpenAPI `summary` / `description` without dropping the tool.	OpenAPI descriptions / JSDoc only where needed.	Unit test proves bounded list output shape and schema/annotation preservation.
`get_mcp_tool_handbook` MCP tool (new)	This ticket + `#10757` V4.1	Given a tool id/name, returns the detailed handbook text for exactly one tool, so agents lazy-load details instead of receiving every detail in `tools/list`.	Unknown tool id returns a structured not-found payload; normal MCP dispatch / projection behavior remains intact.	Representative server `openapi.yaml` documents the operation.	Unit test covers valid id, unknown id, and schema validation.
Handbook content source	Current OpenAPI operation `description` / `summary` metadata	Detailed usage guidance is preserved in the lazy-loaded handbook body for migrated tools.	Missing detailed metadata falls back to the best available summary/description and marks the handbook as derived.	Comment or schema text documents the source-of-truth rule.	Fixture/test proves source mapping and fallback.
Rollout boundary	Current `ai/mcp/server/*/openapi.yaml` server topology	Only one representative server opts into the first slice; shared seam is reusable for later servers.	Unmigrated servers keep current `tools/list` behavior.	Migration note in PR body.	Regression test shows migrated and unmigrated behavior are distinct and compatible.

Decision Record impact

Aligned with #10757 (cognitive-load cycle 2 V4.1). No ADR change required for the first slice.

Acceptance Criteria

A shared MCP tool-list projection / handbook lookup seam exists in the current MCP service layer or an adjacent structurally validated helper.
One representative MCP server exposes get_mcp_tool_handbook through normal MCP tool dispatch.
That server's tools/list descriptions are bounded while preserving schemas and annotations.
Unknown handbook tool ids return a structured not-found response.
Unmigrated servers remain compatible and keep their current listing behavior.
Focused tests cover bounded listing, valid handbook lookup, unknown id, and unmigrated fallback behavior.
The PR body references parent #10757 and prior art #9953, but does not auto-close #9953.

Out of Scope

Repo-wide MCP description truncation.
V4.2 return-value pagination.
V4.3 bulk operations.
V4.4 output-as-Atlas reshaping.
Closing #9953 or #9950.
Changing agent harness local deferred-tool discovery.

Avoided Traps

Do not truncate every server manifest first; prove the lazy-load contract on one representative server.
Do not remove schemas, annotations, or tool names from tools/list; the context win is description/details, not contract erasure.
Do not use Resolves #9953; this is a first slice and should not close the broad prior-art ticket by magic keyword.

Parent: #10757

Prior art: #9953, #9950

Origin Session ID: 4ed21ddf-b92f-45ce-8689-bb3ebb563dd9

Retrieval Hint: MCP tool handbook get_mcp_tool_handbook tools/list description compaction V4.1 #9953 #10757