ruvector/tests/MCP_TESTS.md

RuVector MCP Server Test Scripts

This directory contains test scripts demonstrating how to use the RuVector MCP (Model Context Protocol) server.

Test Scripts

1. mcp-demo.js - Full Featured Demo

A comprehensive demonstration of the MCP server capabilities using the official MCP SDK.

Features:

• Creates a vector database with configurable dimensions
• Inserts sample document vectors with metadata
• Performs semantic search queries
• Demonstrates batch operations
• Shows database statistics

Prerequisites:

# Install dependencies (if not already installed)
npm install

# Build the MCP server binary
cargo build --release -p ruvector-cli --bin ruvector-mcp

Usage:

node tests/mcp-demo.js

2. mcp-simple-test.js - Simple JSON-RPC Test

A lightweight test script using direct JSON-RPC communication without requiring the full SDK.

Features:

• Minimal dependencies
• Direct JSON-RPC over stdio
• Simple vector operations (create, insert, search)
• Database statistics

Usage:

node tests/mcp-simple-test.js

Custom server path:

MCP_SERVER_PATH=/path/to/ruvector-mcp node tests/mcp-simple-test.js

Available MCP Tools

The RuVector MCP server provides the following tools:

Vector Database Operations

• vector_db_create - Create a new vector database
• vector_db_insert - Insert/upsert vectors with metadata
• vector_db_search - Perform semantic similarity search
• vector_db_stats - Get database statistics
• vector_db_backup - Backup database to file

GNN (Graph Neural Network) Operations

• gnn_layer_create - Create/cache GNN layers
• gnn_forward - Forward pass through GNN layer
• gnn_batch_forward - Batch GNN operations
• gnn_cache_stats - Get GNN cache statistics
• gnn_compress - Compress embeddings
• gnn_decompress - Decompress embeddings

Example: Creating a Collection and Searching

const { SimpleMCPClient, generateEmbedding } = require('./mcp-simple-test.js');

async function example() {
  const client = new SimpleMCPClient({
    cmd: './target/release/ruvector-mcp',
    args: []
  });

  await client.start();

  // Create database
  await client.callTool('vector_db_create', {
    path: './my-vectors.db',
    dimensions: 128,
    distance_metric: 'cosine'
  });

  // Insert vectors
  await client.callTool('vector_db_insert', {
    db_path: './my-vectors.db',
    vectors: [{
      id: 'doc-1',
      vector: generateEmbedding(128, 1),
      metadata: { title: 'My Document' }
    }]
  });

  // Search
  const results = await client.callTool('vector_db_search', {
    db_path: './my-vectors.db',
    query: generateEmbedding(128, 1.1),
    k: 5
  });

  console.log(JSON.parse(results.content[0].text));

  await client.close();
}

Distance Metrics

Supported distance metrics:

• cosine - Cosine similarity (recommended for normalized vectors)
• euclidean - Euclidean distance (L2)
• dotproduct - Dot product similarity
• manhattan - Manhattan distance (L1)

Integration with Claude Code

To use the MCP server with Claude Code:

# Add to Claude Code MCP configuration
claude mcp add ruvector -- /path/to/ruvector-mcp

Then Claude can use the vector database tools directly.

Performance Tips

1. Batch Operations: Use batch insert for better performance
2. Dimensions: Choose dimensions based on your embedding model (common: 128, 384, 768, 1536)
3. Distance Metric: Use cosine for normalized embeddings, euclidean for unnormalized
4. GNN Caching: The server automatically caches GNN layers for ~250-500x speedup

Troubleshooting

Server binary not found

# Build the release version
cargo build --release -p ruvector-cli --bin ruvector-mcp

# Or use debug version (slower)
cargo build -p ruvector-cli --bin ruvector-mcp
MCP_SERVER_PATH=./target/debug/ruvector-mcp node tests/mcp-simple-test.js

Dependencies missing

# Install Node.js dependencies
npm install

# Or install just the MCP SDK
npm install @modelcontextprotocol/sdk

Permission denied

# Make the test script executable
chmod +x tests/mcp-demo.js
chmod +x tests/mcp-simple-test.js

Architecture

┌─────────────────┐
│  Test Script    │
│  (Node.js)      │
└────────┬────────┘
         │ JSON-RPC
         │ over stdio
┌────────▼────────┐
│   MCP Server    │
│  (Rust binary)  │
└────────┬────────┘
         │
┌────────▼────────┐
│   RuVector DB   │
│  (Rust crate)   │
└─────────────────┘

Further Reading

• Model Context Protocol Specification
• RuVector Documentation
• MCP Server Implementation
• MCP Handler Reference