Star Wars Planet Data (Couchbase)

🚀 Couchbase Model Context Protocol Server for Semantic Search of Star Wars Planets

This project demonstrates a Model Context Protocol (MCP) server implemented using Couchbase's vector search capabilities, providing semantic search functionality for Star Wars planets.

🚀 Quick Start

This project showcases an MCP server that enables AI models to conduct semantic searches on Star Wars planets. It combines MCP integration with Couchbase's vector search to offer efficient and accurate search results.

✨ Features

MCP Integration

The server implements two main MCP tools:

{
    tools: [
        {
            name: "fetch_planet_name",
            description: "Retrieve a Star Wars planet by name",
            inputSchema: // ... Schema for the planet name
        },
        {
            name: "find_planets_which_are_similar",
            description: "Find planets similar to a given name",
            inputSchema: // ... Schema for the planet name
        }
    ]
}

These tools can be discovered and invoked by AI models supporting the Model Context Protocol.

Couchbase Vector Search

This implementation uses Couchbase's vector search feature to find similar planets:

1. Each planet document in Couchbase contains an embedding field with a vector representing the planet's features.
2. When finding similar planets:
   • Obtain the embedding of the source planet.
   • Use Couchbase's vector search to find planets with similar embeddings.
   • Return the top 5 most similar planets.

Key Features

• Efficient Vector Search: Utilize Couchbase's vector index for fast similarity searches.
• Timeout Protection: Implement timeouts for search and document retrieval operations.
• Connection Management: Properly manage Couchbase connections and perform cleanup.
• Error Handling: Comprehensive error handling and debugging support.
• Type Safety: Fully implemented in TypeScript with correct type definitions.

📦 Installation

Prerequisites

• Node.js
• A Couchbase server with vector search capabilities
• Environment variables:

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

Data Structure

Each planet document should follow the following structure:

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[]; // Vector embedding for similarity search
}

Vector Search Index

Create a vector search index named vector-search-index in Couchbase, which references the embedding field.

💻 Usage Examples

Basic Usage

1. Start the server:

npm start

2. The server will listen for MCP requests via stdin/stdout.
3. AI models can interact with the server using the following example queries:

// Get planet details
{
    "name": "fetch_planet_name",
    "arguments": {
        "name": "Tatooine"
    }
}

// Find similar planets
{
    "name": "find_planets_which_are_similar",
    "arguments": {
        "name": "Tatooine"
    }
}