TxtAI Assistant MCP

Created By

rmtech1a year ago

Model Context Protocol (MCP) server implementation for semantic vector search and memory management using TxtAI. This server provides a robust API for storing, retrieving, and managing text-based memories with semantic vector database search capabilities. You can use Claude and Cline AI as well.

# python

# mcp

Overview Content Tools Comments

Content

TxtAI Assistant MCP

A Model Context Protocol (MCP) server implementation for semantic search and memory management using txtai. This server provides a robust API for storing, retrieving, and managing text-based memories with semantic search capabilities.

About txtai

This project is built on top of txtai, an excellent open-source AI-powered search engine created by NeuML. txtai provides:

🔍 All-in-one semantic search solution
🧠 Neural search with transformers
💡 Zero-shot text classification
🔄 Text extraction and embeddings
🌐 Multi-language support
🚀 High performance and scalability

We extend txtai's capabilities by integrating it with the Model Context Protocol (MCP), enabling AI assistants like Claude and Cline to leverage its powerful semantic search capabilities. Special thanks to the txtai team for creating such a powerful and flexible tool.

Features

🔍 Semantic search across stored memories
💾 Persistent storage with file-based backend
🏷️ Tag-based memory organization and retrieval
📊 Memory statistics and health monitoring
🔄 Automatic data persistence
📝 Comprehensive logging
🔒 Configurable CORS settings
🤖 Integration with Claude and Cline AI

Prerequisites

Python 3.8 or higher
pip (Python package installer)
virtualenv (recommended)

Installation

Clone this repository:

git clone https://github.com/yourusername/txtai-assistant-mcp.git
cd txtai-assistant-mcp

Run the start script:

./scripts/start.sh

The script will:

Create a virtual environment
Install required dependencies
Set up necessary directories
Create a configuration file from template
Start the server

Configuration

The server can be configured using environment variables in the .env file. A template is provided at .env.template:

# Server Configuration
HOST=0.0.0.0
PORT=8000

# CORS Configuration
CORS_ORIGINS=*

# Logging Configuration
LOG_LEVEL=DEBUG

# Memory Configuration
MAX_MEMORIES=0

Integration with Claude and Cline AI

This TxtAI Assistant can be used as an MCP server with Claude and Cline AI to enhance their capabilities with semantic memory and search functionality.

Configuration for Claude

To use this server with Claude, add it to Claude's MCP configuration file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "txtai-assistant": {
      "command": "path/to/txtai-assistant-mcp/scripts/start.sh",
      "env": {}
    }
  }
}

Configuration for Cline

To use with Cline, add the server configuration to Cline's MCP settings file (typically located at ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "txtai-assistant": {
      "command": "path/to/txtai-assistant-mcp/scripts/start.sh",
      "env": {}
    }
  }
}

Available MCP Tools

Once configured, the following tools become available to Claude and Cline:

store_memory: Store new memory content with metadata and tags

{
  "content": "Memory content to store",
  "metadata": {
    "source": "conversation",
    "timestamp": "2023-01-01T00:00:00Z"
  },
  "tags": ["important", "context"],
  "type": "conversation"
}

retrieve_memory: Retrieve memories based on semantic search

{
  "query": "search query",
  "n_results": 5
}

search_by_tag: Search memories by tags

{
  "tags": ["important", "context"]
}

delete_memory: Delete a specific memory by content hash

{
  "content_hash": "hash_value"
}

get_stats: Get database statistics

{}

check_health: Check database and embedding model health

{}

Usage Examples

In Claude or Cline, you can use these tools through the MCP protocol:

# Store a memory
<use_mcp_tool>
<server_name>txtai-assistant</server_name>
<tool_name>store_memory</tool_name>
<arguments>
{
  "content": "Important information to remember",
  "tags": ["important"]
}
</arguments>
</use_mcp_tool>

# Retrieve memories
<use_mcp_tool>
<server_name>txtai-assistant</server_name>
<tool_name>retrieve_memory</tool_name>
<arguments>
{
  "query": "what was the important information?",
  "n_results": 5
}
</arguments>
</use_mcp_tool>

The AI will automatically use these tools to maintain context and retrieve relevant information during conversations.

API Endpoints

Store Memory

POST /store

Store a new memory with optional metadata and tags.

Request Body:

{
    "content": "Memory content to store",
    "metadata": {
        "source": "example",
        "timestamp": "2023-01-01T00:00:00Z"
    },
    "tags": ["example", "memory"],
    "type": "general"
}

Search Memories

POST /search

Search memories using semantic search.

Request Body:

{
    "query": "search query",
    "n_results": 5,
    "similarity_threshold": 0.7
}

Search by Tags

POST /search_tags

Search memories by tags.

Request Body:

{
    "tags": ["example", "memory"]
}

Delete Memory

DELETE /memory/{content_hash}

Delete a specific memory by its content hash.

Get Statistics

GET /stats

Get system statistics including memory counts and tag distribution.

Health Check

GET /health

Check the health status of the server.

Directory Structure

txtai-assistant-mcp/
├── server/
│   ├── main.py           # Main server implementation
│   └── requirements.txt  # Python dependencies
├── scripts/
│   └── start.sh         # Server startup script
├── data/                # Data storage directory
├── logs/                # Log files directory
├── .env.template        # Environment configuration template
└── README.md           # This file