MCP DuckDB Knowledge Graph Memory Server

Instructions

Implementation Reference

• src/manager.ts:261-328 (handler)

  The core handler function in DuckDBKnowledgeGraphManager that implements the logic for creating relations: validates entity existence, deduplicates against existing relations, and inserts new ones into the DuckDB 'relations' table using transactions.

  async createRelations(relations: Relation[]): Promise<Relation[]> {
    using conn = await this.getConn();
  
    try {
      // Begin transaction
      await conn.execute("BEGIN TRANSACTION");
  
      // Get the set of entity names
      const entityNamesReader = await conn.executeAndReadAll(
        "SELECT name FROM entities"
      );
      const entityNamesData = entityNamesReader.getRows();
      const nameColumnIndex = 0; // name column is the first column
      const entityNames = new Set(
        entityNamesData.map((row: any) => row[nameColumnIndex] as string)
      );
  
      // Filter valid relations (both from and to entities must exist)
      const validRelations = relations.filter(
        (relation) =>
          entityNames.has(relation.from) && entityNames.has(relation.to)
      );
  
      // Get existing relations
      const existingRelationsReader = await conn.executeAndReadAll(
        'SELECT from_entity as "from", to_entity as "to", relationType FROM relations'
      );
      const existingRelationsData = existingRelationsReader.getRows();
  
      // Convert results to an array of Relation objects
      const existingRelations = existingRelationsData.map((row: any) => {
        return {
          from: row[0] as string,
          to: row[1] as string,
          relationType: row[2] as string,
        };
      });
  
      // Filter new relations
      const newRelations = validRelations.filter(
        (newRel) =>
          !existingRelations.some(
            (existingRel: any) =>
              existingRel.from === newRel.from &&
              existingRel.to === newRel.to &&
              existingRel.relationType === newRel.relationType
          )
      );
  
      // Insert new relations
      for (const relation of newRelations) {
        await conn.execute(
          "INSERT INTO relations (from_entity, to_entity, relationType) VALUES (?, ?, ?)",
          [relation.from, relation.to, relation.relationType]
        );
      }
  
      // Commit transaction
      await conn.execute("COMMIT");
  
      return newRelations;
    } catch (error: unknown) {
      // Rollback in case of error
      await conn.execute("ROLLBACK");
      this.logger.error("Error creating relations", extractError(error));
      throw error;
    }
  }

• src/server.ts:43-63 (registration)

  Registers the MCP tool 'create_relations' with input schema validation using Zod (array of RelationObject) and a handler that delegates to the knowledgeGraphManager.createRelations method.

  server.tool(
    "create_relations",
    "Create multiple new relations between entities in the knowledge graph. Relations should be in active voice",
    {
      relations: z
        .array(RelationObject)
        .describe("An array of relations to create"),
    },
    async ({ relations }) => ({
      content: [
        {
          type: "text",
          text: JSON.stringify(
            await knowledgeGraphManager.createRelations(relations),
            null,
            2
          ),
        },
      ],
    })
  );

• src/types.ts:20-29 (schema)

  Zod schema (RelationObject) and TypeScript type (Relation) definitions for the input parameter used in create_relations tool.

  export const RelationObject = z.object({
    from: z.string().describe("The name of the entity where the relation starts"),
    to: z.string().describe("The name of the entity where the relation ends"),
    relationType: z.string().describe("The type of the relation"),
  });
  export type Relation = {
    from: string;
    to: string;
    relationType: string;
  };

• src/types.ts:57-57 (schema)

  Interface definition in KnowledgeGraphManagerInterface for the createRelations method signature.

  createRelations(relations: Relation[]): Promise<Relation[]>;