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"
    }
}