MCP DuckDB Knowledge Graph Memory Server

Instructions

Implementation Reference

• src/manager.ts:531-592 (handler)

  The core handler function for searching nodes using Fuse.js fuzzy search on entity names, types, and observations, then retrieving related relations from DuckDB.

  async searchNodes(query: string): Promise<KnowledgeGraph> {
    if (!query || query.trim() === "") {
      return { entities: [], relations: [] };
    }
  
    // Get all entities
    const allEntities = await this.getAllEntities();
  
    // Update Fuse.js collection
    this.fuse.setCollection(allEntities);
  
    // Execute search
    const results = this.fuse.search(query);
  
    // Extract entities from search results (remove duplicates)
    const uniqueEntities = new Map<string, Entity>();
    for (const result of results) {
      if (!uniqueEntities.has(result.item.name)) {
        uniqueEntities.set(result.item.name, result.item);
      }
    }
  
    const entities = Array.from(uniqueEntities.values());
  
    // Create a set of entity names
    const entityNames = entities.map((entity) => entity.name);
  
    if (entityNames.length === 0) {
      return { entities: [], relations: [] };
    }
  
    // Create placeholders
    const placeholders = entityNames.map(() => "?").join(",");
  
    using conn = await this.getConn();
  
    // Get related relations
    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,
    };
  }

• src/server.ts:159-181 (registration)

  Registers the 'search_nodes' tool with the MCP server, defining its name, description, input schema (query string), and handler that delegates to the manager.

  server.tool(
    "search_nodes",
    "Search for nodes in the knowledge graph based on a query",
    {
      query: z
        .string()
        .describe(
          "The search query to match against entity names, types, and observation content"
        ),
    },
    async ({ query }) => ({
      content: [
        {
          type: "text",
          text: JSON.stringify(
            await knowledgeGraphManager.searchNodes(query),
            null,
            2
          ),
        },
      ],
    })
  );

• src/types.ts:55-64 (schema)

  TypeScript interface defining the KnowledgeGraphManagerInterface, including the searchNodes method signature for type safety.

  export type KnowledgeGraphManagerInterface = {
    createEntities(entities: Entity[]): Promise<Entity[]>;
    createRelations(relations: Relation[]): Promise<Relation[]>;
    addObservations(observations: Array<Observation>): Promise<Observation[]>;
    deleteEntities(entityNames: string[]): Promise<void>;
    deleteObservations(deletions: Array<Observation>): Promise<void>;
    deleteRelations(relations: Relation[]): Promise<void>;
    searchNodes(query: string): Promise<KnowledgeGraph>;
    openNodes(names: string[]): Promise<KnowledgeGraph>;
  };

• src/types.ts:47-50 (schema)

  Type definition for KnowledgeGraph, the return type of searchNodes.

  export type KnowledgeGraph = {
    entities: Entity[];
    relations: Relation[];
  };