MCP Context Server

🚀 MCP上下文服务器

MCP上下文服务器是一个高性能的模型上下文协议（MCP）服务器，为大语言模型（LLM）代理提供持久的多模态上下文存储。该服务器基于FastMCP构建，支持通过基于线程的作用域，让多个处理同一任务的代理无缝共享上下文。

✨ 主要特性

• 多模态上下文存储：支持存储和检索文本和图像。
• 基于线程的作用域：处理同一任务的代理可通过线程ID共享上下文。
• 灵活的元数据过滤：可存储具有任何JSON可序列化字段的自定义结构化数据，并使用15种强大的运算符进行过滤。
• 日期范围过滤：使用ISO 8601格式按创建时间戳过滤上下文条目。
• 基于标签的组织：通过规范化、索引化的标签实现高效的上下文检索。
• 全文搜索：可选的语言搜索，支持词干提取、排名和布尔查询（FTS5/tsvector）。
• 语义搜索：可选的向量相似性搜索，用于基于语义的检索。
• 混合搜索：可选的结合全文搜索和语义搜索，使用互反排名融合（RRF）。
• 多数据库后端：可选择SQLite（默认，零配置）或PostgreSQL（高并发，生产级）。
• 高性能：采用WAL模式（SQLite）/MVCC（PostgreSQL）、策略性索引和异步操作。
• 符合MCP标准：可与Claude Code、LangGraph和任何MCP兼容的客户端配合使用。
• 生产就绪：具备全面的测试覆盖、类型安全和强大的错误处理能力。

🚀 快速开始

前提条件

• uv包管理器（安装说明）
• 一个MCP兼容的客户端（Claude Code、LangGraph或任何MCP客户端）

将服务器添加到Claude Code

有两种方法可以将MCP上下文服务器添加到Claude Code：

方法1：使用CLI命令

# 从PyPI安装（推荐）
claude mcp add context-server -- uvx --python 3.12 mcp-context-server

# 从GitHub安装（最新开发版本）
claude mcp add context-server -- uvx --python 3.12 --from git+https://github.com/alex-feel/mcp-context-server mcp-context-server

# 启用语义搜索（设置说明见docs/semantic-search.md）
claude mcp add context-server -- uvx --python 3.12 --with mcp-context-server[semantic-search] mcp-context-server

# 从GitHub安装最新开发版本并启用语义搜索（设置说明见docs/semantic-search.md）
claude mcp add context-server -- uvx --python 3.12 --from git+https://github.com/alex-feel/mcp-context-server --with mcp-context-server[semantic-search] mcp-context-server

更多详细信息，请参阅：https://docs.claude.com/en/docs/claude-code/mcp#option-1%3A-add-a-local-stdio-server

方法2：直接文件配置

在项目目录的.mcp.json文件中添加以下内容：

{
  "mcpServers": {
    "context-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-context-server"],
      "env": {}
    }
  }
}

如果要使用GitHub上的最新开发版本，请使用以下内容：

"args": ["--python", "3.12", "--from", "git+https://github.com/alex-feel/mcp-context-server", "mcp-context-server"]

有关配置文件的位置和详细信息，请参阅：https://docs.claude.com/en/docs/claude-code/settings#settings-files

验证安装

# 启动Claude Code
claude

# 检查MCP工具是否可用
/mcp

📦 安装指南

环境配置

环境变量

您可以在MCP配置中使用环境变量来配置服务器。服务器支持使用${VAR}或${VAR:-default}语法进行环境变量扩展。

以下是一个使用环境变量的配置示例：

{
  "mcpServers": {
    "context-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-context-server"],
      "env": {
        "LOG_LEVEL": "${LOG_LEVEL:-INFO}",
        "DB_PATH": "${DB_PATH:-~/.mcp/context_storage.db}",
        "MAX_IMAGE_SIZE_MB": "${MAX_IMAGE_SIZE_MB:-10}",
        "MAX_TOTAL_SIZE_MB": "${MAX_TOTAL_SIZE_MB:-100}"
      }
    }
  }
}

有关环境变量扩展的更多详细信息，请参阅：https://docs.claude.com/en/docs/claude-code/mcp#environment-variable-expansion-in-mcp-json

支持的环境变量

核心设置：

• STORAGE_BACKEND：数据库后端 - sqlite（默认）或postgresql
• LOG_LEVEL：日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL） - 默认值为ERROR
• DB_PATH：数据库文件位置（仅适用于SQLite） - 默认值为~/.mcp/context_storage.db
• MAX_IMAGE_SIZE_MB：每个图像的最大大小（MB） - 默认值为10
• MAX_TOTAL_SIZE_MB：请求的最大总大小（MB） - 默认值为100

