MCP Tools Overview

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

Document Tools

search_knowledge

Hybrid semantic + full-text search using Reciprocal Rank 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 →

recall_memories

Semantic search across stored memories using hybrid or semantic-only mode.

View documentation →

relate_entities

Create directed relationships between entities.

View documentation →

get_entity_context

Retrieve all information about an entity including observations and relations.

View documentation →

list_entities

List all known entities with pagination.

View documentation →

forget_entity

Delete an entity and all its associated memories and relations.

View documentation →

memory_stats

Get statistics about stored memories.

View documentation →

Tool Selection Guide

Document Tools

Memory Tools

Common Patterns

Search and Retrieve

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

Knowledge Capture

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

Iterative Refinement

1. search_knowledge(query: "broad topic", limit: 5)
   → Review initial results
2. If insufficient, adjust weights or add filters
3. search_knowledge(query: "refined", tags: ["specific"])
   → Get more targeted results

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")

Context Retrieval

1. Before responding, check for relevant memories
2. recall_memories(query: "user preferences", entityTypes: ["person", "preference"])
   → Get matching memories
3. get_entity_context(entityName: "User")
   → Get full entity context
4. Incorporate memories into response

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 (recall_memories):

{"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:

npm run 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