MCP Tools Overview

textrawl exposes 18 tools via the Model Context Protocol (MCP). These tools allow Claude and other MCP clients to search, retrieve, create, and manage documents, memories, conversations, and insights in your knowledge base.

Document Tools

search

Hybrid semantic + full-text search using Reciprocal Rank Fusion. Optionally include memories and conversations with weighted cross-source fusion.

View documentation →

get_document

Retrieve full document content by ID, optionally including chunks.

View documentation →

list_documents

Browse documents with pagination and filtering by type or tags.

View documentation →

update_document

Update document title and/or tags for organization.

View documentation →

add_note

Create markdown notes with automatic chunking and embedding.

View documentation →

Memory Tools (Persistent Memory)

Enable with ENABLE_MEMORY=true (default). Requires setup-db-memory.sql schema.

remember_fact

Store facts about entities (people, projects, concepts) with automatic semantic embedding.

View documentation →

build_knowledge

Store multiple facts and relations in a single batch call.

View documentation →

query_memory

Query the memory graph: search memories, look up entity context, or list entities. Modes: search, entity, list.

View documentation →

relate_entities

Create directed relationships between entities.

View documentation →

forget_entity

Delete an entity and all its associated memories and relations.

View documentation →

extract_memories

Extract entities and facts from text using LLM analysis. Requires ENABLE_MEMORY_EXTRACTION=true.

View documentation →

Conversation Tools (Conversation Memory)

Enable with ENABLE_CONVERSATIONS=true (default). Requires setup-db-conversation.sql schema.

save_conversation_context

Save conversation summary and turns for later recall.

View documentation →

query_conversations

Query past conversations: search by content, get by ID/key, or list sessions. Modes: search, get, list.

View documentation →

delete_conversation

Delete a conversation session and all its turns.

View documentation →

Insight Tools (Proactive Discovery)

Enable with ENABLE_INSIGHTS=true (default).

get_insights

View cross-source connections, themes, entity bridges, and outliers discovered from your knowledge base.

View documentation →

discover_connections

Trigger an insight scan to find patterns across your knowledge base. Best used after bulk imports.

View documentation →

dismiss_insight

Dismiss an insight so it no longer appears in results.

View documentation →

Stats

get_stats

Get statistics across all features with scope selection: all, knowledge, memory, conversations, insights.

View documentation →

Tool Selection Guide

Document Tools

Memory Tools

Conversation Tools

Insight Tools

Common Patterns

Search and Retrieve

1. search(query: "user question")
   → Get top matching chunks
2. get_document(documentId: results[0].documentId)
   → Get full document content
3. Synthesize answer from full context

Comprehensive Context

1. search(query: "topic", includeMemories: true, includeConversations: true)
   → Get results from all sources at once
2. Synthesize answer from documents, memories, and past conversations

Knowledge Capture

1. User provides information
2. add_note(title: "...", content: "...", tags: ["topic"])
   → Creates document + generates embeddings
3. Return documentId for reference

Memory Capture

1. User mentions facts about themselves or preferences
2. remember_fact(entityName: "User", entityType: "person", observation: "prefers TypeScript")
   → Store as atomic fact with embedding
3. For relationships: relate_entities(fromEntity: "User", relation: "works_at", toEntity: "Acme")

Conversation Continuity

1. At end of conversation, save context:
   save_conversation_context(summary: "...", sessionKey: "project-planning", recentTurns: [...])
2. At start of next session, recall:
   query_conversations(mode: "search", query: "project planning")
   → Resume with full context

Insight Discovery

1. After bulk import (email, documents):
   discover_connections(maxChunks: 500)
2. Check for discoveries:
   get_insights(status: "new")
3. Review and dismiss irrelevant insights:
   dismiss_insight(insightId: "...")

Response Format

All tools return JSON-formatted responses. Memory tools support two response modes controlled by COMPACT_RESPONSES environment variable.

Compact Mode (Default)

COMPACT_RESPONSES=true - Reduces token usage by 40-60% using short keys and no whitespace.

Key mappings:

Example (query_memory mode=search):

{"n":2,"e":[{"n":"Jeff","t":"person","m":[{"c":"prefers dark mode","s":0.92}]}]}

Verbose Mode

COMPACT_RESPONSES=false - Human-readable responses with full key names and formatting.

{
  "query": "preferences",
  "totalMemories": 2,
  "entities": [
    {
      "entityName": "Jeff",
      "entityType": "person",
      "memories": [
        {"content": "prefers dark mode", "source": "conversation", "score": 0.92}
      ]
    }
  ]
}

Error Handling

Errors are returned in the result object (not as protocol errors):

{
  "error": "Error type",
  "message": "Human-readable explanation with fix suggestion"
}

Common errors:

Testing Tools

Use the MCP Inspector to test tools interactively:

pnpm inspector

Opens a web UI at http://localhost:5173 where you can:

1. Select a tool from the dropdown
2. Fill in parameters
3. Execute and view response
4. Debug issues