全文搜索设置：

• ENABLE_FTS：启用全文搜索功能（true/false） - 默认值为false
• FTS_LANGUAGE：词干提取和文本搜索的语言 - 默认值为english。PostgreSQL支持29种语言的完整词干提取。SQLite使用english进行Porter词干提取，或使用任何其他值进行unicode61分词器（无词干提取）。

混合搜索设置：

• ENABLE_HYBRID_SEARCH：启用结合全文搜索和语义搜索的混合搜索，使用RRF融合（true/false） - 默认值为false
• HYBRID_RRF_K：RRF平滑常数（1 - 1000） - 默认值为60。值越高，排名处理越均匀。

语义搜索设置：

• ENABLE_SEMANTIC_SEARCH：启用语义搜索功能（true/false） - 默认值为false
• OLLAMA_HOST：用于嵌入生成的Ollama API主机URL - 默认值为http://localhost:11434
• EMBEDDING_MODEL：语义搜索的嵌入模型名称 - 默认值为embeddinggemma:latest
• EMBEDDING_DIM：嵌入向量维度 - 默认值为768。注意：初始设置后更改此值需要进行数据库迁移（请参阅语义搜索指南）

PostgreSQL设置（仅当STORAGE_BACKEND = postgresql时）：

• POSTGRESQL_HOST：PostgreSQL服务器主机 - 默认值为localhost
• POSTGRESQL_PORT：PostgreSQL服务器端口 - 默认值为5432
• POSTGRESQL_USER：PostgreSQL用户名 - 默认值为postgres
• POSTGRESQL_PASSWORD：PostgreSQL密码 - 默认值为postgres
• POSTGRESQL_DATABASE：PostgreSQL数据库名称 - 默认值为mcp_context

高级配置

还有其他环境变量可用于服务器的高级调优，包括：

• 连接池配置
• 重试行为设置
• SQLite性能优化
• 断路器阈值
• 操作超时

有关所有配置选项的完整列表，请参阅app/settings.py。

语义搜索

有关使用Ollama和EmbeddingGemma启用可选语义搜索的详细说明，请参阅语义搜索指南。

Docker部署

对于使用HTTP传输和容器编排的生产部署，提供了SQLite、PostgreSQL和外部PostgreSQL（Supabase）的Docker Compose配置。有关设置说明和客户端连接详细信息，请参阅Docker部署指南。

身份验证

对于需要身份验证的HTTP传输部署，请参阅身份验证指南，了解有关Bearer令牌、Google OAuth和Azure AD的配置选项。

数据库后端

服务器支持多种数据库后端，可通过STORAGE_BACKEND环境变量进行选择。

SQLite（默认）

零配置的本地存储，非常适合单用户部署。

• 特性：
  • 无需安装，开箱即用。
  • 生产级连接池和写入队列。
  • WAL模式，提高并发性能。
  • 适用于单用户和中等工作负载。
• 配置：无需配置，直接启动服务器即可！

PostgreSQL

适用于多用户和高流量部署的高性能后端。

• 特性：
  • 与SQLite相比，写入吞吐量提高10倍以上，通过MVCC实现。
  • 原生支持并发写入。
  • JSONB索引，实现快速元数据查询。
  • 使用asyncpg的生产级连接池。
  • 支持pgvector扩展，用于语义搜索。
• 使用Docker快速启动： 运行带有pgvector的PostgreSQL非常简单，只需2个命令：

# 1. 拉取并运行带有pgvector的PostgreSQL（一体化）
docker run --name pgvector18 \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=mcp_context \
  -p 5432:5432 \
  -d pgvector/pgvector:pg18-trixie

# 2. 配置服务器（最小化设置 - 仅需2个变量）
export STORAGE_BACKEND=postgresql
export ENABLE_SEMANTIC_SEARCH=true  # 可选：仅在需要语义搜索时设置

就是这样！ 服务器将自动：

• 在启动时连接到PostgreSQL。

• 初始化模式（创建表和索引）。

• 启用pgvector扩展（Docker镜像中已预安装）。

• 如果启用了语义搜索，则应用迁移。

• 在.mcp.json中配置：

