MCP DuckDB Knowledge Graph Memory Server

Instructions

Implementation Reference

• src/manager.ts:630-716 (handler)

  Implementation of the openNodes method in KnowledgeGraphManager. Retrieves entities by names using SQL queries, groups observations, fetches related relations, and returns a KnowledgeGraph.

  async openNodes(names: string[]): Promise<KnowledgeGraph> {
    if (names.length === 0) {
      return { entities: [], relations: [] };
    }
  
    try {
      using conn = await this.getConn();
  
      // Create placeholders
      const placeholders = names.map(() => "?").join(",");
  
      // Retrieve entities and observations at once using LEFT JOIN
      const reader = await conn.executeAndReadAll(
        `
        SELECT e.name, e.entityType, o.content
        FROM entities e
        LEFT JOIN observations o ON e.name = o.entityName
        WHERE e.name IN (${placeholders})
      `,
        names
      );
      const rows = reader.getRows();
  
      // Group results by entity
      const entitiesMap = new Map<string, Entity>();
  
      for (const row of rows) {
        const name = row[0] as string;
        const entityType = row[1] as string;
        const content = row[2] as string | null;
  
        if (!entitiesMap.has(name)) {
          // Create a new entity
          entitiesMap.set(name, {
            name,
            entityType,
            observations: content ? [content] : [],
          });
        } else if (content) {
          // Add observation to existing entity
          entitiesMap.get(name)!.observations.push(content);
        }
      }
  
      const entities = Array.from(entitiesMap.values());
  
      // Create a set of entity names
      const entityNames = entities.map((entity) => entity.name);
  
      // Get related relations
      if (entityNames.length > 0) {
        const placeholders = entityNames.map(() => "?").join(",");
        const relationsReader = await conn.executeAndReadAll(
          `
        SELECT from_entity as "from", to_entity as "to", relationType
        FROM relations
        WHERE from_entity IN (${placeholders})
        OR to_entity IN (${placeholders})
        `,
          [...entityNames, ...entityNames]
        );
        const relationsData = relationsReader.getRows();
  
        // Convert results to an array of Relation objects
        const relations = relationsData.map((row: any) => {
          return {
            from: row[0] as string,
            to: row[1] as string,
            relationType: row[2] as string,
          };
        });
  
        return {
          entities,
          relations,
        };
      } else {
        return {
          entities,
          relations: [],
        };
      }
    } catch (error: unknown) {
      this.logger.error("Error opening nodes", extractError(error));
      return { entities: [], relations: [] };
    }
  }

• src/server.ts:184-204 (registration)

  Registers the 'open_nodes' MCP tool with server.tool, defining input schema (array of strings for names) and delegating execution to knowledgeGraphManager.openNodes.

  server.tool(
    "open_nodes",
    "Open specific nodes in the knowledge graph by their names",
    {
      names: z
        .array(z.string())
        .describe("An array of entity names to retrieve"),
    },
    async ({ names }) => ({
      content: [
        {
          type: "text",
          text: JSON.stringify(
            await knowledgeGraphManager.openNodes(names),
            null,
            2
          ),
        },
      ],
    })
  );

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

  TypeScript interface definition for the openNodes method in KnowledgeGraphManager.

  openNodes(names: string[]): Promise<KnowledgeGraph>;