8000 neuromesh/docs/mcp.md at main · behzad-amini/neuromesh · GitHub
[go: up one dir, main page]

Skip to content

Latest commit

 

History

History
136 lines (97 loc) · 10.6 KB

mcp.md

File metadata and controls

136 lines (97 loc) · 10.6 KB

MCP tools

Transport: stdio JSON-RPC (neuromesh mcp <workspace>). That is what Cursor, Claude, Codex, OpenCode, MiMo CLI, Antigravity, Kilo Code, Trae, Cline, and similar clients launch. Stdio has no TCP port — --port on mcp does nothing. Background index uses the same file-cap rules as neuromesh index (--max-files, NEUROMESH_MAX_FILES, project-slot config.json; default auto, ceiling 50,000). See cli.md.

Warning: Never run neuromesh mcp without a workspace path (or NEUROMESH_WORKSPACE). Without it the server may bind to your home directory and index unrelated projects. Prefer neuromesh connect, which pins an absolute binary path and workspace in MCP config.

Remote / multi-agent: neuromesh monitor (optionally --port 9000 / neuromesh port 9000), then SSE and HTTP as in api.md.

Connect

neuromesh connect           # write project MCP configs + globals for installed apps
neuromesh connect --print   # snippets only
neuromesh connect --project # this repo only
neuromesh connect --global  # also create user-level files

The command points each client at this binary (absolute path) and the current workspace (args: ["mcp", "<workspace>"] plus NEUROMESH_WORKSPACE). PATH is not required. It merges a neuromesh server into existing files and does not delete other MCP servers.

Manual

When neuromesh is on PATH and the IDE runs MCP from your project root (or you set NEUROMESH_WORKSPACE), paste this into MCP settings — no neuromesh connect required.

Cursor — .cursor/mcp.json, or Settings → MCP → Edit config:

{
  "mcpServers": {
    "neuromesh": {
      "command": "neuromesh",
      "args": ["mcp"]
    }
  }
}

Same mcpServers shape works for Claude Desktop (claude_desktop_config.json), Trae (.trae/mcp.json), MiniMax (.minimax/mcp.json), and other clients that use that key. OpenCode uses an mcp object with type: "local" and a command array — run neuromesh connect --print and map the binary + args. MiMo CLI uses .mimo-code.json / ~/.mimo-code/config.json with an mcpServers list. VS Code / Copilot uses .vscode/mcp.json with a top-level servers object instead — run neuromesh connect --print for that shape.

neuromesh connect is still preferred when PATH is unreliable: it writes an absolute command and pins the workspace via args: ["mcp", "<path>"] plus NEUROMESH_WORKSPACE.

Client Project file User file (if the app is installed)
Cursor .cursor/mcp.json ~/.cursor/mcp.json
VS Code / Copilot .vscode/mcp.json (servers) —
Codex .codex/config.toml ~/.codex/config.toml
OpenCode opencode.json / .opencode/opencode.jsonc ~/.config/opencode/opencode.jsonc
MiMo CLI .mimo-code.json ~/.mimo-code/config.json
Antigravity .agents/mcp_config.json ~/.gemini/config/mcp_config.json
Gemini CLI — ~/.gemini/settings.json
Kilo Code .kilo/kilo.jsonc (mcp + command array) kilo.jsonc in the user config dir
Trae .trae/mcp.json Trae/User/mcp.json
MiniMax Code .minimax/mcp.json same mcpServers snippet as Cursor
Claude Desktop / Code .mcp.json claude_desktop_config.json
Windsurf / Cline / Roo — their existing MCP settings files

Stdout is JSON-RPC only (NDJSON). Handshake logs go to stderr so Antigravity and other strict hosts stay happy.

Agent loop

neuromesh_get_context(task_description)
  → if coverage is partial or no_seed_resolved: neuromesh_search_symbols
  → if you need diagnostics: neuromesh_explain_packet(packet_id)
  → if a folded body is required: neuromesh_expand_fold(fold_id)
  → after a successful edit: neuromesh_record_feedback

Start with get_context. The default packet is minimal: packet_id, coverage string, selected/packet tokens, skeletonized files, fold descriptors without bodies. missing and next appear only when coverage is partial or no_seed_resolved (zero identifiers resolved — do not treat a utility fallback file as the answer). After a good edit, always call neuromesh_record_feedback — that is the synaptic learning step; without it the next packet does not change.

Agent rule (recommended)

neuromesh connect only registers the MCP server. It does not tell the IDE agent to call those tools. Without project instructions, many agents still Read / Grep whole files and skip NeuroMesh.

Full tutorial (every client): agent-guide.md — Cursor, VS Code/Copilot, Claude, Codex, OpenCode, MiMo CLI, Antigravity, Kilo, Trae, MiniMax, Gemini CLI, Windsurf, Cline/Roo, Zed, plus a one-shot prompt and smoke test.

Quick Cursor install:

mkdir -p .cursor/rules
cp /path/to/neuromesh/docs/agent-rule.mdc .cursor/rules/neuromesh.mdc