{
  "mcpServers": {
    "context-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-context-server"],
      "env": {
        "STORAGE_BACKEND": "postgresql",
        "POSTGRESQL_HOST": "localhost",
        "POSTGRESQL_USER": "postgres",
        "POSTGRESQL_PASSWORD": "postgres",
        "POSTGRESQL_DATABASE": "mcp_context",
        "ENABLE_SEMANTIC_SEARCH": "true"
      }
    }
  }
}

注意：仅在使用PostgreSQL时需要设置PostgreSQL相关设置。如果未设置STORAGE_BACKEND，服务器默认使用SQLite。

与Supabase一起使用

Supabase通过直接数据库连接与PostgreSQL后端完全兼容，无需特殊配置 - Supabase就是PostgreSQL。

连接方法

Supabase提供两种连接方法，可根据网络能力选择：

1. 直接连接（需要IPv6，延迟最低）
2. 会话池（支持IPv4，通用）

连接方法1：直接连接（推荐）

适用于：支持IPv6的虚拟机、服务器和本地开发。

• 要求：
  • IPv6连接（或付费专用IPv4附加组件）
  • 端口5432可访问
  • 最低延迟（~15 - 20ms）
• 快速设置：
  1. 获取数据库连接详细信息： 导航到您的Supabase仪表板：
     • 转到Database → Settings（左侧边栏 → Database → Settings）
     • 找到**"Connect to your project"**部分
     • 选择**"Connection String"选项卡，然后选择"Direct connection"**方法
     • 您将看到：postgresql://postgres:[YOUR_PASSWORD]@db.[PROJECT_REF].supabase.co:5432/postgres
  2. 获取或重置数据库密码： 重要：出于安全原因，您的数据库密码不会在Supabase仪表板中显示。 您必须使用以下方法之一：
     • 使用创建Supabase项目时设置的密码，或者
     • 点击"Reset database password"（连接字符串下方）生成新密码 注意：将连接字符串中的[YOUR_PASSWORD]替换为您的实际数据库密码（不是API密钥 - API密钥用于REST/GraphQL API）。
  3. 配置连接： 在您的.mcp.json中添加实际密码：

     {
       "mcpServers": {
         "context-server": {
           "type": "stdio",
           "command": "uvx",
           "args": ["--python", "3.12", "mcp-context-server"],
           "env": {
             "STORAGE_BACKEND": "postgresql",
             "POSTGRESQL_CONNECTION_STRING": "postgresql://postgres:your-actual-password@db.[PROJECT_REF].supabase.co:5432/postgres"
           }
         }
       }
     }
     

     或者使用单独的环境变量：

     {
       "mcpServers": {
         "context-server": {
           "type": "stdio",
           "command": "uvx",
           "args": ["--python", "3.12", "mcp-context-server"],
           "env": {
             "STORAGE_BACKEND": "postgresql",
             "POSTGRESQL_HOST": "db.[PROJECT_REF].supabase.co",
             "POSTGRESQL_PORT": "5432",
             "POSTGRESQL_USER": "postgres",
             "POSTGRESQL_PASSWORD": "your-actual-password",
             "POSTGRESQL_DATABASE": "postgres",
             "ENABLE_SEMANTIC_SEARCH": "true"
           }
         }
       }
     }
     

     替换[PROJECT_REF]为您的实际项目参考ID，your-actual-password为您的数据库密码。

连接方法2：会话池（支持IPv4）

适用于：不支持IPv6的系统（Windows、企业网络、受限环境）。

• 要求：
  • IPv4连接（通用）
  • 端口5432可访问
  • 稍高的延迟（~20 - 30ms，比直接连接高5 - 10ms）
• 与直接连接的重要区别：
  • 不同的主机名：使用*.pooler.supabase.com（不是db.*.supabase.co）
  • 不同的用户名格式：postgres.[PROJECT-REF]（包含项目参考）
  • 相同的端口：5432（不是6543 - 6543是无服务器事务池的端口）
  • 支持IPv4：无需IPv6配置，适用于所有系统
