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	13734
title	Knowledge-base MCP tool handbook slice
state	Closed
labels	enhancementaiarchitecturemodel-experience
assignees	neo-gpt
createdAt	Jun 21, 2026, 11:02 AM
updatedAt	Jun 21, 2026, 11:52 AM
githubUrl	https://github.com/neomjs/neo/issues/13734
author	neo-gpt
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	Jun 21, 2026, 11:52 AM

Knowledge-base MCP tool handbook slice

Closed v13.1.0/archive-v13-1-0-chunk-5 enhancementaiarchitecturemodel-experience

neo-gpt commented on Jun 21, 2026, 11:02 AM

Context

Release classification: post-release / boardless (MCP context-budget reduction; not a v13 release blocker).

#9953 is the broad MCP progressive-disclosure parent. The first server slice was delivered by #13268 / PR #13269: ToolService now supports compact tools/list descriptions plus lazy-loaded tool handbooks, and the file-system MCP server opts into that path.

A fresh intake on 2026-06-21 showed the next high-value non-duplicate slice is the Knowledge Base MCP server: its always-loaded descriptions are among the largest remaining primary MCP surfaces (query_documents about 3256 chars, ask_knowledge_base about 2722 chars), while no exact open leaf exists for knowledge-base handbook migration.

Live latest-open sweep: checked the latest 20 open issues on 2026-06-21; no equivalent knowledge-base MCP handbook migration leaf found. Exact live search for "knowledge-base" "tool handbook" found only the broad parent #9953. A2A recency sweep: latest 30 messages had no competing #9953 / knowledge-base handbook claim.

The Problem

ai/mcp/server/knowledge-base/openapi.yaml contains detailed usage guidance inside operation description fields. That is useful guidance, but before this slice it was projected directly into the Knowledge Base MCP tools/list payload. Agents paid that context cost every turn even when they only needed the routing-level tool description.

The shipped shared seam from #13268 makes this a migration problem, not a new architecture problem: keep the details in lazy-loaded handbook entries, make the list projection short, and preserve serviceMapping / OpenAPI alignment.

The Architectural Reality

ai/mcp/ToolService.mjs owns the OpenAPI-to-MCP projection and already supports compactToolDescriptions, toolListDescriptionMaxLength, and getToolHandbook().
ai/mcp/server/knowledge-base/toolService.mjs owns the Knowledge Base service mapping and the transport visibility filter that hides ingest_source_files from local stdio lists.
test/playwright/unit/ai/mcp/server/McpServerListToolsSmoke.spec.mjs already verifies cross-server tools/list shape, OpenAPI operation alignment, serviceMapping alignment, and the file-system handbook slice.

The Fix

Migrate the Knowledge Base MCP server onto the existing handbook seam:

Add get_mcp_tool_handbook to the Knowledge Base OpenAPI contract and service mapping.
Enable compact list descriptions for the Knowledge Base server with the existing ToolService options.
Add explicit short routing summaries for the two largest Knowledge Base tools: query_documents and ask_knowledge_base.
Preserve detailed usage guidance as lazy-loaded handbook content through the existing description fallback.
Extend the existing MCP list-tools smoke coverage to prove the compact projection and handbook lookup.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback / Edge Case	Docs	Evidence
Knowledge Base `tools/list` descriptions	#9953 + #13268 shared `ToolService` seam	Listed Knowledge Base tools expose short routing descriptions capped by `toolListDescriptionMaxLength`.	Tools without `x-neo-tool-summary` fall back to OpenAPI `summary` through `ToolService.buildToolListDescription()`.	`ai/mcp/server/knowledge-base/openapi.yaml`	Unit smoke test asserts every listed Knowledge Base description is <= 120 chars.
`get_mcp_tool_handbook` on Knowledge Base MCP	#9953 + #13268 first-slice contract	The Knowledge Base server exposes a normal MCP tool that returns detailed handbook content for one operation id.	Unknown ids return the structured `TOOL_NOT_FOUND` payload from `ToolService.getToolHandbook()`.	OpenAPI `/tool/handbook` operation	Unit smoke test covers valid and missing handbook lookups.
Detailed query guidance	Existing Knowledge Base OpenAPI operation descriptions	Heavy `query_documents` / `ask_knowledge_base` guidance no longer appears in `tools/list`; it remains available via the handbook.	If dedicated `x-neo-tool-handbook` metadata is absent, `ToolService` uses the operation `description` as the handbook source.	OpenAPI descriptions remain the source of authority.	Unit smoke test asserts compact descriptions omit heavy guidance and handbook includes it.

Decision Record impact

Aligned with #10757 V4.1 and #13268. No ADR change required.

Acceptance Criteria

Knowledge Base MCP exposes get_mcp_tool_handbook through normal MCP tool dispatch.
Knowledge Base tools/list emits compact routing descriptions while preserving schemas, annotations, and transport visibility behavior.
Detailed query_documents guidance remains available through the lazy-loaded handbook lookup.
Unknown handbook ids return structured not-found output.
Focused tests cover list compaction, valid handbook lookup, missing handbook lookup, and cross-server OpenAPI/serviceMapping alignment.

Out of Scope

Migrating github-workflow, memory-core, neural-link, or gitlab-workflow.
Closing #9953.
Changing the shared ToolService API created by #13268.
Changing Knowledge Base query semantics, Chroma access, or ingestion behavior.

Avoided Traps

Do not add a second handbook mechanism. Reuse ToolService.getToolHandbook().
Do not remove schemas, annotations, or tool names from tools/list; the context win is description compaction only.
Do not claim the broad #9953 parent is complete from this single server slice.

Parent: #9953

Related: #10757, #13268, PR #13269

Retrieval Hint: Knowledge Base MCP get_mcp_tool_handbook compact tools/list descriptions #9953 #13268

tobiu closed this issue on Jun 21, 2026, 11:52 AM

tobiu referenced in commit 2931918 - "feat(mcp): add knowledge-base tool handbook slice (#13734) (#13735)" on Jun 21, 2026, 11:52 AM