collective-memory-mcp 0.1.0 → 0.3.0

package/src/server.js

@@ -0,0 +1,793 @@
+/**
+ * Collective Memory MCP Server
+ * A persistent, graph-based memory system for AI agents.
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { getStorage } from "./storage.js";
+import { Entity, Relation, ENTITY_TYPES, RELATION_TYPES } from "./models.js";
+
+/**
+ * Create and configure the MCP server
+ */
+function createServer() {
+  const storage = getStorage();
+
+  const server = new Server(
+    {
+      name: "collective-memory",
+      version: "0.1.0",
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  /**
+   * List available tools
+   */
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        {
+          name: "create_entities",
+          description:
+            "Create multiple new entities in the knowledge graph. " +
+            "Silently ignores entities with duplicate names. Returns list of successfully created entities. " +
+            "Valid entity types: agent, task, structure, artifact, session",
+          inputSchema: {
+            type: "object",
+            properties: {
+              entities: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    name: {
+                      type: "string",
+                      description: "Unique entity name",
+                    },
+                    entityType: {
+                      type: "string",
+                      enum: ENTITY_TYPES,
+                      description: "Type of entity",
+                    },
+                    observations: {
+                      type: "array",
+                      items: { type: "string" },
+                      description: "List of atomic facts about this entity",
+                    },
+                  },
+                  required: ["name", "entityType"],
+                },
+              },
+            },
+            required: ["entities"],
+          },
+        },
+        {
+          name: "create_relations",
+          description:
+            "Create multiple directed relations between entities. " +
+            "Skips duplicate relations. Fails gracefully if source or target entity doesn't exist. " +
+            "Valid relation types: executed_by, created, modified, documented, depends_on, part_of, similar_to, uses, implements",
+          inputSchema: {
+            type: "object",
+            properties: {
+              relations: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    from: {
+                      type: "string",
+                      description: "Source entity name",
+                    },
+                    to: {
+                      type: "string",
+                      description: "Target entity name",
+                    },
+                    relationType: {
+                      type: "string",
+                      enum: RELATION_TYPES,
+                      description: "Type of relation",
+                    },
+                  },
+                  required: ["from", "to", "relationType"],
+                },
+              },
+            },
+            required: ["relations"],
+          },
+        },
+        {
+          name: "add_observations",
+          description:
+            "Add new observations to existing entities. " +
+            "Appends observations to existing list. Fails if entity doesn't exist. " +
+            "Returns count of added observations per entity.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              observations: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    entityName: {
+                      type: "string",
+                      description: "Name of the entity",
+                    },
+                    contents: {
+                      type: "array",
+                      items: { type: "string" },
+                      description: "Observations to add",
+                    },
+                  },
+                  required: ["entityName", "contents"],
+                },
+              },
+            },
+            required: ["observations"],
+          },
+        },
+        {
+          name: "delete_entities",
+          description:
+            "Remove entities and cascade delete their relations. " +
+            "Removes all relations where entity is source or target. " +
+            "Silent operation if entity doesn't exist. Irreversible operation.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              entityNames: {
+                type: "array",
+                items: { type: "string" },
+                description: "Names of entities to delete",
+              },
+            },
+            required: ["entityNames"],
+          },
+        },
+        {
+          name: "delete_observations",
+          description:
+            "Remove specific observations from entities. " +
+            "Removes exact string matches. Silent if observation doesn't exist. " +
+            "Preserves other observations on the entity.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              deletions: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    entityName: {
+                      type: "string",
+                      description: "Name of the entity",
+                    },
+                    observations: {
+                      type: "array",
+                      items: { type: "string" },
+                      description: "Observations to remove (exact matches)",
+                    },
+                  },
+                  required: ["entityName", "observations"],
+                },
+              },
+            },
+            required: ["deletions"],
+          },
+        },
+        {
+          name: "delete_relations",
+          description:
+            "Remove specific relations from the graph. " +
+            "Requires exact match of all three fields. Silent if relation doesn't exist. " +
+            "Does not affect entities, only the connection.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              relations: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    from: { type: "string", description: "Source entity name" },
+                    to: { type: "string", description: "Target entity name" },
+                    relationType: { type: "string", description: "Type of relation" },
+                  },
+                  required: ["from", "to", "relationType"],
+                },
+              },
+            },
+            required: ["relations"],
+          },
+        },
+        {
+          name: "read_graph",
+          description:
+            "Read the entire knowledge graph. " +
+            "Returns all entities and relations. Useful for debugging, inspection, " +
+            "generating graph visualizations, and exporting memory for analysis.",
+          inputSchema: {
+            type: "object",
+            properties: {},
+          },
+        },
+        {
+          name: "search_collective_memory",
+          description:
+            "Search for relevant past work based on a natural language query. " +
+            "Search scope includes entity names, entity types, all observation content, and relation types. " +
+            "Returns entities with their immediate relations, ordered by relevance.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description: "Natural language search query",
+              },
+            },
+            required: ["query"],
+          },
+        },
+        {
+          name: "open_nodes",
+          description:
+            "Retrieve specific nodes by exact name match. " +
+            "Returns only requested entities and includes relations between returned entities. " +
+            "Silently skips non-existent nodes.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              names: {
+                type: "array",
+                items: { type: "string" },
+                description: "Entity names to retrieve",
+              },
+            },
+            required: ["names"],
+          },
+        },
+        {
+          name: "record_task_completion",
+          description:
+            "[Primary tool for agents] Document a completed task with full context. " +
+            "Automatically creates the task entity, agent entity if needed, all artifact entities, " +
+            "and establishes all relevant relations (executed_by, created, modified, part_of). " +
+            "Returns the complete task node with all relations.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              agent_name: {
+                type: "string",
+                description: "Name of the agent completing the task",
+              },
+              task_name: {
+                type: "string",
+                description: "Unique name for the task",
+              },
+              task_type: {
+                type: "string",
+                description: "Type of task (e.g., implementation, debugging, refactoring)",
+              },
+              description: {
+                type: "string",
+                description: "High-level description of what was accomplished",
+              },
+              observations: {
+                type: "array",
+                items: { type: "string" },
+                description: "Detailed observations about the task execution",
+              },
+              created_artifacts: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    name: { type: "string" },
+                    observations: {
+                      type: "array",
+                      items: { type: "string" },
+                    },
+                  },
+                  required: ["name"],
+                },
+                description: "Artifacts created during the task",
+              },
+              modified_structures: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    name: { type: "string" },
+                    observations: {
+                      type: "array",
+                      items: { type: "string" },
+                    },
+                  },
+                  required: ["name"],
+                },
+                description: "Structures modified during the task",
+              },
+              session_id: {
+                type: "string",
+                description: "Optional session identifier",
+              },
+            },
+            required: ["agent_name", "task_name"],
+          },
+        },
+        {
+          name: "find_similar_procedures",
+          description:
+            "Search for tasks that match a procedural query and return their full implementation details. " +
+            "Searches task entities and observations. Returns complete subgraphs (tasks + related artifacts + structures). " +
+            "Sorted by relevance and recency.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description: "Procedural search query (e.g., 'authentication implementation')",
+              },
+            },
+            required: ["query"],
+          },
+        },
+      ],
+    };
+  });
+
+  /**
+   * Handle tool calls
+   */
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    try {
+      switch (name) {
+        case "create_entities":
+          return { content: [{ type: "text", text: JSON.stringify(createEntities(args), null, 2) }] };
+
+        case "create_relations":
+          return { content: [{ type: "text", text: JSON.stringify(createRelations(args), null, 2) }] };
+
+        case "add_observations":
+          return { content: [{ type: "text", text: JSON.stringify(addObservations(args), null, 2) }] };
+
+        case "delete_entities":
+          return { content: [{ type: "text", text: JSON.stringify(deleteEntities(args), null, 2) }] };
+
+        case "delete_observations":
+          return { content: [{ type: "text", text: JSON.stringify(deleteObservations(args), null, 2) }] };
+
+        case "delete_relations":
+          return { content: [{ type: "text", text: JSON.stringify(deleteRelations(args), null, 2) }] };
+
+        case "read_graph":
+          return { content: [{ type: "text", text: JSON.stringify(readGraph(), null, 2) }] };
+
+        case "search_collective_memory":
+          return { content: [{ type: "text", text: JSON.stringify(searchCollectiveMemory(args), null, 2) }] };
+
+        case "open_nodes":
+          return { content: [{ type: "text", text: JSON.stringify(openNodes(args), null, 2) }] };
+
+        case "record_task_completion":
+          return { content: [{ type: "text", text: JSON.stringify(recordTaskCompletion(args), null, 2) }] };
+
+        case "find_similar_procedures":
+          return { content: [{ type: "text", text: JSON.stringify(findSimilarProcedures(args), null, 2) }] };
+
+        default:
+          throw new Error(`Unknown tool: ${name}`);
+      }
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              status: "error",
+              message: error.message,
+            }),
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+
+  // ========== Tool Implementations ==========
+
+  function createEntities({ entities = [] }) {
+    const created = [];
+
+    for (const data of entities) {
+      const { name, entityType, observations = [] } = data;
+
+      if (!name || !entityType) continue;
+      if (!ENTITY_TYPES.includes(entityType)) continue;
+
+      const entity = new Entity({ name, entityType, observations });
+      if (storage.createEntity(entity)) {
+        created.push(name);
+      }
+    }
+
+    return { status: "success", created_entities: created, count: created.length };
+  }
+
+  function createRelations({ relations = [] }) {
+    const created = [];
+
+    for (const data of relations) {
+      const { from, to, relationType } = data;
+
+      if (!from || !to || !relationType) continue;
+
+      // Verify entities exist
+      if (!storage.entityExists(from) || !storage.entityExists(to)) continue;
+
+      const relation = new Relation({ from, to, relationType });
+      if (storage.createRelation(relation)) {
+        created.push(`${from} -> ${to} (${relationType})`);
+      }
+    }
+
+    return { status: "success", created_relations: created, count: created.length };
+  }
+
+  function addObservations({ observations = [] }) {
+    const results = {};
+
+    for (const data of observations) {
+      const { entityName, contents = [] } = data;
+
+      if (!entityName) {
+        continue;
+      }
+
+      const entity = storage.getEntity(entityName);
+      if (!entity) {
+        results[entityName] = { error: "Entity not found" };
+        continue;
+      }
+
+      // Add new observations (avoid duplicates)
+      const newObs = contents.filter((o) => !entity.observations.includes(o));
+      entity.observations.push(...newObs);
+
+      if (storage.updateEntity(entityName, { observations: entity.observations })) {
+        results[entityName] = { added: newObs.length };
+      } else {
+        results[entityName] = { error: "Failed to update" };
+      }
+    }
+
+    return { status: "success", results };
+  }
+
+  function deleteEntities({ entityNames = [] }) {
+    const count = storage.deleteEntities(entityNames);
+    return { status: "success", deleted_count: count };
+  }
+
+  function deleteObservations({ deletions = [] }) {
+    const results = {};
+
+    for (const data of deletions) {
+      const { entityName, observations: toRemove = [] } = data;
+
+      const entity = storage.getEntity(entityName);
+      if (!entity) {
+        results[entityName] = { error: "Entity not found" };
+        continue;
+      }
+
+      // Remove exact matches
+      const originalCount = entity.observations.length;
+      entity.observations = entity.observations.filter((o) => !toRemove.includes(o));
+      const removedCount = originalCount - entity.observations.length;
+
+      storage.updateEntity(entityName, { observations: entity.observations });
+      results[entityName] = { removed: removedCount };
+    }
+
+    return { status: "success", results };
+  }
+
+  function deleteRelations({ relations = [] }) {
+    const toDelete = relations.map((r) => [r.from, r.to, r.relationType]);
+    const count = storage.deleteRelations(toDelete);
+    return { status: "success", deleted_count: count };
+  }
+
+  function readGraph() {
+    const entities = storage.getAllEntities().map((e) => e.toJSON());
+    const relations = storage.getAllRelations().map((r) => r.toJSON());
+
+    return {
+      entities,
+      relations,
+      summary: {
+        entity_count: entities.length,
+        relation_count: relations.length,
+      },
+    };
+  }
+
+  function searchCollectiveMemory({ query = "" }) {
+    const matchingEntities = storage.searchEntities(query);
+
+    const results = matchingEntities.map((entity) => {
+      const related = storage.getRelatedEntities(entity.name);
+      return {
+        name: entity.name,
+        entityType: entity.entityType,
+        observations: entity.observations,
+        createdAt: entity.createdAt,
+        related_entities: related.connected.map((e) => ({
+          name: e.name,
+          entityType: e.entityType,
+        })),
+      };
+    });
+
+    return { matching_entities: results, count: results.length };
+  }
+
+  function openNodes({ names = [] }) {
+    const entities = [];
+    const entityNamesSet = new Set();
+
+    for (const name of names) {
+      const entity = storage.getEntity(name);
+      if (entity) {
+        entities.push(entity.toJSON());
+        entityNamesSet.add(name);
+      }
+    }
+
+    // Get relations between requested entities
+    const allRelations = storage.getAllRelations();
+    const filteredRelations = allRelations
+      .filter((r) => entityNamesSet.has(r.from) && entityNamesSet.has(r.to))
+      .map((r) => r.toJSON());
+
+    return {
+      entities,
+      relations_between_requested_nodes: filteredRelations,
+    };
+  }
+
+  function recordTaskCompletion({
+    agent_name,
+    task_name,
+    task_type = "task",
+    description = "",
+    observations = [],
+    created_artifacts = [],
+    modified_structures = [],
+    session_id = null,
+  }) {
+    if (!agent_name || !task_name) {
+      return {
+        status: "error",
+        message: "agent_name and task_name are required",
+      };
+    }
+
+    // Ensure agent entity exists
+    let agentEntity = storage.getEntity(agent_name);
+    if (!agentEntity) {
+      agentEntity = new Entity({
+        name: agent_name,
+        entityType: "agent",
+        observations: [`Created during task ${task_name}`],
+      });
+      storage.createEntity(agentEntity);
+    }
+
+    // Create task entity
+    const taskObservations = [...observations];
+    if (description) {
+      taskObservations.unshift(`Description: ${description}`);
+    }
+
+    const taskEntity = new Entity({
+      name: task_name,
+      entityType: "task",
+      observations: taskObservations,
+      metadata: { task_type },
+    });
+    storage.createEntity(taskEntity);
+
+    // Create executed_by relation
+    storage.createRelation(
+      new Relation({
+        from: task_name,
+        to: agent_name,
+        relationType: "executed_by",
+      })
+    );
+
+    // Handle session
+    if (session_id) {
+      let sessionEntity = storage.getEntity(session_id);
+      if (!sessionEntity) {
+        sessionEntity = new Entity({
+          name: session_id,
+          entityType: "session",
+          observations: [`Started for task ${task_name}`],
+        });
+        storage.createEntity(sessionEntity);
+      }
+
+      storage.createRelation(
+        new Relation({
+          from: task_name,
+          to: session_id,
+          relationType: "part_of",
+        })
+      );
+    }
+
+    // Create artifacts
+    const createdArtifactNames = [];
+    for (const artifactData of created_artifacts) {
+      const { name: artifactName, observations: artifactObs = [] } = artifactData;
+      if (!artifactName) continue;
+
+      let artifactEntity;
+      if (!storage.entityExists(artifactName)) {
+        artifactEntity = new Entity({
+          name: artifactName,
+          entityType: "artifact",
+          observations: artifactObs,
+        });
+        storage.createEntity(artifactEntity);
+      } else {
+        artifactEntity = storage.getEntity(artifactName);
+        const newObs = artifactObs.filter((o) => !artifactEntity.observations.includes(o));
+        artifactEntity.observations.push(...newObs);
+        storage.updateEntity(artifactName, { observations: artifactEntity.observations });
+      }
+
+      storage.createRelation(
+        new Relation({
+          from: task_name,
+          to: artifactName,
+          relationType: "created",
+        })
+      );
+      createdArtifactNames.push(artifactName);
+    }
+
+    // Handle modified structures
+    for (const structureData of modified_structures) {
+      const { name: structureName, observations: structureObs = [] } = structureData;
+      if (!structureName) continue;
+
+      let relationType;
+      if (!storage.entityExists(structureName)) {
+        const structureEntity = new Entity({
+          name: structureName,
+          entityType: "structure",
+          observations: structureObs,
+        });
+        storage.createEntity(structureEntity);
+        relationType = "documented";
+      } else {
+        const existing = storage.getEntity(structureName);
+        const newObs = structureObs.filter((o) => !existing.observations.includes(o));
+        if (newObs.length > 0) {
+          existing.observations.push(...newObs);
+          storage.updateEntity(structureName, { observations: existing.observations });
+        }
+        relationType = "modified";
+      }
+
+      storage.createRelation(
+        new Relation({
+          from: task_name,
+          to: structureName,
+          relationType,
+        })
+      );
+    }
+
+    // Build response
+    const taskRelations = storage.getRelations({ fromEntity: task_name });
+
+    return {
+      status: "success",
+      task: taskEntity.toJSON(),
+      relations: taskRelations.map((r) => r.toJSON()),
+      created_artifacts: createdArtifactNames,
+    };
+  }
+
+  function findSimilarProcedures({ query = "" }) {
+    const searchQuery = query.toLowerCase();
+
+    // Search for matching task entities
+    const allEntities = storage.getAllEntities();
+    const matchingTasks = allEntities.filter(
+      (e) =>
+        e.entityType === "task" &&
+        (e.name.toLowerCase().includes(searchQuery) ||
+          e.observations.some((obs) => obs.toLowerCase().includes(searchQuery)))
+    );
+
+    const results = [];
+    for (const task of matchingTasks) {
+      const taskRelations = storage.getRelations({ fromEntity: task.name });
+
+      const artifacts = [];
+      const structures = [];
+
+      for (const rel of taskRelations) {
+        if (rel.relationType === "created" || rel.relationType === "uses") {
+          const artifact = storage.getEntity(rel.to);
+          if (artifact) artifacts.push(artifact.toJSON());
+        } else if (rel.relationType === "modified" || rel.relationType === "documented") {
+          const structure = storage.getEntity(rel.to);
+          if (structure) structures.push(structure.toJSON());
+        }
+      }
+
+      // Get execution context (agent info)
+      let agentName = null;
+      for (const rel of taskRelations) {
+        if (rel.relationType === "executed_by") {
+          agentName = rel.to;
+          break;
+        }
+      }
+
+      const executionContext = {};
+      if (agentName) {
+        const agent = storage.getEntity(agentName);
+        if (agent) {
+          executionContext.agent = agent.toJSON();
+        }
+      }
+
+      results.push({
+        task: task.toJSON(),
+        artifacts,
+        structures,
+        execution_context: executionContext,
+      });
+    }
+
+    return { similar_tasks: results, count: results.length };
+  }
+
+  return server;
+}
+
+/**
+ * Main entry point
+ */
+async function main() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});