• 快速设置：
  1. 获取会话池连接字符串： 导航到您的Supabase仪表板：
     • 转到Database → Settings（左侧边栏 → Database → Settings）
     • 找到**"Connect to your project"**部分
     • 选择**"Connection String"选项卡，然后选择"Session pooler"**方法（不是"Transaction pooler"）
     • 您将看到：postgresql://postgres.[PROJECT-REF]:[YOUR_PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres 示例：

     postgresql://postgres.abcdefghijklmno:your-password@aws-0-us-east-1.pooler.supabase.com:5432/postgres
     

  2. 获取或重置数据库密码（与直接连接相同 - 见上文）
  3. 配置连接： 在您的.mcp.json中添加：

     {
       "mcpServers": {
         "context-server": {
           "type": "stdio",
           "command": "uvx",
           "args": ["--python", "3.12", "mcp-context-server"],
           "env": {
             "STORAGE_BACKEND": "postgresql",
             "POSTGRESQL_CONNECTION_STRING": "postgresql://postgres.[PROJECT-REF]:your-actual-password@aws-0-[REGION].pooler.supabase.com:5432/postgres"
           }
         }
       }
     }
     

     或者使用单独的环境变量：

     {
       "mcpServers": {
         "context-server": {
           "type": "stdio",
           "command": "uvx",
           "args": ["--python", "3.12", "mcp-context-server"],
           "env": {
             "STORAGE_BACKEND": "postgresql",
             "POSTGRESQL_HOST": "aws-0-[REGION].pooler.supabase.com",
             "POSTGRESQL_PORT": "5432",
             "POSTGRESQL_USER": "postgres.[PROJECT-REF]",
             "POSTGRESQL_PASSWORD": "your-actual-password",
             "POSTGRESQL_DATABASE": "postgres",
             "ENABLE_SEMANTIC_SEARCH": "true"
           }
         }
       }
     }
     

     替换[PROJECT-REF]为您的实际项目参考，[REGION]为您的项目区域（例如，us-east-1），your-actual-password为您的数据库密码。

应该使用哪种连接方法？

建议：

• 首先尝试直接连接 - 更简单、更快
• 如果出现"getaddrinfo failed"错误，请切换到会话池（表示IPv6连接问题）

故障排除

"getaddrinfo failed"错误： 如果在直接连接时看到此错误：

Error: getaddrinfo ENOTFOUND db.[PROJECT-REF].supabase.co

解决方案：您的系统不支持IPv6或已禁用。请改用会话池（上述方法2）。 原因：直接连接（db.*.supabase.co）默认使用IPv6。会话池（*.pooler.supabase.com）通过Supavisor代理提供IPv4兼容性。

启用语义搜索（pgvector扩展）： 如果您想在Supabase上使用语义搜索，必须启用pgvector扩展：

1. 通过Supabase仪表板（最简单的方法）：
   • 导航到Database → Extensions（左侧边栏）
   • 在扩展列表中搜索"vector"
   • 找到"vector"扩展（版本0.8.0+）
   • 点击切换开关启用它（启用后变为绿色）
2. 通过SQL编辑器（替代方法）：
   • 导航到Supabase仪表板中的SQL Editor
   • 运行：CREATE EXTENSION IF NOT EXISTS vector;
   • 验证：SELECT * FROM pg_extension WHERE extname = 'vector';
3. 配置环境：

   {
     "mcpServers": {
       "context-server": {
         "type": "stdio",
         "command": "uvx",
         "args": ["--python", "3.12", "mcp-context-server"],
         "env": {
           "STORAGE_BACKEND": "postgresql",
           "POSTGRESQL_CONNECTION_STRING": "postgresql://postgres:your-actual-password@db.[PROJECT_REF].supabase.co:5432/postgres",
           "ENABLE_SEMANTIC_SEARCH": "true"
         }
       }
     }
   }
   

注意：所有Supabase项目都提供pgvector扩展，但必须手动启用。服务器在首次运行时将自动创建必要的向量列和索引。

为什么选择直接连接？

• Supabase推荐用于后端服务和服务器端应用程序
• 完整的PostgreSQL功能：pgvector（可用，必须启用）、JSONB、事务、所有扩展
• 更好的性能：比REST API延迟更低，原生连接池
• 生产就绪：MVCC支持并发写入，使用asyncpg的连接池
• 无需特殊代码：使用标准PostgreSQL后端 - 无需特定于Supabase的实现

重要注意事项：

• ✅ 使用数据库密码：从Settings → Database部分获取
• ❌ 不要使用API密钥：API密钥（包括旧版service_role密钥）用于REST/GraphQL API，不是直接数据库连接
• ✅ 使用端口5432：用于直接连接（推荐用于后端服务）
• ✅ pgvector扩展：所有Supabase项目都可用 - 通过Dashboard → Extensions启用，用于语义搜索
• ✅ 所有PostgreSQL功能：相同工作方式 - JSONB索引、元数据过滤、事务

安全最佳实践：

