Typesense MCP Server

🚀 Tacitbase MCP Server

This is a Machine Comprehension Protocol (MCP) server that provides advanced search capabilities for Tacitbase. It supports both Tacitbase's native search and enhanced search features of Typesense.

📁 Project Structure

The project adopts a clean and modular architecture:

.
├── models/      # Data structures and types
├── services/    # Business logic and interaction with external services
├── handlers/    # Request handlers and routing logic
├── tools/       # Tool registration and configuration
├── main.go      # Application entry point
└── README.md    # Project documentation

📦 Packages

• models: Contains data structures and types used in the application.
• services: Implements business logic and interaction with external services.
• handlers: Contains request handlers for incoming requests.
• tools: Registers tools for searching candidates.

✨ Features

• Basic keyword-based search with support for filtering, sorting, and grouping.
• Vector search using vector embeddings for similarity matching.
• Semantic search with natural language understanding capabilities.
• Fallback to Tacitbase's native search when necessary.
• Tool registration for searching candidates.

🔍 Search Tools

1. Basic Search (search_candidates)

• Keyword-based search with support for keyword typo tolerance.
• Support for field-specific search.
• Support for filtering, sorting, and grouping functions.
• Allows for exact matching options.

2. Vector Search (vector_search_candidates)

• Similarity search using vector embeddings.
• Suitable for finding candidates with similar profiles.
• Supports hybrid search combined with filters.

3. Semantic Search (semantic_search_candidates)

• Has natural language understanding capabilities.
• Automatically generates embedding representations.
• Supports multiple embedding models (OpenAI, SBERT, E5).
• Hybrid search combining semantic understanding and filters.

⚙️ Configuration

Environment Variables

• TACITBASE_AUTH_TOKEN: Authentication token for the Tacitbase API.
• TYPESENSE_API_KEY: API key for Typesense.
• TYPESENSE_HOST (default: localhost): Host address of the Typesense service.
• TYPESENSE_PORT (default: 8108): Port of the Typesense service.
• TYPESENSE_PROTOCOL (default: http): Protocol of the Typesense service.

📦 Installation

1. Download dependencies:

go mod download

2. Build the server:

go build -o tb-mcp-server

3. Run the server:

./tb-mcp-server

💻 Usage Examples

Basic Search

{
  "query": "golang developer",
  "search_fields": "skills,latest_experience",
  "filter_fields": "location:San Francisco",
  "sort_by": "latest_experience:desc",
  "page": 1,
  "per_page": 20
}

Vector Search

{
  "vector_query": "[0.1, 0.2, ..., 0.512]",
  "filter_fields": "work_experience:>5",
  "page": 1,
  "per_page": 20
}

Semantic Search

{
  "query": "Candidates with team leadership experience and familiarity with cloud technologies",
  "search_fields": "skills,experience,education",
  "filter_fields": "location:Beijing, age_range:28-35",
  "sort_by": "relevance:desc",
  "page": 1,
  "per_page": 20
}

💻 Development

Project Initialization

For projects managed by Go modules, you can initialize them with the following commands:

go mod init your_project_name
go mod tidy

Running Tests

Run the test cases in the project:

go test -v ./...

API Documentation

API documentation can be generated using the following tools:

• Go Swagger
• Gin's route grouping

Code Examples

Basic Search Implementation

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": "Invalid request format"})
			return
		}

		// Simulate search logic
		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{} {
	// Simulate search results
	return []map[string]interface{}{
		{
			"id":    1,
			"title": "Golang Development Engineer",
			"company": "Example Company",
		},
		{
			"id":    2,
			"title": "Senior Golang Developer",
			"company": "Another Company",
		},
	}
}

Vector Search Implementation

package main

import (
	"fmt"
	"math"
	"sort"
)

func vectorSearch(embeddings [][]float64, queryEmbedding []float64) []int {
	// Calculate cosine similarity
	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
		}
	}

	// Sort by similarity
	order := make([]int, len(similarities))
	for i := range order {
		order[i] = i
	}
	sort.Slice(order, func(i, j int) bool {
		return similarities[order[i]] > similarities[order[j]]
	})

	return order
}

🤝 Project Contribution

Contributions to this project are welcome! Please refer to the CONTRIBUTING.md file for details on how to contribute.

📄 License

This project is licensed under the MIT License.