Star Wars Planet Data (Couchbase)

🚀 用於《星球大戰》行星語義搜索的 Couchbase 模型上下文協議服務器

本項目藉助 Couchbase 的向量搜索功能，實現了模型上下文協議（MCP）服務器，為用戶提供《星球大戰》行星的語義搜索能力，幫助用戶便捷獲取相關信息。

🚀 快速開始

本項目實現的 MCP 服務器，為 AI 模型與外部工具和數據源的交互提供了標準方式。藉助該服務器，AI 模型能夠獲取《星球大戰》行星的詳細信息，還能依據向量嵌入查找相似的行星。

✨ 主要特性

• 高效的向量搜索：利用 Couchbase 的向量索引進行快速相似性查找。
• 超時保護：為搜索和文檔獲取操作實現超時。
• 連接管理：正確管理 Couchbase 連接並清理。
• 錯誤處理：全面的錯誤處理和調試支持。
• 類型安全：完整的 TypeScript 實現，具有正確的類型定義。

🔧 技術細節

模型上下文協議集成

服務器實現了兩個主要的 MCP 工具，這些工具可被支持模型上下文協議的 AI 模型發現和調用：

{
    tools: [
        {
            name: "fetch_planet_name",
            description: "按名稱獲取《星球大戰》行星",
            inputSchema: // ... 行星名稱的模式
        },
        {
            name: "find_planets_which_are_similar",
            description: "查找與給定名稱相似的行星",
            inputSchema: // ... 行星名稱的模式
        }
    ]
}

Couchbase 向量搜索

本實現使用 Couchbase 的向量搜索功能查找相似行星：

1. 每個 Couchbase 中的行星文檔包含一個 embedding 字段，其中包含表示行星特徵的向量。
2. 查找相似行星時：
   • 獲取源行星的嵌入。
   • 使用 Couchbase 的向量搜索來查找具有相似嵌入的行星。
   • 返回最相似的 5 個行星。

📦 安裝指南

先決條件

• Node.js
• 帶有向量搜索功能的 Couchbase 服務器
• 環境變量：

COUCHBASE_URL=
COUCHBASE_USERNAME=
COUCHBASE_PASSWORD=
COUCHBASE_BUCKET=
COUCHBASE_SCOPE=
COUCHBASE_COLLECTION=

數據結構

每個行星文檔應遵循以下結構：

interface StarWarsCharacter {
    name: string;
    rotation_period: string;
    orbital_period: string;
    diameter: string;
    climate: string;
    gravity: string;
    terrain: string;
    surface_water: string;
    population: string;
    residents: string[];
    films: string[];
    created: string;
    edited: string;
    url: string;
    embedding?: number[]; // 用於相似性搜索的向量嵌入
}

向量搜索索引

需在 Couchbase 中創建一個名為 vector-search-index 的向量搜索索引，該索引引用 embedding 字段。

💻 使用示例

基礎用法

1. 啟動服務器：

npm start

2. 服務器將通過 stdin/stdout 監聽 MCP 請求。
3. AI 模型可以使用以下示例查詢與服務器交互：

// 獲取行星詳細信息
{
    "name": "fetch_planet_name",
    "arguments": {
        "name": "Tatooine"
    }
}

// 查找相似的行星
{
    "name": "find_planets_which_are_similar",
    "arguments": {
        "name": "Tatooine"
    }
}