• 将数据库密码存储在环境变量中，而不是代码中
• 使用Supabase的连接字符串格式，简化配置
• 默认启用SSL/TLS（由Supabase连接自动处理）
• 如果您的用例只需要读访问，考虑使用只读凭据

📚 详细文档

API参考

工具

store_context

存储一个上下文条目，可包含可选的图像和灵活的元数据。

• 参数：
  • thread_id（str，必需）：对话/任务线程的唯一标识符
  • source（str，必需）：可以是'user'或'agent'
  • text（str，必需）：要存储的文本内容
  • images（list，可选）：包含mime_type的Base64编码图像
  • metadata（dict，可选）：额外的结构化数据 - 完全灵活的JSON对象，可根据您的用例使用
  • tags（list，可选）：用于组织的标签（自动规范化）
• 元数据灵活性： 元数据字段接受任何JSON可序列化的结构，使服务器能够适应各种用例：
  • 任务管理：存储status、priority、assignee、due_date、completed
  • 代理协调：跟踪agent_name、task_name、execution_time、resource_usage
  • 知识库：包含category、relevance_score、source_url、author
  • 调试上下文：保存error_type、stack_trace、environment、version
  • 分析：记录user_id、session_id、event_type、timestamp
• 性能注意事项：以下元数据字段已建立索引，以加快过滤速度：
  • status：状态信息（例如，'pending'、'active'、'completed'）
  • priority：用于范围查询的数值
  • agent_name：特定代理标识符
  • task_name：用于字符串搜索的任务标题
  • completed：完成状态的布尔标志
• 返回值：包含成功状态和context_id的字典

search_context

使用强大的过滤功能搜索上下文条目，包括元数据查询和日期范围。

• 参数：
  • thread_id（str，可选）：按线程过滤
  • source（str，可选）：按来源过滤（'user'或'agent'）
  • tags（list，可选）：按标签过滤（OR逻辑）
  • content_type（str，可选）：按类型过滤（'text'或'multimodal'）
  • metadata（dict，可选）：简单的元数据过滤（键值相等）
  • metadata_filters（list，可选）：使用运算符的高级元数据过滤
  • start_date（str，可选）：过滤在此日期或之后创建的条目（ISO 8601格式）
  • end_date（str，可选）：过滤在此日期或之前创建的条目（ISO 8601格式）
  • limit（int，可选）：返回的最大结果数（1 - 100，默认值：30）
  • offset（int，可选）：分页偏移量（默认值：0）
  • include_images（bool，可选）：在响应中包含图像数据
  • explain_query（bool，可选）：包含查询执行统计信息
• 元数据过滤：支持简单的键值相等和使用15种运算符的高级过滤。请参阅元数据指南。
• 日期过滤：支持ISO 8601日期过滤。请参阅本文档末尾的部分。
• 返回值：包含匹配上下文条目的列表，可选包含查询统计信息

get_context_by_ids

按ID获取特定的上下文条目。

• 参数：
  • context_ids（list，必需）：上下文条目ID列表
  • include_images（bool，可选）：包含图像数据（默认值：True）
• 返回值：包含完整内容的上下文条目列表

delete_context

按ID或线程删除上下文条目。

• 参数：
  • context_ids（list，可选）：要删除的特定ID
  • thread_id（str，可选）：删除线程中的所有条目
• 返回值：包含删除计数的字典

list_threads

列出所有活动线程并提供统计信息。

• 返回值：包含以下内容的字典：
  • 包含条目计数的线程列表
  • 来源类型分布
  • 多模态内容计数
  • 时间戳范围

get_statistics

获取数据库统计信息和使用指标。

• 返回值：包含以下内容的字典：
  • 总条目计数
  • 按来源和内容类型的细分
  • 总图像计数
  • 唯一标签计数
  • 数据库大小（MB）

update_context

更新现有上下文条目的特定字段。

• 参数：
  • context_id（int，必需）：要更新的上下文条目的ID
  • text（str，可选）：新的文本内容
  • metadata（dict，可选）：新的元数据（完全替换）
  • metadata_patch（dict，可选）：使用RFC 7396 JSON Merge Patch进行部分元数据更新
  • tags（list，可选）：新的标签（完全替换）
  • images（list，可选）：新的图像（完全替换）
• 元数据更新选项： 使用metadata进行完全替换，或使用metadata_patch进行部分更新。这些参数互斥。 RFC 7396 JSON Merge Patch语义（metadata_patch）：
  • 新键将添加到现有元数据中
  • 现有键将被新值替换
  • 空值将删除键

