Typesense MCP Server

🚀 Tacitbase MCP 服務器

Tacitbase MCP 服務器為 Tacitbase 提供高級搜索功能，支持 Tacitbase 原生搜索與 Typesense 增強搜索特性，能有效提升搜索效率與精準度。

🚀 快速開始

安裝

1. 下載依賴：

go mod download

2. 構建服務器：

go build -o tb-mcp-server

3. 運行服務器：

./tb-mcp-server

配置環境變量

• TACITBASE_AUTH_TOKEN: Tacitbase API 的身份驗證令牌
• TYPESENSE_API_KEY: Typesense 的 API 密鑰
• TYPESENSE_HOST (默認: localhost): Typesense 服務的主機地址
• TYPESENSE_PORT (默認: 8108): Typesense 服務的端口
• TYPESENSE_PROTOCOL (默認: http): Typesense 服務的協議

✨ 主要特性

• 基於關鍵詞的基本搜索，支持過濾、排序和分組
• 使用向量嵌入進行相似性匹配的向量搜索
• 具備自然語言理解能力的語義搜索
• 需要時回退到 Tacitbase 的原生搜索
• 工具註冊以搜索候選人

📦 安裝指南

下載依賴

go mod download

構建服務器

go build -o tb-mcp-server

運行服務器

./tb-mcp-server

💻 使用示例

基礎用法

基本搜索

{
  "query": "golang 開發者",
  "search_fields": "技能,最新經驗",
  "filter_fields": "地點:舊金山",
  "sort_by": "最新經驗:降序",
  "page": 1,
  "per_page": 20
}

向量搜索

{
  "vector_query": "[0.1, 0.2, ..., 0.512]",
  "filter_fields": "工作經驗:>5",
  "page": 1,
  "per_page": 20
}

語義搜索

{
  "query": "具備團隊領導經驗且熟悉雲技術的候選人",
  "search_fields": "技能,經驗,教育背景",
  "filter_fields": "地點:北京, 年齡範圍:28-35",
  "sort_by": "相關性:降序",
  "page": 1,
  "per_page": 20
}

高級用法

基本搜索實現

package main

import (
	"encoding/json"
	"fmt"
	"net/http"

	"github.com/gin-gonic/gin"
)

type SearchRequest struct {
	Query       string      `json:"query"`
	SearchFields []string    `json:"search_fields"`
	FilterFields map[string]string `json:"filter_fields"`
	SortBy      string      `json:"sort_by"`
	Page        int         `json:"page"`
	PerPage     int         `json:"per_page"`
}

func main() {
	r := gin.DefaultRouter()

	r.POST("/search", func(c *gin.Context) {
		var req SearchRequest
		if err := c.ShouldBindJSON(&req); err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": "請求格式錯誤"})
			return
		}

		// 模擬搜索邏輯
		results := search(req.Query, req.SearchFields, req.FilterFields)
		
		c.JSON(http.StatusOK, gin.H{
			"results": results,
			"page":    req.Page,
			"per_page": req.PerPage,
		})
	})

	r.Run(":8080")
}

func search(query string, fields []string, filters map[string]string) []map[string]interface{} {
	// 模擬搜索結果
	return []map[string]interface{}{
		{
			"id":    1,
			"title": "Golang 開發工程師",
			"company": "示例公司",
		},
		{
			"id":    2,
			"title": "高級 Golang 開發者",
			"company": "另一家公司",
		},
	}
}

向量搜索實現

package main

import (
	"fmt"
	"math"

	"github.com/gocarina/goshark"
)

func vectorSearch(embeddings []float64, queryEmbedding []float64) []int {
	// 計算餘弦相似度
	similarities := make([]float64, len(embeddings))
	for i, vec := range embeddings {
		dotProduct := 0.0
		for j := 0; j < len(vec); j++ {
			dotProduct += vec[j] * queryEmbedding[j]
		}
		norm := math.Sqrt(float64(len(queryEmbedding))) * math.Sqrt(float64(len(embeddings[i])))
		if norm == 0 {
			similarities[i] = 0
		} else {
			similarities[i] = dotProduct / norm
		}
	}

	// 根據相似度排序
	order := make(sort.IntSlice, len(similarities))
	for i := range order {
		order[i] = i
	}
	order.Sort(func(i, j int) bool {
		return similarities[i] > similarities[j]
	})

	return order.Indizes()
}

📚 詳細文檔

項目結構

該項目採用乾淨、模塊化的架構：

.
├── 模型/      # 數據結構和類型
├── 服務/    # 商業邏輯和外部服務交互
├── 處理器/   # 請求處理器和路由邏輯
├── 工具/     # 工具註冊和配置
├── main.go      # 應用程序入口點
└── README.md    # 項目文檔

包

• models: 包含應用程序中使用的數據結構和類型
• services: 實現商業邏輯和外部服務交互
• handlers: 包含處理傳入請求的請求處理器
• tools: 註冊可用於搜索候選人的工具

搜索工具

1. 基本搜索 (search_candidates)

• 支持關鍵詞打字錯誤容忍度的基於關鍵詞搜索
• 支持字段特定搜索
• 支持過濾、排序和分組功能
• 允許精確匹配選項

2. 向量搜索 (vector_search_candidates)

• 使用向量嵌入進行相似性搜索
• 適合用於查找具有類似配置文件的候選人
• 支持結合過濾器使用的混合搜索

3. 語義搜索 (semantic_search_candidates)

• 具備自然語言理解能力
• 自動生成嵌入表示
• 支持多種嵌入模型（OpenAI、SBERT、E5）
• 結合語義理解和過濾器的混合搜索

開發

項目初始化

使用 Go 模塊管理的項目，可以通過以下命令初始化：

go mod init your_project_name
go mod tidy

運行測試

運行項目中的測試用例：

go test -v ./...

接口文檔

API 文檔可以通過以下工具生成：

• Go Swagger
• Gin 的路由分組

項目貢獻

歡迎為該項目貢獻力量！請參考 CONTRIBUTING.md 文件瞭解如何參與。

📄 許可證

本項目遵循 MIT 協議。