TxtAI Assistant MCP

TxtAI Assistant MCP

一个基于 txtai 实现的模型上下文协议（MCP）服务，用于语义搜索和记忆管理。该服务提供强大的 API，可通过语义搜索功能存储、检索和管理基于文本的记忆。

关于 txtai

本项目基于 txtai 构建。txtai 是由 NeuML 创建的一款优秀的开源 AI 搜索引擎。txtai 提供：

• 🔍 一体化语义搜索解决方案
• 🧠 使用 transformers 进行神经搜索
• 💡 零样本文本分类
• 🔄 文本提取和嵌入
• 🌐 多语言支持
• 🚀 高性能和可扩展性

我们通过将 txtai 与模型上下文协议（MCP）集成来扩展其功能，让 Claude 和 Cline 等 AI 助手能够利用其强大的语义搜索能力。特别感谢 txtai 团队打造了如此强大且灵活的工具。

功能

• 🔍 对存储的记忆进行语义搜索
• 💾 使用基于文件的后端进行持久化存储
• 🏷️ 基于标签整理和检索记忆
• 📊 记忆统计和运行状况监控
• 🔄 自动持久化数据
• 📝 全面的日志记录
• 🔒 可配置的 CORS 设置
• 🤖 与 Claude 和 Cline AI 集成

先决条件

• Python 3.8 或更高版本
• pip（Python 包安装程序）
• virtualenv（推荐）

安装

1. 克隆此仓库：

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

2. 运行启动脚本：

./scripts/start.sh

该脚本将：

• 创建虚拟环境
• 安装所需依赖项
• 设置必要的目录
• 根据模板创建配置文件
• 启动服务

配置

可以使用 .env 文件中的环境变量配置服务。模板文件位于 .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

与 Claude 和 Cline AI 集成

此 TxtAI Assistant 可作为 MCP 服务与 Claude 和 Cline AI 配合使用，增强它们的语义记忆和搜索功能。

Claude 配置

要将此服务与 Claude 配合使用，请将其添加到 Claude 的 MCP 配置文件中（在 macOS 上通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：

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

Cline 配置

要与 Cline 配合使用，请将服务配置添加到 Cline 的 MCP 设置文件中（通常位于 ~/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": {}
    }
  }
}

可用的 MCP 工具

配置完成后，Claude 和 Cline 将可以使用以下工具：

1. store_memory：存储带有元数据和标签的新记忆

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

2. retrieve_memory：根据语义搜索检索记忆

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

3. search_by_tag：按标签搜索记忆

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

4. delete_memory：通过内容哈希删除特定记忆

{
  "content_hash": "hash_value"
}

5. get_stats：获取数据库统计信息

{}

6. check_health：检查数据库和嵌入模型的运行状况

{}

使用示例

在 Claude 或 Cline 中，你可以通过 MCP 协议使用这些工具：

# 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>

AI 会在对话过程中自动使用这些工具来维护上下文并检索相关信息。

API 端点

存储记忆

POST /store

存储带有可选元数据和标签的新记忆。

请求正文：

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

搜索记忆

POST /search

使用语义搜索查找记忆。

请求正文：

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

按标签搜索

POST /search_tags

按标签搜索记忆。

请求正文：

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

删除记忆

DELETE /memory/{content_hash}

通过内容哈希删除特定记忆。

获取统计信息

GET /stats

获取系统统计信息，包括记忆数量和标签分布。

运行状况检查

GET /health

检查服务的运行状况。

目录结构

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

数据存储

记忆和标签以 JSON 文件的形式存储在 data 目录中：

• memories.json：包含所有已存储的记忆
• tags.json：包含标签索引

日志记录

日志存储在 logs 目录中。默认日志文件为 server.log。

开发

如需为此项目做出贡献：

1. 复刻此代码仓库
2. 创建一个功能分支
3. 进行修改
4. 提交拉取请求

错误处理

服务实现了全面的错误处理：

• 无效请求会返回相应的 HTTP 状态码
• 错误会连同堆栈跟踪一起记录
• 响应中会返回用户友好的错误消息

安全注意事项

• 可通过环境变量配置 CORS 设置
• 会对文件路径进行清理，以防止目录遍历
• 会对所有端点执行输入验证

许可证

此项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

贡献

欢迎贡献！请随时提交拉取请求。

支持

如果遇到任何问题或有疑问，请在 GitHub 代码仓库中提交问题。