# 更新单个字段，保留其他字段
update_context(context_id=123, metadata_patch={"status": "completed"})

# 添加新字段并删除另一个字段
update_context(context_id=123, metadata_patch={"reviewer": "alice", "draft": None})

• 限制（RFC 7396）：空值不能存储（空值表示删除键 - 如果需要，请使用完全替换），数组将被完全替换（不合并）。请参阅元数据指南了解详细信息。
• 字段更新规则：
  • 可更新字段：text_content、metadata、tags、images
  • 不可变字段：id、thread_id、source、created_at（为保证数据完整性保留）
  • 自动管理字段：content_type（根据图像存在情况重新计算）、updated_at（设置为当前时间戳）
• 更新行为：
  • 仅更新提供的字段（选择性更新）
  • 标签和图像使用完全替换语义，以保持一致性
  • 内容类型根据图像存在情况自动在'text'和'multimodal'之间切换
  • 必须提供至少一个可更新字段
• 返回值：包含以下内容的字典：
  • 成功状态
  • 上下文ID
  • 更新字段列表
  • 成功/错误消息

semantic_search_context

使用向量嵌入执行语义相似性搜索。 注意：仅当通过ENABLE_SEMANTIC_SEARCH=true启用语义搜索且所有依赖项都已安装时，此工具才可用。实现因后端而异：

• SQLite：使用sqlite-vec扩展和通过Ollama的嵌入模型
• PostgreSQL：使用pgvector扩展（pgvector Docker镜像中预安装）和通过Ollama的嵌入模型
• 参数：
  • query（str，必需）：自然语言搜索查询
  • limit（int，可选）：返回的最大结果数（1 - 100，默认值：5）
  • offset（int，可选）：分页偏移量（默认值：0）
  • thread_id（str，可选）：可选的按线程过滤
  • source（str，可选）：按来源类型过滤（'user'或'agent'）
  • tags（list，可选）：按任何这些标签过滤（OR逻辑）
  • content_type（str，可选）：按内容类型过滤（'text'或'multimodal'）
  • start_date（str，可选）：过滤在此日期或之后创建的条目（ISO 8601格式）
  • end_date（str，可选）：过滤在此日期或之前创建的条目（ISO 8601格式）
  • metadata（dict，可选）：简单的元数据过滤（键值相等）
  • metadata_filters（list，可选）：使用运算符的高级元数据过滤
  • include_images（bool，可选）：在结果中包含图像数据（默认值：false）
  • explain_query（bool，可选）：包含查询执行统计信息（默认值：false）
• 元数据过滤：支持与search_context相同的过滤语法。请参阅元数据指南。
• 返回值：包含以下内容的字典：
  • 查询字符串
  • 包含相似性分数的语义相似上下文条目列表
  • 结果计数
  • 用于嵌入的模型名称
  • 查询执行统计信息（仅当explain_query = True时）
• 用例：
  • 根据语义相似性在不同线程中查找相关工作
  • 发现含义相似但措辞不同的上下文
  • 基于概念的检索，无需精确关键字匹配
  • 使用日期过滤器在特定时间段内查找相似内容
• 日期过滤示例：

# 查找过去一周内的相似内容
semantic_search_context(
    query="authentication implementation",
    start_date="2025-11-22",
    end_date="2025-11-29"
)

有关设置说明，请参阅语义搜索指南。

fts_search_context

执行全文搜索，支持语言处理、相关性排名和高亮片段。 注意：仅当通过ENABLE_FTS=true启用全文搜索时，此工具才可用。实现因后端而异：

• SQLite：使用FTS5和BM25排名。Porter词干提取器（英语）或unicode61分词器（多语言）。
• PostgreSQL：使用tsvector/tsquery和ts_rank排名。支持29种语言的完整词干提取。
• 参数：
  • query（str，必需）：搜索查询
  • mode（str，可选）：搜索模式 - match（默认）、prefix、phrase或boolean
  • limit（int，可选）：返回的最大结果数（1 - 100，默认值：5）
  • offset（int，可选）：分页偏移量（默认值：0）
  • thread_id（str，可选）：可选的按线程过滤
  • source（str，可选）：按来源类型过滤（'user'或'agent'）
  • tags（list，可选）：按任何这些标签过滤（OR逻辑）
  • content_type（str，可选）：按内容类型过滤（'text'或'multimodal'）
  • start_date（str，可选）：过滤在此日期或之后创建的条目（ISO 8601格式）
  • end_date（str，可选）：过滤在此日期或之前创建的条目（ISO 8601格式）
  • metadata（dict，可选）：简单的元数据过滤（键值相等）
  • metadata_filters（list，可选）：使用运算符的高级元数据过滤
  • highlight（bool，可选）：在结果中包含高亮片段（默认值：false）
  • include_images（bool，可选）：在结果中包含图像数据（默认值：false）
  • explain_query（bool，可选）：包含查询执行统计信息（默认值：false）
