zilliz-mcp-server
Version:
Universal memory layer MCP server for Zilliz Cloud - enables continuous conversations across all LLMs and agents
651 lines • 31 kB
JavaScript
import { MemoryType } from './types.js';
export class ZillizMCPTools {
client;
memoryManager;
defaultClusterId;
constructor(client, memoryManager) {
this.client = client;
this.memoryManager = memoryManager;
}
setDefaultCluster(clusterId) {
this.defaultClusterId = clusterId;
}
// Define all available MCP tools
getTools() {
return [
// Memory Layer Tools - The core functionality
{
name: 'memory_remember',
description: 'Store information in the shared memory layer that all LLMs and agents can access. This creates persistent memory across conversations.',
inputSchema: {
type: 'object',
properties: {
content: { type: 'string', description: 'The information to remember' },
type: {
type: 'string',
enum: Object.values(MemoryType),
description: 'Type of memory: short_term (recent context), long_term (important facts), procedural (how-to knowledge), episodic (specific events), semantic (general knowledge), shared (between agents)'
},
importance: { type: 'number', minimum: 0, maximum: 1, description: 'Importance score (0-1, higher = more important)' },
tags: { type: 'array', items: { type: 'string' }, description: 'Tags to categorize this memory' },
userId: { type: 'string', description: 'User ID this memory belongs to' },
sessionId: { type: 'string', description: 'Session ID for conversation context' }
},
required: ['content', 'type']
}
},
{
name: 'memory_recall',
description: 'Search and retrieve relevant memories from the shared memory layer. All LLMs and agents can access the same memories.',
inputSchema: {
type: 'object',
properties: {
query: { type: 'string', description: 'What to search for in memories' },
type: {
type: 'string',
enum: Object.values(MemoryType),
description: 'Optional: filter by memory type'
},
limit: { type: 'number', default: 10, description: 'Maximum number of memories to retrieve' },
minSimilarity: { type: 'number', minimum: 0, maximum: 1, default: 0.7, description: 'Minimum similarity score' },
userId: { type: 'string', description: 'Filter memories by user ID' }
},
required: ['query']
}
},
{
name: 'memory_get_conversation',
description: 'Get the continuous conversation history for a session. This maintains context across different LLMs and agents.',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Session ID to get history for' },
limit: { type: 'number', default: 50, description: 'Maximum number of messages' }
},
required: ['sessionId']
}
},
{
name: 'memory_share_context',
description: 'Share specific memories with another agent or LLM. This enables seamless handoffs between different AI systems.',
inputSchema: {
type: 'object',
properties: {
fromAgent: { type: 'string', description: 'Agent sharing the memory' },
toAgent: { type: 'string', description: 'Agent receiving the memory' },
contextIds: { type: 'array', items: { type: 'string' }, description: 'Memory IDs to share' }
},
required: ['fromAgent', 'toAgent', 'contextIds']
}
},
{
name: 'memory_get_continuous_context',
description: 'Get the complete continuous context for a user session including recent, persistent, and shared memories.',
inputSchema: {
type: 'object',
properties: {
userId: { type: 'string', description: 'User ID' },
sessionId: { type: 'string', description: 'Session ID' }
},
required: ['userId', 'sessionId']
}
},
{
name: 'memory_analytics',
description: 'Get analytics about the memory system including usage stats, memory distribution, and performance metrics.',
inputSchema: {
type: 'object',
properties: {}
}
},
// Cluster Management Tools
{
name: 'zilliz_list_projects',
description: 'List all projects in your Zilliz Cloud account',
inputSchema: {
type: 'object',
properties: {}
}
},
{
name: 'zilliz_create_project',
description: 'Create a new project in Zilliz Cloud',
inputSchema: {
type: 'object',
properties: {
name: { type: 'string', description: 'Project name' },
description: { type: 'string', description: 'Project description' }
},
required: ['name']
}
},
{
name: 'zilliz_list_clusters',
description: 'List all clusters in your projects',
inputSchema: {
type: 'object',
properties: {
projectId: { type: 'string', description: 'Filter by project ID' }
}
}
},
{
name: 'zilliz_create_free_cluster',
description: 'Create a new free-tier Milvus cluster',
inputSchema: {
type: 'object',
properties: {
clusterName: { type: 'string', description: 'Name for the cluster' },
regionId: { type: 'string', description: 'Region ID (default: gcp-us-west1)' }
},
required: ['clusterName']
}
},
{
name: 'zilliz_describe_cluster',
description: 'Get detailed information about a specific cluster',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID to describe' }
},
required: ['clusterId']
}
},
{
name: 'zilliz_suspend_cluster',
description: 'Suspend a running cluster to save costs',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID to suspend' }
},
required: ['clusterId']
}
},
{
name: 'zilliz_resume_cluster',
description: 'Resume a suspended cluster',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID to resume' }
},
required: ['clusterId']
}
},
{
name: 'zilliz_query_cluster_metrics',
description: 'Get performance metrics for a cluster',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
timeRange: { type: 'string', description: 'Time range (e.g., 1h, 1d, 1w)', default: '1h' }
},
required: ['clusterId']
}
},
// Collection Management Tools
{
name: 'zilliz_list_databases',
description: 'List all databases in a cluster',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' }
},
required: ['clusterId']
}
},
{
name: 'zilliz_list_collections',
description: 'List all collections in a database',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
dbName: { type: 'string', description: 'Database name', default: 'default' }
},
required: ['clusterId']
}
},
{
name: 'zilliz_create_collection',
description: 'Create a new collection with specified schema',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
collectionName: { type: 'string', description: 'Collection name' },
dimension: { type: 'number', description: 'Vector dimension for quick setup' },
metricType: { type: 'string', enum: ['L2', 'IP', 'COSINE'], description: 'Distance metric' },
schema: {
type: 'object',
description: 'Custom schema definition (overrides dimension and metricType)'
}
},
required: ['clusterId', 'collectionName']
}
},
{
name: 'zilliz_describe_collection',
description: 'Get detailed information about a collection',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
collectionName: { type: 'string', description: 'Collection name' }
},
required: ['clusterId', 'collectionName']
}
},
{
name: 'zilliz_drop_collection',
description: 'Delete a collection (WARNING: This is permanent)',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
collectionName: { type: 'string', description: 'Collection name to delete' }
},
required: ['clusterId', 'collectionName']
}
},
// Data Operations Tools
{
name: 'zilliz_insert_entities',
description: 'Insert data entities into a collection',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
collectionName: { type: 'string', description: 'Collection name' },
data: {
type: 'array',
items: { type: 'object' },
description: 'Array of data objects to insert'
}
},
required: ['clusterId', 'collectionName', 'data']
}
},
{
name: 'zilliz_delete_entities',
description: 'Delete entities from a collection based on filter',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
collectionName: { type: 'string', description: 'Collection name' },
filter: { type: 'string', description: 'Filter expression for deletion' }
},
required: ['clusterId', 'collectionName', 'filter']
}
},
{
name: 'zilliz_search',
description: 'Perform vector similarity search on a collection',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
collectionName: { type: 'string', description: 'Collection name' },
data: {
type: 'array',
items: {
type: 'array',
items: { type: 'number' }
},
description: 'Query vectors'
},
annsField: { type: 'string', description: 'Vector field name to search' },
limit: { type: 'number', description: 'Number of results to return' },
filter: { type: 'string', description: 'Filter expression' },
outputFields: {
type: 'array',
items: { type: 'string' },
description: 'Fields to return in results'
}
},
required: ['clusterId', 'collectionName', 'data', 'annsField', 'limit']
}
},
{
name: 'zilliz_query',
description: 'Query entities based on scalar filter expressions',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
collectionName: { type: 'string', description: 'Collection name' },
filter: { type: 'string', description: 'Filter expression' },
outputFields: {
type: 'array',
items: { type: 'string' },
description: 'Fields to return'
},
limit: { type: 'number', description: 'Maximum results' },
offset: { type: 'number', description: 'Results offset' }
},
required: ['clusterId', 'collectionName', 'filter']
}
},
{
name: 'zilliz_hybrid_search',
description: 'Perform hybrid search combining vector similarity and scalar filters',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
collectionName: { type: 'string', description: 'Collection name' },
search: {
type: 'array',
description: 'Array of search requests'
},
rerank: {
type: 'object',
properties: {
strategy: { type: 'string', enum: ['rrf', 'weighted'] },
params: { type: 'object' }
},
description: 'Reranking strategy'
},
limit: { type: 'number', description: 'Number of final results' },
outputFields: {
type: 'array',
items: { type: 'string' }
}
},
required: ['clusterId', 'collectionName', 'search', 'rerank', 'limit']
}
},
// Index Management Tools
{
name: 'zilliz_create_index',
description: 'Create an index on a collection field',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
collectionName: { type: 'string', description: 'Collection name' },
fieldName: { type: 'string', description: 'Field to index' },
indexType: { type: 'string', description: 'Index type (e.g., AUTOINDEX, IVF_FLAT)' },
metricType: { type: 'string', enum: ['L2', 'IP', 'COSINE'], description: 'Distance metric' },
params: { type: 'object', description: 'Index parameters' }
},
required: ['clusterId', 'collectionName', 'fieldName']
}
},
{
name: 'zilliz_list_indexes',
description: 'List all indexes for a collection',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
collectionName: { type: 'string', description: 'Collection name' }
},
required: ['clusterId', 'collectionName']
}
},
// Collection Lifecycle Tools
{
name: 'zilliz_load_collection',
description: 'Load a collection into memory for querying',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
collectionName: { type: 'string', description: 'Collection name' }
},
required: ['clusterId', 'collectionName']
}
},
{
name: 'zilliz_release_collection',
description: 'Release a collection from memory',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
collectionName: { type: 'string', description: 'Collection name' }
},
required: ['clusterId', 'collectionName']
}
},
{
name: 'zilliz_get_load_state',
description: 'Check the load state of a collection',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID' },
collectionName: { type: 'string', description: 'Collection name' }
},
required: ['clusterId', 'collectionName']
}
},
// Utility Tools
{
name: 'zilliz_health_check',
description: 'Check the health of the Zilliz connection',
inputSchema: {
type: 'object',
properties: {}
}
},
{
name: 'zilliz_setup_memory_layer',
description: 'Initialize the shared memory layer for LLM/agent communication',
inputSchema: {
type: 'object',
properties: {
clusterId: { type: 'string', description: 'Cluster ID to setup memory in' },
collectionName: { type: 'string', description: 'Memory collection name', default: 'alphe_memory' },
dimensions: { type: 'number', description: 'Vector dimensions', default: 768 }
},
required: ['clusterId']
}
}
];
}
// Handle tool calls
async callTool(request) {
const { name, arguments: args } = request.params;
if (!args || typeof args !== 'object') {
throw new Error('Invalid arguments provided');
}
// Type cast for convenience
const params = args;
try {
let result;
const clusterId = params.clusterId || this.defaultClusterId;
switch (name) {
// Memory Layer Tools
case 'memory_remember':
const memoryId = await this.memoryManager.remember(params.content, params.type, params.importance);
result = { success: true, memoryId, message: 'Memory stored successfully' };
break;
case 'memory_recall':
const memories = await this.memoryManager.recall(params.query, params.type, params.limit);
result = {
success: true,
memories: memories.map(m => ({
id: m.item.id,
content: m.item.content,
similarity: m.similarity,
type: m.item.type,
importance: m.item.importance,
source: m.item.metadata.source,
createdAt: m.item.createdAt
}))
};
break;
case 'memory_get_conversation':
const conversation = await this.memoryManager.getConversationHistory(params.sessionId, params.limit);
result = { success: true, conversation };
break;
case 'memory_share_context':
for (const contextId of params.contextIds) {
await this.memoryManager.shareContext(params.fromAgent, params.toAgent, contextId);
}
result = { success: true, message: `Shared ${params.contextIds.length} contexts` };
break;
case 'memory_get_continuous_context':
const context = await this.memoryManager.getContinuousContext(params.userId, params.sessionId);
result = { success: true, context };
break;
case 'memory_analytics':
const analytics = await this.memoryManager.getMemoryStats();
result = { success: true, analytics };
break;
// Cluster Management
case 'zilliz_list_projects':
result = await this.client.listProjects();
break;
case 'zilliz_create_project':
result = await this.client.createProject(params.name, params.description);
break;
case 'zilliz_list_clusters':
result = await this.client.listClusters(params.projectId);
break;
case 'zilliz_create_free_cluster':
result = await this.client.createFreeCluster(params.clusterName, params.regionId);
break;
case 'zilliz_describe_cluster':
result = await this.client.describeCluster(params.clusterId);
break;
case 'zilliz_suspend_cluster':
await this.client.suspendCluster(params.clusterId);
result = { success: true, message: 'Cluster suspended successfully' };
break;
case 'zilliz_resume_cluster':
await this.client.resumeCluster(params.clusterId);
result = { success: true, message: 'Cluster resumed successfully' };
break;
case 'zilliz_query_cluster_metrics':
result = await this.client.queryClusterMetrics(params.clusterId, params.timeRange);
break;
// Data Operations
case 'zilliz_list_databases':
result = await this.client.listDatabases(clusterId);
break;
case 'zilliz_list_collections':
result = await this.client.listCollections(clusterId, params.dbName);
break;
case 'zilliz_create_collection':
const collectionConfig = {
collectionName: params.collectionName,
...(params.schema || {
dimension: params.dimension || 768,
metricType: params.metricType || 'COSINE'
})
};
result = await this.client.createCollection(clusterId, collectionConfig);
break;
case 'zilliz_describe_collection':
result = await this.client.describeCollection(clusterId, params.collectionName);
break;
case 'zilliz_drop_collection':
await this.client.dropCollection(clusterId, params.collectionName);
result = { success: true, message: 'Collection deleted successfully' };
break;
case 'zilliz_insert_entities':
result = await this.client.insertEntities(clusterId, params.collectionName, params.data);
break;
case 'zilliz_delete_entities':
result = await this.client.deleteEntities(clusterId, params.collectionName, params.filter);
break;
case 'zilliz_search':
result = await this.client.search(clusterId, {
collectionName: params.collectionName,
data: params.data,
annsField: params.annsField,
limit: params.limit,
filter: params.filter,
outputFields: params.outputFields
});
break;
case 'zilliz_query':
result = await this.client.query(clusterId, {
collectionName: params.collectionName,
filter: params.filter,
outputFields: params.outputFields,
limit: params.limit,
offset: params.offset
});
break;
case 'zilliz_hybrid_search':
result = await this.client.hybridSearch(clusterId, {
collectionName: params.collectionName,
search: params.search,
rerank: params.rerank,
limit: params.limit,
outputFields: params.outputFields
});
break;
// Index Management
case 'zilliz_create_index':
await this.client.createIndex(clusterId, params.collectionName, {
fieldName: params.fieldName,
indexType: params.indexType || 'AUTOINDEX',
metricType: params.metricType || 'COSINE',
params: params.params || {}
});
result = { success: true, message: 'Index created successfully' };
break;
case 'zilliz_list_indexes':
result = await this.client.listIndexes(clusterId, params.collectionName);
break;
// Collection Lifecycle
case 'zilliz_load_collection':
await this.client.loadCollection(clusterId, params.collectionName);
result = { success: true, message: 'Collection loaded successfully' };
break;
case 'zilliz_release_collection':
await this.client.releaseCollection(clusterId, params.collectionName);
result = { success: true, message: 'Collection released successfully' };
break;
case 'zilliz_get_load_state':
result = await this.client.getLoadState(clusterId, params.collectionName);
break;
// Utility
case 'zilliz_health_check':
const isHealthy = await this.client.healthCheck();
result = {
success: isHealthy,
message: isHealthy ? 'Connection healthy' : 'Connection failed',
timestamp: new Date().toISOString()
};
break;
case 'zilliz_setup_memory_layer':
await this.memoryManager.initialize();
result = {
success: true,
message: 'Memory layer initialized successfully',
collectionName: params.collectionName || 'alphe_memory',
dimensions: params.dimensions || 768
};
break;
default:
throw new Error(`Unknown tool: ${name}`);
}
return [{
type: 'text',
text: JSON.stringify(result, null, 2)
}];
}
catch (error) {
return [{
type: 'text',
text: JSON.stringify({
success: false,
error: error.message,
details: error.details || null
}, null, 2)
}];
}
}
}
//# sourceMappingURL=mcp-tools.js.map