add_observations

Instructions

Implementation Reference

• storage/MarkdownStorageManager.ts:202-242 (handler)

  Core handler function that implements the add_observations tool logic: loads entity, filters duplicates, appends new observations, reloads relations, and saves the updated markdown file for each entity.

  async addObservations(observations: { entityName: string; contents: string[] }[]): Promise<{ entityName: string; addedObservations: string[] }[]> {
    const results: { entityName: string; addedObservations: string[] }[] = [];
    
    for (const obs of observations) {
      const entityPath = getEntityPath(obs.entityName);
      
      try {
        // Load current entity
        const entity = await this.loadEntity(entityPath);
        if (!entity) {
          throw new Error(`Entity ${obs.entityName} not found`);
        }
        
        // Filter out duplicate observations
        const newObservations = obs.contents.filter(
          content => !entity.observations.includes(content)
        );
        
        if (newObservations.length > 0) {
          // Update entity
          entity.observations.push(...newObservations);
          
          // Get current relations for this entity
          const graph = await this.loadGraph();
          const entityRelations = graph.relations.filter(r => r.from === entity.name);
          
          // Save updated entity
          await this.saveEntity(entity, entityRelations);
          
          results.push({
            entityName: obs.entityName,
            addedObservations: newObservations
          });
        }
      } catch (error) {
        throw new Error(`Failed to add observations to ${obs.entityName}: ${error}`);
      }
    }
    
    return results;
  }

• index.ts:80-100 (schema)

  Input schema defining the structure for add_observations tool: array of objects with entityName (string) and contents (array of strings).

  inputSchema: {
    type: "object",
    properties: {
      observations: {
        type: "array",
        items: {
          type: "object",
          properties: {
            entityName: { type: "string", description: "The name of the entity to add the observations to" },
            contents: { 
              type: "array", 
              items: { type: "string" },
              description: "An array of observation contents to add"
            },
          },
          required: ["entityName", "contents"],
        },
      },
    },
    required: ["observations"],
  },

• index.ts:77-101 (registration)

  Tool registration in the ListTools response, including name, description, and input schema.

  {
    name: "add_observations",
    description: "Add new observations to existing entities in the knowledge graph",
    inputSchema: {
      type: "object",
      properties: {
        observations: {
          type: "array",
          items: {
            type: "object",
            properties: {
              entityName: { type: "string", description: "The name of the entity to add the observations to" },
              contents: { 
                type: "array", 
                items: { type: "string" },
                description: "An array of observation contents to add"
              },
            },
            required: ["entityName", "contents"],
          },
        },
      },
      required: ["observations"],
    },
  },

• index.ts:215-216 (handler)

  MCP server dispatch handler for add_observations tool call, which invokes the storage manager method and formats the response.

  case "add_observations":
    return { content: [{ type: "text", text: JSON.stringify(await storageManager.addObservations(args.observations as { entityName: string; contents: string[] }[]), null, 2) }] };