• 搜索模式：
  • match：标准单词匹配，支持词干提取（默认）
  • prefix：前缀匹配，用于自动完成式搜索
  • phrase：精确短语匹配，保留单词顺序
  • boolean：布尔运算符（AND、OR、NOT），用于复杂查询
• 元数据过滤：支持与search_context相同的过滤语法。请参阅元数据指南。
• 返回值：包含以下内容的字典：
  • 查询字符串和搜索模式
  • 包含相关性分数和高亮片段的匹配条目列表
  • 结果计数
  • 全文搜索可用性状态
• 示例：

# 使用前缀匹配进行搜索
fts_search_context(
    query="auth",
    mode="prefix",
    thread_id="project-123"
)

# 使用元数据过滤进行布尔搜索
fts_search_context(
    query="authentication AND security",
    mode="boolean",
    metadata_filters=[{"key": "status", "operator": "eq", "value": "active"}]
)

hybrid_search_context

执行混合搜索，结合全文搜索和语义搜索，使用互反排名融合（RRF）。 注意：仅当通过ENABLE_HYBRID_SEARCH=true启用混合搜索，并且至少启用了全文搜索（ENABLE_FTS=true）或语义搜索（ENABLE_SEMANTIC_SEARCH=true）之一时，此工具才可用。RRF算法结合了可用搜索方法的结果，提升在两种搜索结果中都出现的文档的排名。

• 参数：
  • query（str，必需）：自然语言搜索查询
  • limit（int，可选）：返回的最大结果数（1 - 100，默认值：5）
  • offset（int，可选）：分页偏移量（默认值：0）
  • search_modes（list，可选）：使用的搜索模式 - ['fts', 'semantic']（默认：两者都用）
  • fusion_method（str，可选）：融合算法 - 'rrf'（默认）
  • rrf_k（int，可选）：RRF平滑常数（1 - 1000，默认值来自HYBRID_RRF_K环境变量）
  • thread_id（str，可选）：可选的按线程过滤
  • source（str，可选）：按来源类型过滤（'user'或'agent'）
  • tags（list，可选）：按任何这些标签过滤（OR逻辑）
  • content_type（str，可选）：按内容类型过滤（'text'或'multimodal'）
  • start_date（str，可选）：过滤在此日期或之后创建的条目（ISO 8601格式）
  • end_date（str，可选）：过滤在此日期或之前创建的条目（ISO 8601格式）
  • metadata（dict，可选）：简单的元数据过滤（键值相等）
  • metadata_filters（list，可选）：使用运算符的高级元数据过滤
  • include_images（bool，可选）：在结果中包含图像数据（默认值：false）
  • explain_query（bool，可选）：包含查询执行统计信息（默认值：false）
• 元数据过滤：支持与search_context相同的过滤语法。请参阅元数据指南。
• 返回值：包含以下内容的字典：
  • 查询字符串和融合方法
  • 包含组合RRF分数和单个搜索排名的匹配条目列表
  • 结果计数和每个搜索方法的计数
  • 实际使用的搜索模式列表
  • 查询执行统计信息（仅当explain_query = True时）
• 分数分解： 每个结果包含一个scores对象，其中包含：
  • rrf：组合的RRF分数（越高越好）
  • fts_rank：在全文搜索结果中的位置（基于1），如果不在全文搜索结果中则为null
  • semantic_rank：在语义搜索结果中的位置（基于1），如果不在语义搜索结果中则为null
  • fts_score：原始全文搜索相关性分数（BM25/ts_rank）
  • semantic_distance：原始语义距离（L2，越低越相似）
• 优雅降级：
  • 如果仅全文搜索可用，则仅返回全文搜索结果
  • 如果仅语义搜索可用，则仅返回语义搜索结果
  • 如果两者都不可用，则抛出错误
• 示例：

# 完整的混合搜索
hybrid_search_context(
    query="authentication implementation",
    thread_id="project-123"
)

