🚀 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 协议。