mcp-memory-libsql

Instructions

Implementation Reference

• src/db/client.ts:35-130 (handler)

  Core handler implementation: Validates input entities, performs upsert (update or insert) on entities table, manages observations in transaction per entity.

  async create_entities(
  	entities: Array<{
  		name: string;
  		entityType: string;
  		observations: string[];
  	}>,
  ): Promise<void> {
  	try {
  		for (const entity of entities) {
  			// Validate entity name
  			if (
  				!entity.name ||
  				typeof entity.name !== 'string' ||
  				entity.name.trim() === ''
  			) {
  				throw new Error('Entity name must be a non-empty string');
  			}
  
  			// Validate entity type
  			if (
  				!entity.entityType ||
  				typeof entity.entityType !== 'string' ||
  				entity.entityType.trim() === ''
  			) {
  				throw new Error(
  					`Invalid entity type for entity "${entity.name}"`,
  				);
  			}
  
  			// Validate observations
  			if (
  				!Array.isArray(entity.observations) ||
  				entity.observations.length === 0
  			) {
  				throw new Error(
  					`Entity "${entity.name}" must have at least one observation`,
  				);
  			}
  
  			if (
  				!entity.observations.every(
  					(obs) => typeof obs === 'string' && obs.trim() !== '',
  				)
  			) {
  				throw new Error(
  					`Entity "${entity.name}" has invalid observations. All observations must be non-empty strings`,
  				);
  			}
  
  			// Start a transaction
  			const txn = await this.client.transaction('write');
  
  			try {
  				// First try to update
  				const result = await txn.execute({
  					sql: 'UPDATE entities SET entity_type = ? WHERE name = ?',
  					args: [entity.entityType, entity.name],
  				});
  
  				// If no rows affected, do insert
  				if (result.rowsAffected === 0) {
  					await txn.execute({
  						sql: 'INSERT INTO entities (name, entity_type) VALUES (?, ?)',
  						args: [entity.name, entity.entityType],
  					});
  				}
  
  				// Clear old observations
  				await txn.execute({
  					sql: 'DELETE FROM observations WHERE entity_name = ?',
  					args: [entity.name],
  				});
  
  				// Add new observations
  				for (const observation of entity.observations) {
  					await txn.execute({
  						sql: 'INSERT INTO observations (entity_name, content) VALUES (?, ?)',
  						args: [entity.name, observation],
  					});
  				}
  
  				await txn.commit();
  			} catch (error) {
  				await txn.rollback();
  				throw error;
  			}
  		}
  	} catch (error) {
  		// Wrap all errors with context
  		throw new Error(
  			`Entity operation failed: ${
  				error instanceof Error ? error.message : String(error)
  			}`,
  		);
  	}
  }

• src/index.ts:23-31 (schema)

  Input schema using Valibot for validating the entities array with name, entityType, and observations.

  const CreateEntitiesSchema = v.object({
  	entities: v.array(
  		v.object({
  			name: v.string(),
  			entityType: v.string(),
  			observations: v.array(v.string()),
  		}),
  	),
  });

• src/index.ts:60-99 (registration)

  MCP server tool registration with name, description, schema, and thin async handler that calls the db.create_entities method and handles response/error.

  server.tool<typeof CreateEntitiesSchema>(
  	{
  		name: 'create_entities',
  		description: 'Create new entities with observations',
  		schema: CreateEntitiesSchema,
  	},
  	async ({ entities }) => {
  		try {
  			await db.create_entities(entities);
  			return {
  				content: [
  					{
  						type: 'text' as const,
  						text: `Successfully processed ${entities.length} entities (created new or updated existing)`,
  					},
  				],
  			};
  		} catch (error) {
  			return {
  				content: [
  					{
  						type: 'text' as const,
  						text: JSON.stringify(
  							{
  								error: 'internal_error',
  								message:
  									error instanceof Error
  										? error.message
  										: 'Unknown error',
  							},
  							null,
  							2,
  						),
  					},
  				],
  				isError: true,
  			};
  		}
  	},
  );