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為您的數據庫密碼。

應該使用哪種連接方法？

考慮因素	直接連接	會話池
需要IPv6	是（或付費IPv4附加組件）	否 - 支持IPv4
延遲	最低（~15 - 20ms）	增加5 - 10ms開銷
與Windows兼容	可能需要IPv6配置	通用
企業網絡	可能被阻止	通常可用
配置	更簡單（標準PostgreSQL）	需要正確的主機名
最適合	支持IPv6的虛擬機、服務器	Windows、受限網絡

建議：

• 首先嚐試直接連接 - 更簡單、更快
• 如果出現"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"]
)

有關詳細配置和故障排除，請參閱混合搜索指南。

搜索工具響應結構

所有搜索工具返回一致的響應結構，包含公共字段和特定於工具的附加字段：

字段	search_context	semantic_search_context	fts_search_context	hybrid_search_context
results	條目列表	條目列表	條目列表	條目列表
count	是	是	是	是
query	否	是	是	是
stats	explain_query = true	explain_query = true	explain_query = true	explain_query = true
model	否	是（嵌入模型）	否	否
mode	否	否	是（搜索模式）	否
language	否	否	是（全文搜索語言）	否
fusion_method	否	否	否	是
search_modes_used	否	否	否	是
fts_count	否	否	否	是
semantic_count	否	否	否	是

條目字段按工具劃分

條目字段	search_context	semantic_search_context	fts_search_context	hybrid_search_context
id, thread_id, source, content_type	是	是	是	是
text_content	截斷（150個字符）	完整	完整	完整
is_truncated	是	否	否	否
metadata, tags, created_at, updated_at	是	是	是	是
images	include_images = true	include_images = true	include_images = true	include_images = true
distance	否	是（L2距離）	否	否
score	否	否	是（相關性）	否
highlighted	否	否	highlight = true	否
scores（rrf, fts_rank, semantic_rank等）	否	否	否	是

注意：

• 僅當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許可協議。