## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# API Reference Overview

m1nd currently exposes 78 MCP tools over JSON-RPC 2.0 via stdio. Every tool requires `agent_id` as a parameter. The exported MCP schema uses underscore-based canonical names such as `trail_resume`, `perspective_start`, and `apply_batch`.

Several tools now do more than return raw results. On the main structural flows you should expect some combination of:

- `proof_state`
- `next_suggested_tool`
- `next_suggested_target`
- `next_step_hint`

That matters for how you integrate m1nd into an agent loop: treat many responses as workflow guidance, not just data blobs.

## Tool Index

### Core Activation

Tool | Description
--- | ---
`activate` | Spreading activation query across the graph
`warmup` | Task-based warmup and priming
`resonate` | Resonance analysis: harmonics, sympathetic pairs, and resonant frequencies

### Analysis

Tool | Description
--- | ---
`impact` | Impact radius / blast analysis for a node
`predict` | Co-change prediction for a modified node
`counterfactual` | What-if node removal simulation
`fingerprint` | Activation fingerprint and equivalence detection
`hypothesize` | Graph-based hypothesis testing against structural claims
`differential` | Focused structural diff between two graph snapshots
`diverge` | Structural drift between a baseline and current graph state

### Memory, Trails, and Learning

Tool | Description
--- | ---
`learn` | Explicit feedback-based edge adjustment
`drift` | Weight and structural drift analysis
`why` | Path explanation between two nodes
`trail_save` | Persist current investigation state
`trail_resume` | Restore a saved investigation with next-step guidance
`trail_list` | List saved investigation trails
`trail_merge` | Combine two or more investigation trails

### Exploration

Tool | Description
--- | ---
`seek` | Intent-aware semantic code search
`scan` | Pattern-aware structural code analysis
`missing` | Detect structural holes and missing connections
`trace` | Map runtime errors to structural root causes
`timeline` | Git-based temporal history for a node
`federate` | Multi-repository federated graph ingestion
`federate_auto` | Discover repo candidates from external path evidence and optionally federate them

### Perspectives

Tool | Description
--- | ---
`perspective_start` | Enter a perspective: navigable route surface from a query
`perspective_routes` | Browse the current route set with pagination
`perspective_inspect` | Expand a route with metrics, provenance, and affinity
`perspective_peek` | Extract a code/doc slice from a route target
`perspective_follow` | Follow a route: move focus to target, synthesize new routes
`perspective_suggest` | Get the next best move suggestion
`perspective_affinity` | Discover probable connections a route target might have
`perspective_branch` | Fork navigation state into a new branch
`perspective_back` | Navigate back to previous focus
`perspective_compare` | Compare two perspectives on shared/unique nodes
`perspective_list` | List all perspectives for an agent
`perspective_close` | Close a perspective and release associated locks

### Lifecycle, Search, and Surgical

Tool | Description
--- | ---
`ingest` | Ingest or re-ingest a codebase, descriptor, or memory corpus
`health` | Server health and statistics
`search` | Literal, regex, or semantic-graph-aware content search
`glob` | Graph-aware file globbing
`view` | Fast line-numbered file inspection
`validate_plan` | Validate a modification plan against the code graph
`surgical_context_v2` | Pull connected edit context with proof-oriented options
`apply_batch` | Atomic multi-file write with progress, verification, and handoff

The grouped reference pages below still organize the surface by area, but the current best operational map is in `help`, the README tool table, and the live `tools/list` response.

## Common Parameters

Every tool requires the `agent_id` parameter:

Parameter | Type | Required | Description
--- | --- | --- | ---
`agent_id` | `string` | Yes | Identifier for the calling agent. Used for session tracking, perspective ownership, lock ownership, and multi-agent coordination.

Agent IDs are free-form strings. Convention: use the agent’s name or role identifier (e.g. `"jimi"`, `"hacker-auth"`, `"forge-build"`).

## JSON-RPC Request Format

m1nd uses the MCP protocol over JSON-RPC 2.0 via stdio. All tool calls use the `tools/call` method.

### Request structure

    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/call",
      "params": {
            "name": "activate",
        "arguments": {
          "agent_id": "jimi",
          "query": "session management"
        }
      }
    }

### Successful response

    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": {
        "content": [
          {
            "type": "text",
            "text": "{ ... pretty-printed JSON result ... }"
          }
        ]
      }
    }

The `text` field contains the tool-specific output as a pretty-printed JSON string. Parse it to get the structured result.

### Error response (tool execution error)

Tool execution errors are returned as MCP `isError` content, not as JSON-RPC errors. Many current errors are recovery-oriented and may include fields such as `hint`, `workflow_hint`, `example`, or `suggested_next_step`.

    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": {
        "content": [
          {
            "type": "text",
            "text": "{ \"error\": \"...\", \"hint\": \"...\", \"suggested_next_step\": \"...\" }"
          }
        ],
        "isError": true
      }
    }

### Error response (protocol error)

JSON-RPC protocol errors use standard error codes:

    {
      "jsonrpc": "2.0",
      "id": 1,
      "error": {
        "code": -32601,
        "message": "Method not found: bad_method"
      }
    }

## Error Codes

Code | Meaning
--- | ---
`-32700` | Parse error – invalid JSON
`-32601` | Method not found – unknown JSON-RPC method
`-32603` | Internal error – server-level failure

Tool-specific errors (node not found, perspective not found, lock ownership violation, etc.) are returned via `isError: true` in the content, not as JSON-RPC errors.

## Transport

m1nd supports two stdio transport modes, auto-detected per message:

- Framed: `Content-Length: N\r\n\r\n{json}` – standard MCP/LSP framing. Used by Claude Code, Cursor, and most MCP clients.
- Line: `{json}\n` – one JSON object per line. Used by simple scripts and testing.

The server auto-detects which mode each incoming message uses and responds in the same mode.

## Tool Name Normalization

The exported MCP schema uses underscore-based canonical names, but the server still accepts legacy dotted and underscored aliases when possible:

- `activate` is canonical
- `m1nd.activate` is accepted as a compatibility alias
- `m1nd_activate` is also accepted where normalization applies

If you are generating tool calls from an MCP client, prefer the canonical schema names returned by `tools/list`.

## Protocol Handshake

Before calling tools, MCP clients perform a handshake:

    {"jsonrpc":"2.0","id":0,"method":"initialize","params":{}}

Response:

    {
      "jsonrpc": "2.0",
      "id": 0,
      "result": {
        "protocolVersion": "2024-11-05",
        "serverInfo": { "name": "m1nd-mcp", "version": "0.6.1" },
        "capabilities": { "tools": {} }
      }
    }

Then list available tools:

    {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

This returns the full schema for all 63 tools with `inputSchema` for each.