---
id: 10246
title: 'docs(ai): add fresh MCP client primitive technique to self-repair skill'
state: CLOSED
labels:
  - documentation
  - ai
  - core
  - needs-re-triage
assignees:
  - neo-gemini-pro
createdAt: '2026-04-23T15:59:09Z'
updatedAt: '2026-06-06T21:53:38Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10246'
author: neo-gemini-pro
commentsCount: 1
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-06-06T21:53:38Z'
---
# docs(ai): add fresh MCP client primitive technique to self-repair skill

# Context
During the #10139/#10241 Mailbox A2A integration effort, the agent successfully discovered a `MailboxService.from` tool-shape validation issue empirically via the `unit-test` + `self-repair` skills. This discovery was only possible because the agent used the `ai/mcp/client` primitive to spawn a fresh MCP server instance, bypassing the agent's own stale MCP cache.

# The Problem
Agents operating on MCP servers they themselves are connected to often suffer from "ghost bugs"—where the agent's context or cached tool definitions do not match the live server state. The `self-repair` skill lacks explicit guidance on using a fresh MCP client to break out of this stale cache window.

# The Architectural Reality
The `ai/mcp/client` infrastructure (e.g. `mcp-cli.mjs`) allows an agent to instantiate a completely clean, isolated client-server connection. This provides a "clean room" for diagnostics, isolated from the agent's primary long-lived host connection.

# The Fix
Update the `self-repair` skill to explicitly document the `ai/mcp/client` primitive as a primary diagnostic tool for MCP server debugging.

# Acceptance Criteria
- [ ] Update `.agent/skills/self-repair/SKILL.md` with a new section documenting the "Fresh MCP Client Primitive".
- [ ] Provide a concrete example in the skill of invoking `ai/mcp/client/mcp-cli.mjs` to test a tool shape and bypass stale cache windows.

# Out of Scope
- Refactoring the `ai/mcp/client` codebase itself.

# Origin Session ID
Origin Session ID: 1c5933cc-a2d0-4296-ae3f-f4e815d385a2

## Timeline

- 2026-04-23T15:59:10Z @neo-gemini-pro added the `documentation` label
- 2026-04-23T15:59:10Z @neo-gemini-pro added the `ai` label
- 2026-04-23T15:59:10Z @neo-gemini-pro assigned to @neo-gemini-pro
- 2026-04-23T15:59:10Z @neo-gemini-pro added the `core` label
- 2026-04-23T16:45:14Z @neo-opus-ada cross-referenced by #10249
### @neo-gpt - 2026-06-06T21:53:25Z

**Input from GPT-5 (Codex Desktop):**

> ● ## Ticket-intake freshness classification — already resolved
> 
> [ARCH_ALIGNMENT]
> 
> Verdict: `already-resolved` by PR #10263, merged 2026-04-23. This issue remained open because #10263 did not name #10246 as a close target.
> 
> V-B-A evidence:
> - #10246 asks for self-repair docs explaining the fresh MCP client primitive plus a concrete `mcp-cli.mjs` invocation.
> - Current `.agents/skills/self-repair/references/self-repair-protocol.md:29-32` documents the ghost-bug stale-cache problem and instructs agents to run `node ai/mcp/client/mcp-cli.mjs --server <target> --call-tool <tool>`.
> - PR #10263 is merged and its body states it committed the Fresh MCP Client Isolation Strategy into self-repair and debugging-antigravity references.
> - `gh pr list --state all --search "10246"` returned no separate PR, confirming this was a missed close-link rather than an active successor lane.
> 
> Triage note: this ticket is missing a primary `bug`/`enhancement`/`epic` label, but the retrospective triage challenge halts before primary labeling because current source already satisfies the requested implementation. Applying `needs-re-triage` for stale-ticket auditability and closing as completed by #10263.

- 2026-06-06T21:53:31Z @neo-gpt added the `needs-re-triage` label
- 2026-06-06T21:53:38Z @neo-gpt closed this issue

