ruvector/tests/QUICKSTART.md

Quick Start: RuVector MCP Server

This guide shows you how to quickly test the RuVector MCP server.

Usage

Option 1: Using the Simple Test Script

The simplest way to test the MCP server:

# 1. Build the MCP server (first time only)
cargo build --release -p ruvector-cli --bin ruvector-mcp

# 2. Run the test
node tests/mcp-simple-test.js

Expected Output:

🧪 RuVector MCP Server Simple Test
======================================================================

🚀 Starting MCP server...
✅ MCP server started

📦 Test 1: Creating vector database
   Path: /tmp/ruvector-test.db
   Dimensions: 128

✅ Database created
   {"status":"ok","path":"/tmp/ruvector-test.db"}

----------------------------------------------------------------------

📝 Test 2: Inserting sample vectors

   Inserting: vec-1 (Sample A)
   Inserting: vec-2 (Sample B)
   Inserting: vec-3 (Sample C)

✅ All vectors inserted

----------------------------------------------------------------------

🔍 Test 3: Semantic search

   Searching for similar vectors...

   Results:

   1. vec-1
      Score: 0.9876
      Metadata: {"label":"Sample A","type":"test"}

   2. vec-2
      Score: 0.9234
      Metadata: {"label":"Sample B","type":"test"}

   3. vec-3
      Score: 0.8765
      Metadata: {"label":"Sample C","type":"demo"}

======================================================================

✅ All tests passed!

Option 2: Using the Full Demo

For a more comprehensive demonstration:

node tests/mcp-demo.js

This will:

• Create a vector database
• Insert 5 sample documents with realistic metadata
• Perform 3 semantic search queries
• Demonstrate batch operations
• Show performance metrics

Option 3: Manual Testing

Test individual operations manually:

# Start the MCP server
./target/release/ruvector-mcp

# In another terminal, send JSON-RPC commands:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./target/release/ruvector-mcp

What Each Test Does

Simple Test (mcp-simple-test.js)

• ✅ Creates a 128-dimensional vector database
• ✅ Inserts 3 test vectors
• ✅ Performs semantic search
• ✅ Shows database statistics
• ⏱️ Runtime: ~2-5 seconds

Full Demo (mcp-demo.js)

• ✅ Creates a 384-dimensional vector database
• ✅ Inserts 5 documents with rich metadata
• ✅ Performs 3 different semantic searches
• ✅ Batch inserts 10 more vectors
• ✅ Shows performance metrics
• ✅ Demonstrates real-world use cases
• ⏱️ Runtime: ~5-10 seconds

Troubleshooting

"MCP server binary not found"

Build it first:

cargo build --release -p ruvector-cli --bin ruvector-mcp

Or use debug build (faster to compile):

cargo build -p ruvector-cli --bin ruvector-mcp
MCP_SERVER_PATH=./target/debug/ruvector-mcp node tests/mcp-simple-test.js

"Cannot find module '@modelcontextprotocol/sdk'"

Install dependencies:

npm install

Or just install the SDK:

npm install @modelcontextprotocol/sdk

Server hangs or times out

1. Check if the server starts:

./target/release/ruvector-mcp --help

2. Test manual JSON-RPC:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | ./target/release/ruvector-mcp

3. Check server logs (enable debug mode):

DEBUG=1 node tests/mcp-simple-test.js

Next Steps

After successfully running the tests:

1. Integrate with Claude Code

   claude mcp add ruvector -- ./target/release/ruvector-mcp
   

2. Use Real Embeddings

   • Replace generateEmbedding() with actual embedding models
   • Try: sentence-transformers, OpenAI embeddings, Cohere

3. Scale Up

   • Test with larger vector dimensions (768, 1536)
   • Insert thousands of vectors
   • Benchmark search performance

4. Explore GNN Tools

   • Try graph-based queries
   • Use the GNN layer caching
   • Experiment with graph neural network operations

Examples

Semantic Document Search

// Insert documents
await client.callTool('vector_db_insert', {
  db_path: './docs.db',
  vectors: [{
    id: 'doc-1',
    vector: await embedText('Machine learning tutorial'),
    metadata: {
      title: 'ML Tutorial',
      author: 'John Doe',
      tags: ['ml', 'tutorial']
    }
  }]
});

// Search
const results = await client.callTool('vector_db_search', {
  db_path: './docs.db',
  query: await embedText('AI learning guide'),
  k: 5
});

Image Similarity

// Insert image embeddings
await client.callTool('vector_db_insert', {
  db_path: './images.db',
  vectors: [{
    id: 'img-1',
    vector: await embedImage('cat.jpg'),
    metadata: {
      filename: 'cat.jpg',
      category: 'animals'
    }
  }]
});

// Find similar images
const similar = await client.callTool('vector_db_search', {
  db_path: './images.db',
  query: await embedImage('kitten.jpg'),
  k: 10
});

Learn More

• MCP Tests Documentation
• RuVector README
• MCP Specification