# 带有元数据过滤的混合搜索
hybrid_search_context(
    query="performance optimization",
    metadata={"status": "completed"},
    metadata_filters=[{"key": "priority", "operator": "gte", "value": 7}]
)

# 通过混合API使用单模式搜索（保持接口一致）
hybrid_search_context(
    query="exact phrase",
    search_modes=["fts"]
)

有关详细配置和故障排除，请参阅混合搜索指南。

搜索工具响应结构

所有搜索工具返回一致的响应结构，包含公共字段和特定于工具的附加字段：

条目字段按工具划分

注意：

• 仅当explain_query = true时，所有搜索工具才包含stats字段。
• search_context返回截断的文本，用于浏览；使用get_context_by_ids获取完整内容。
• 较低的distance值表示较高的语义相似性。
• 较高的score值表示更好的全文搜索相关性。

批量操作

store_context_batch

在单个批量操作中存储多个上下文条目。

• 参数：
  • entries（list，必需）：上下文条目列表（最多100个）。每个条目包含：
    • thread_id（str，必需），source（str，必需），text（str，必需）
    • metadata（dict，可选），tags（list，可选），images（list，可选）
  • atomic（bool，可选）：如果为true，所有操作要么全部成功，要么全部失败（默认：true）
• 返回值：包含成功、总数、成功数、失败数、结果数组和消息的字典

update_context_batch

在单个批量操作中更新多个上下文条目。

• 参数：
  • updates（list，必需）：更新操作列表（最多100个）。每个更新包含：
    • context_id（int，必需）
    • text（str，可选），metadata（dict，可选），metadata_patch（dict，可选）
    • tags（list，可选），images（list，可选）
  • atomic（bool，可选）：如果为true，所有操作要么全部成功，要么全部失败（默认：true） 注意：metadata_patch使用RFC 7396 JSON Merge Patch语义。请参阅元数据指南了解详细信息。
• 返回值：包含成功、总数、成功数、失败数、结果数组和消息的字典

delete_context_batch

根据各种条件删除多个上下文条目。不可逆。

• 参数：
  • context_ids（list，可选）：要删除的特定上下文ID
  • thread_ids（list，可选）：删除这些线程中的所有条目
  • source（str，可选）：按来源过滤（'user'或'agent'） - 必须与另一个条件结合使用
  • older_than_days（int，可选）：删除早于N天的条目 至少提供一个条件。级联删除将移除关联的标签、图像和嵌入。
• 返回值：包含成功、删除计数、使用的条件和消息的字典

过滤参考

以下过滤选项适用于search_context、semantic_search_context、fts_search_context和hybrid_search_context工具。

元数据过滤

• 简单过滤（精确匹配）：

metadata={'status': 'active', 'priority': 5}

• 高级过滤，使用运算符：

metadata_filters=[
    {'key': 'priority', 'operator': 'gt', 'value': 3},
    {'key': 'status', 'operator': 'in', 'value': ['active', 'pending']},
    {'key': 'agent_name', 'operator': 'starts_with', 'value': 'gpt'},
    {'key': 'completed', 'operator': 'eq', 'value': False}
]

• 支持的运算符：
  • eq：等于（默认情况下，字符串不区分大小写）
  • ne：不等于
  • gt, gte, lt, lte：数值比较
  • in, not_in：列表成员关系
  • exists, not_exists：字段存在性
  • contains, starts_with, ends_with：字符串操作
  • is_null, is_not_null：空值检查 所有字符串运算符支持case_sensitive: true/false选项。 有关元数据过滤的全面文档，包括实际用例、运算符示例、嵌套JSON路径和性能优化，请参阅元数据指南。

日期过滤

使用ISO 8601格式按创建时间戳过滤条目：

# 查找特定日期的条目
search_context(thread_id="project-123", start_date="2025-11-29", end_date="2025-11-29")

# 查找日期范围内的条目
search_context(thread_id="project-123", start_date="2025-11-01", end_date="2025-11-30")

# 查找精确时间戳的条目
search_context(thread_id="project-123", start_date="2025-11-29T10:00:00")

支持的ISO 8601格式：

• 仅日期：2025-11-29
• 日期时间：2025-11-29T10:00:00
• UTC（Z后缀）：2025-11-29T10:00:00Z
• 时区偏移：2025-11-29T10:00:00+02:00

注意：仅日期的end_date值会自动扩展到当天结束（T23:59:59.999999），以实现直观的"一整天"行为。朴素的日期时间（没有时区）被解释为UTC。

📄 许可证

本项目采用GitHub License许可协议。