Mnemosyne MCP Server: MCP Tools

Level 2 (Topic) — The 5 MCP tools exposed by the server.

Concept

The server registers 5 tools via the mark3labs/mcp-go SDK (v0.45.0). Each tool has a defined input schema and handler. All handlers generate a random trace ID for request tracing.

Tool Inventory

1. ingest_memory

Store a technical chronicle in semantic memory.

Returns: {"status": "queued", "request_id": "<trace_id>"} — ingestion is async, result does not confirm success.

Handler flow: see Ingest Memory Detail

2. retrieve_memories

Semantic search across all stored memories.

Returns: formatted list with ID, date, content.

Handler flow: see Retrieve Memories Detail

Note: temporal filters (daysBack, startStr, endStr) exist in the controller but are NOT exposed in the MCP schema. See Known Issues.

3. get_memory

Retrieve full text of a specific memory by ID.

Returns: full memory content.

4. list_memories

List recent memory IDs and titles.

Returns: ID, date, extracted title (looks for TITLE: prefix, falls back to first 50 chars).

5. delete_memory

Delete a specific memory by UUID.

Returns: deletion confirmation.

Tool Registration

Tools are registered in internal/mcp/mcp.go (lines 41-93). Each handler:

1. Generates a random trace ID
2. Parses input schema
3. Delegates to logic.Controller method
4. Returns formatted result

A comment at line 92 notes: // T2.3: blueprint tools removed — blueprint tools were previously defined but removed.

Calling MCP Tools via HTTP (Streamable HTTP)

Il server è deployato in modalità MCP_TRANSPORT=http (Streamable HTTP). Ogni richiesta richiede una sessione MCP: la prima chiamata initialize restituisce un session ID nell’header HTTP Mcp-Session-Id, che va reinviato in tutte le richieste successive.

Ricetta curl (inizializzazione + chiamata tool)

# 1. Initialize: estrai session ID dall'header di risposta
SESSION=$(curl -s -D - --connect-timeout 5 http://192.168.1.240:8004/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"client","version":"1"}},"id":1}' \
  | grep -i "^Mcp-Session-Id:" | tr -d '\r' | awk '{print $2}')

echo "Session: $SESSION"

# 2. Chiamata tool con session header
curl -s http://192.168.1.240:8004/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_memories","arguments":{"limit":5}},"id":2}'

# 3. Ingest una memoria
curl -s http://192.168.1.240:8004/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ingest_memory","arguments":{"content":"[[[CHRONICLE_START]]]\nTS: 2026-05-20\nTITLE: Esempio\nTAGS: Software-IT: Development\nBODY: Test\n[[[CHRONICLE_END]]]","timestamp":"2026-05-20T22:00:00Z"}},"id":3}'

Attenzione: initialize non funziona se preceduta da un’altra richiesta fallita (es. con session scaduta). Per ogni nuova sessione, usa un fresh initialize.

Endpoint

See Also

• Parent hub: mnemosyne-mcp-server
• Sibling topics: Architecture, Embedding Model, Async Ingestion, Database Schema
• Details: Ingest Memory Detail, Retrieve Memories Detail