diff --git a/src/memory/index.ts b/src/memory/index.ts new file mode 100644 index 00000000..37546cd7 --- /dev/null +++ b/src/memory/index.ts @@ -0,0 +1,414 @@ +#!/usr/bin/env node + +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 { promises as fs } from 'fs'; +import path from 'path'; +import { fileURLToPath } from 'url'; + + +// Define the path to the JSONL file, you can change this to your desired local path +const __dirname = path.dirname(fileURLToPath(import.meta.url)); +const MEMORY_FILE_PATH = path.join(__dirname, 'memory.json'); + +// We are storing our memory using entities, relations, and observations in a graph structure +interface Entity { + name: string; + entityType: string; + observations: string[]; +} + +interface Relation { + from: string; + to: string; + relationType: string; +} + +interface KnowledgeGraph { + entities: Entity[]; + relations: Relation[]; +} + +// The KnowledgeGraphManager class contains all operations to interact with the knowledge graph +class KnowledgeGraphManager { + private async loadGraph(): Promise { + try { + const data = await fs.readFile(MEMORY_FILE_PATH, "utf-8"); + const lines = data.split("\n").filter(line => line.trim() !== ""); + return lines.reduce((graph: KnowledgeGraph, line) => { + const item = JSON.parse(line); + if (item.type === "entity") graph.entities.push(item as Entity); + if (item.type === "relation") graph.relations.push(item as Relation); + return graph; + }, { entities: [], relations: [] }); + } catch (error) { + if (error instanceof Error && 'code' in error && (error as any).code === "ENOENT") { + return { entities: [], relations: [] }; + } + throw error; + } + } + + private async saveGraph(graph: KnowledgeGraph): Promise { + const lines = [ + ...graph.entities.map(e => JSON.stringify({ type: "entity", ...e })), + ...graph.relations.map(r => JSON.stringify({ type: "relation", ...r })), + ]; + await fs.writeFile(MEMORY_FILE_PATH, lines.join("\n")); + } + + async createEntities(entities: Entity[]): Promise { + const graph = await this.loadGraph(); + const newEntities = entities.filter(e => !graph.entities.some(existingEntity => existingEntity.name === e.name)); + graph.entities.push(...newEntities); + await this.saveGraph(graph); + return newEntities; + } + + async createRelations(relations: Relation[]): Promise { + const graph = await this.loadGraph(); + const newRelations = relations.filter(r => !graph.relations.some(existingRelation => + existingRelation.from === r.from && + existingRelation.to === r.to && + existingRelation.relationType === r.relationType + )); + graph.relations.push(...newRelations); + await this.saveGraph(graph); + return newRelations; + } + + async addObservations(observations: { entityName: string; contents: string[] }[]): Promise<{ entityName: string; addedObservations: string[] }[]> { + const graph = await this.loadGraph(); + const results = observations.map(o => { + const entity = graph.entities.find(e => e.name === o.entityName); + if (!entity) { + throw new Error(`Entity with name ${o.entityName} not found`); + } + const newObservations = o.contents.filter(content => !entity.observations.includes(content)); + entity.observations.push(...newObservations); + return { entityName: o.entityName, addedObservations: newObservations }; + }); + await this.saveGraph(graph); + return results; + } + + async deleteEntities(entityNames: string[]): Promise { + const graph = await this.loadGraph(); + graph.entities = graph.entities.filter(e => !entityNames.includes(e.name)); + graph.relations = graph.relations.filter(r => !entityNames.includes(r.from) && !entityNames.includes(r.to)); + await this.saveGraph(graph); + } + + async deleteObservations(deletions: { entityName: string; observations: string[] }[]): Promise { + const graph = await this.loadGraph(); + deletions.forEach(d => { + const entity = graph.entities.find(e => e.name === d.entityName); + if (entity) { + entity.observations = entity.observations.filter(o => !d.observations.includes(o)); + } + }); + await this.saveGraph(graph); + } + + async deleteRelations(relations: Relation[]): Promise { + const graph = await this.loadGraph(); + graph.relations = graph.relations.filter(r => !relations.some(delRelation => + r.from === delRelation.from && + r.to === delRelation.to && + r.relationType === delRelation.relationType + )); + await this.saveGraph(graph); + } + + async readGraph(): Promise { + return this.loadGraph(); + } + + // Very basic search function + async searchNodes(query: string): Promise { + const graph = await this.loadGraph(); + + // Filter entities + const filteredEntities = graph.entities.filter(e => + e.name.toLowerCase().includes(query.toLowerCase()) || + e.entityType.toLowerCase().includes(query.toLowerCase()) || + e.observations.some(o => o.toLowerCase().includes(query.toLowerCase())) + ); + + // Create a Set of filtered entity names for quick lookup + const filteredEntityNames = new Set(filteredEntities.map(e => e.name)); + + // Filter relations to only include those between filtered entities + const filteredRelations = graph.relations.filter(r => + filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to) + ); + + const filteredGraph: KnowledgeGraph = { + entities: filteredEntities, + relations: filteredRelations, + }; + + return filteredGraph; + } + + async openNodes(names: string[]): Promise { + const graph = await this.loadGraph(); + + // Filter entities + const filteredEntities = graph.entities.filter(e => names.includes(e.name)); + + // Create a Set of filtered entity names for quick lookup + const filteredEntityNames = new Set(filteredEntities.map(e => e.name)); + + // Filter relations to only include those between filtered entities + const filteredRelations = graph.relations.filter(r => + filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to) + ); + + const filteredGraph: KnowledgeGraph = { + entities: filteredEntities, + relations: filteredRelations, + }; + + return filteredGraph; + } +} + +const knowledgeGraphManager = new KnowledgeGraphManager(); + + +// The server instance and tools exposed to Claude +const server = new Server({ + name: "knowledge-graph-server", + version: "1.0.0", +}, { + capabilities: { + tools: {}, + }, + },); + +server.setRequestHandler(ListToolsRequestSchema, async () => { + return { + tools: [ + { + name: "create_entities", + description: "Create multiple new entities in the knowledge graph", + inputSchema: { + type: "object", + properties: { + entities: { + type: "array", + items: { + type: "object", + properties: { + name: { type: "string", description: "The name of the entity" }, + entityType: { type: "string", description: "The type of the entity" }, + observations: { + type: "array", + items: { type: "string" }, + description: "An array of observation contents associated with the entity" + }, + }, + required: ["name", "entityType", "observations"], + }, + }, + }, + required: ["entities"], + }, + }, + { + name: "create_relations", + description: "Create multiple new relations between entities in the knowledge graph. Relations should be in active voice", + inputSchema: { + type: "object", + properties: { + relations: { + type: "array", + items: { + type: "object", + properties: { + from: { type: "string", description: "The name of the entity where the relation starts" }, + to: { type: "string", description: "The name of the entity where the relation ends" }, + relationType: { type: "string", description: "The type of the relation" }, + }, + required: ["from", "to", "relationType"], + }, + }, + }, + required: ["relations"], + }, + }, + { + 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"], + }, + }, + { + name: "delete_entities", + description: "Delete multiple entities and their associated relations from the knowledge graph", + inputSchema: { + type: "object", + properties: { + entityNames: { + type: "array", + items: { type: "string" }, + description: "An array of entity names to delete" + }, + }, + required: ["entityNames"], + }, + }, + { + name: "delete_observations", + description: "Delete specific observations from entities in the knowledge graph", + inputSchema: { + type: "object", + properties: { + deletions: { + type: "array", + items: { + type: "object", + properties: { + entityName: { type: "string", description: "The name of the entity containing the observations" }, + observations: { + type: "array", + items: { type: "string" }, + description: "An array of observations to delete" + }, + }, + required: ["entityName", "observations"], + }, + }, + }, + required: ["deletions"], + }, + }, + { + name: "delete_relations", + description: "Delete multiple relations from the knowledge graph", + inputSchema: { + type: "object", + properties: { + relations: { + type: "array", + items: { + type: "object", + properties: { + from: { type: "string", description: "The name of the entity where the relation starts" }, + to: { type: "string", description: "The name of the entity where the relation ends" }, + relationType: { type: "string", description: "The type of the relation" }, + }, + required: ["from", "to", "relationType"], + }, + description: "An array of relations to delete" + }, + }, + required: ["relations"], + }, + }, + { + name: "read_graph", + description: "Read the entire knowledge graph", + inputSchema: { + type: "object", + properties: {}, + }, + }, + { + name: "search_nodes", + description: "Search for nodes in the knowledge graph based on a query", + inputSchema: { + type: "object", + properties: { + query: { type: "string", description: "The search query to match against entity names, types, and observation content" }, + }, + required: ["query"], + }, + }, + { + name: "open_nodes", + description: "Open specific nodes in the knowledge graph by their names", + inputSchema: { + type: "object", + properties: { + names: { + type: "array", + items: { type: "string" }, + description: "An array of entity names to retrieve", + }, + }, + required: ["names"], + }, + }, + ], + }; +}); + +server.setRequestHandler(CallToolRequestSchema, async (request) => { + const { name, arguments: args } = request.params; + + if (!args) { + throw new Error(`No arguments provided for tool: ${name}`); + } + + switch (name) { + case "create_entities": + return { toolResult: await knowledgeGraphManager.createEntities(args.entities as Entity[]) }; + case "create_relations": + return { toolResult: await knowledgeGraphManager.createRelations(args.relations as Relation[]) }; + case "add_observations": + return { toolResult: await knowledgeGraphManager.addObservations(args.observations as { entityName: string; contents: string[] }[]) }; + case "delete_entities": + await knowledgeGraphManager.deleteEntities(args.entityNames as string[]); + return { toolResult: "Entities deleted successfully" }; + case "delete_observations": + await knowledgeGraphManager.deleteObservations(args.deletions as { entityName: string; observations: string[] }[]); + return { toolResult: "Observations deleted successfully" }; + case "delete_relations": + await knowledgeGraphManager.deleteRelations(args.relations as Relation[]); + return { toolResult: "Relations deleted successfully" }; + case "read_graph": + return { toolResult: await knowledgeGraphManager.readGraph() }; + case "search_nodes": + return { toolResult: await knowledgeGraphManager.searchNodes(args.query as string) }; + case "open_nodes": + return { toolResult: await knowledgeGraphManager.openNodes(args.names as string[]) }; + default: + throw new Error(`Unknown tool: ${name}`); + } +}); + +async function main() { + const transport = new StdioServerTransport(); + await server.connect(transport); + console.error("Knowledge Graph MCP Server running on stdio"); +} + +main().catch((error) => { + console.error("Fatal error in main():", error); + process.exit(1); +}); \ No newline at end of file diff --git a/src/memory/package.json b/src/memory/package.json new file mode 100644 index 00000000..8cb17d27 --- /dev/null +++ b/src/memory/package.json @@ -0,0 +1,28 @@ +{ + "name": "@modelcontextprotocol/server-memory", + "version": "0.1.0", + "description": "MCP server for enabling memory for Claude through a knowledge graph", + "license": "MIT", + "author": "Anthropic, PBC (https://anthropic.com)", + "homepage": "https://modelcontextprotocol.io", + "bugs": "https://github.com/modelcontextprotocol/servers/issues", + "type": "module", + "bin": { + "mcp-server-memory": "dist/index.js" + }, + "files": [ + "dist" + ], + "scripts": { + "build": "tsc && shx chmod +x dist/*.js", + "prepare": "npm run build", + "watch": "tsc --watch" + }, + "dependencies": { + "@modelcontextprotocol/sdk": "0.5.0" + }, + "devDependencies": { + "shx": "^0.3.4", + "typescript": "^5.6.2" + } +} diff --git a/src/memory/tsconfig.json b/src/memory/tsconfig.json new file mode 100644 index 00000000..4d33cae1 --- /dev/null +++ b/src/memory/tsconfig.json @@ -0,0 +1,11 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "." + }, + "include": [ + "./**/*.ts" + ] + } + \ No newline at end of file