Cursor-ready template: agent-rule.mdc. Same body without YAML frontmatter lives in the guide for AGENTS.md / CLAUDE.md / Copilot instructions.

Tools

Tool Input Returns
neuromesh_get_context task_description, prompt, or task; optional mode; optional response_detail Compact evidence packet (minimal by default)
neuromesh_explain_packet packet_id; optional include On-demand diagnostics (no fold bodies)
neuromesh_expand_fold fold_id, node_id, or query; optional reason Original folded body
neuromesh_get_file_skeleton file_path, optional active_symbols One skeletonized file + fold descriptors (no bodies)
neuromesh_search_symbols query, optional limit Ranked hits
neuromesh_get_dependencies name or path Typed neighbors
neuromesh_trace query, direction (in / out / both), depth Call/import chains. Inbound includes throw new, throw $e after catch (Type $e), and ternary new Type. Trace the exception that is actually thrown.
neuromesh_analyze_impact query, depth Blast radius
neuromesh_get_architecture — Languages, packages, entry points
neuromesh_get_project_memory — Seeded facts
neuromesh_record_feedback task_success, touched_nodes STDP on that path; persists base_relevance to graph.bin
neuromesh_get_node_weights query / symbol / path Read access_count, base_relevance, learning_bonus (verify learning)
neuromesh_expand_gap path, optional token_cap Cheap skeleton for packet_gaps paths
neuromesh_get_stats — Node/edge counts

Aliases exist for older clients (activate_context, expand_context, search_context, explain_packet, get_context_details). Prefer the neuromesh_* names.

Evidence packet

neuromesh_get_context is the product. Default (response_detail=minimal) shape:

  • packet_id — session key for neuromesh_explain_packet (LRU, ~10 minutes, 32 packets)
  • coverage — claim (no_recorded_gap, bounded, partial, no_seed_resolved), plus covered, skipped, sidecar_files, unsure, packet_gaps, and optional semantic_coverage for style tasks. no_recorded_gap only when every attempted seed resolved, packet_gaps is empty, no sidecar connector files, and the packet was not budget-truncated. bounded means seeds resolved but optional connector/sidecar fill or budget cut was applied — do not Grep unless you need more context.
  • tokens.selected / tokens.packet — raw selected vs skeletonized packet
  • files[] — path, short why, optional sidecar: true (connector fill, not a task anchor), skeleton code, folds[] as descriptors (fold_id, symbol, signature, lines, saved_tokens) with no original_body
  • missing / next — only when coverage is incomplete; one search action, not a repeated seed list

mode: balanced (default, +5,000 fill), max_savings (0), max_quality (+16,000). Critical tasks (auth / payment / secret) upgrade to max quality. mode does not add metadata; response_detail does (minimal ≤ 256 metadata tokens, standard ≤ 750, diagnostic on demand).

neuromesh_explain_packet returns seeds, selection, budget, physarum, and membrane for a packet_id. selection.candidates lists ranked files with selected, emitted, drop_stage, score_breakdown, and learning_bonus — use this when debugging why feedback did or did not change the emitted packet. Pass include: ["graph"] for graph stats; otherwise use neuromesh_get_stats. The HTTP monitor (/api/simulate) still requests diagnostic so the VS Code inspector keeps the nested evidence_packet.

Folds

Markers look like:

/* [neuromesh:fold:fold_unused_helper_1 | 12 lines folded | fn unused_helper()] */

Pass that fold_id to neuromesh_expand_fold as fold_id, node_id, or query. The full marker line also works. Folds persist for the MCP session (same process, same project). Folds from the current activation stay resolvable; older activations are LRU-trimmed (cap 2000) so long sessions do not grow without bound. A new project id wipes the registry. Ids include a short path tag so two files that both fold write do not collide. Fold bodies are never in get_context or get_file_skeleton; only expand_fold restores them.

Learning

neuromesh_record_feedback updates base_relevance, edge pheromones, and episodic memory. Durable weights persist in graph.bin (episode checkpoints in the snapshot); neuromesh.json holds episodic records for recall. The response includes episode_saved_this_call, learning_episodes_in_store, and persisted_to: "graph.bin" (episodes_recorded is a per-call 0/1 compat field).

E 31B9 ffects apply on the next get_context in the same MCP process: search ranking, selector fill, unified scoring, and the emission pipeline (which files actually ship after fill/packet caps). Negative feedback lowers base_relevance and can suppress penalized files from the optional set. Use neuromesh_get_node_weights before and after feedback to verify deltas. When a file shows selected: true but is missing from files[], call neuromesh_explain_packet and check emitted / drop_stage on selection.candidates.

Learning does not change a packet mid-request; restart the MCP server to load persisted graph state from a prior session. Positive reinforcement (learning_bonus ≥ learning_promotion_min_bonus, default 14) can add focus-matched files to the next packet; it does not inject heavily reinforced files into unrelated queries. Negative reinforcement drops penalized hop-expanded files. Benchmark locally with neuromesh eval --learning.

0