Typesense MCP Server

🚀 Tacitbase MCP 服务器

Tacitbase MCP 服务器为 Tacitbase 提供高级搜索功能，支持 Tacitbase 原生搜索和 Typesense 增强搜索特性，极大提升搜索的灵活性和效率。

🚀 快速开始

Tacitbase MCP 服务器为 Tacitbase 带来高级搜索能力，支持 Tacitbase 原生搜索和 Typesense 增强搜索特性。你可以按以下步骤安装和运行该服务器：

1. 下载依赖：

go mod download

2. 构建服务器：

go build -o tb-mcp-server

3. 运行服务器：

./tb-mcp-server

✨ 主要特性

• 多样化搜索功能：支持基于关键词的基本搜索、使用向量嵌入的相似性匹配向量搜索以及具备自然语言理解能力的语义搜索。
• 灵活回退机制：在需要时可回退到 Tacitbase 的原生搜索。
• 工具注册功能：支持工具注册以搜索候选人。

📦 安装指南

环境变量配置

在运行服务器前，需要配置以下环境变量：

• TACITBASE_AUTH_TOKEN：Tacitbase API 的身份验证令牌
• TYPESENSE_API_KEY：Typesense 的 API 密钥
• TYPESENSE_HOST (默认: localhost)：Typesense 服务的主机地址
• TYPESENSE_PORT (默认: 8108)：Typesense 服务的端口
• TYPESENSE_PROTOCOL (默认: http)：Typesense 服务的协议

安装步骤

1. 下载依赖：

go mod download

2. 构建服务器：

go build -o tb-mcp-server

3. 运行服务器：

./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
}

📚 详细文档

项目结构

该项目采用干净、模块化的架构：

.
├── 模型/      # 数据结构和类型
├── 服务/    # 商业逻辑和外部服务交互
├── 处理器/   # 请求处理器和路由逻辑
├── 工具/     # 工具注册和配置
├── 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 的路由分组

代码示例

基本搜索实现

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()
}

🔧 技术细节

该项目采用模块化架构，将不同功能模块分离，提高代码的可维护性和可扩展性。各模块职责明确，如 models 负责数据结构和类型定义，services 处理商业逻辑和外部服务交互等。同时，项目支持多种搜索方式，包括基本搜索、向量搜索和语义搜索，每种搜索方式都有其独特的实现逻辑。

📄 许可证

本项目遵循 MIT 协议。

项目贡献

欢迎为该项目贡献力量！请参考 CONTRIBUTING.md 文件了解如何参与。