graph.do 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,724 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { MongoClient } from "mongo.do";
+
+// src/graph-manager.ts
+var KnowledgeGraphManager = class {
+  entities;
+  relations;
+  constructor(config) {
+    this.entities = config.entities;
+    this.relations = config.relations;
+  }
+  /**
+   * Create new entities (ignores duplicates)
+   */
+  async createEntities(entities) {
+    const created = [];
+    for (const entity of entities) {
+      const existing = await this.entities.findOne({ name: entity.name });
+      if (!existing) {
+        await this.entities.insertOne({
+          name: entity.name,
+          entityType: entity.entityType,
+          observations: entity.observations
+        });
+        created.push(entity);
+      }
+    }
+    return created;
+  }
+  /**
+   * Create new relations (skips duplicates)
+   */
+  async createRelations(relations) {
+    const created = [];
+    for (const relation of relations) {
+      const existing = await this.relations.findOne({
+        from: relation.from,
+        to: relation.to,
+        relationType: relation.relationType
+      });
+      if (!existing) {
+        await this.relations.insertOne({
+          from: relation.from,
+          to: relation.to,
+          relationType: relation.relationType
+        });
+        created.push(relation);
+      }
+    }
+    return created;
+  }
+  /**
+   * Add observations to existing entities
+   * Throws if entity doesn't exist
+   */
+  async addObservations(observations) {
+    const results = [];
+    for (const { entityName, contents } of observations) {
+      const entity = await this.entities.findOne({ name: entityName });
+      if (!entity) {
+        throw new Error(`Entity with name "${entityName}" not found`);
+      }
+      const existingObservations = new Set(entity.observations);
+      const newObservations = contents.filter((obs) => !existingObservations.has(obs));
+      if (newObservations.length > 0) {
+        await this.entities.updateOne(
+          { name: entityName },
+          { $push: { observations: { $each: newObservations } } }
+        );
+      }
+      results.push({
+        entityName,
+        addedObservations: newObservations
+      });
+    }
+    return results;
+  }
+  /**
+   * Delete entities and cascade delete their relations
+   */
+  async deleteEntities(entityNames) {
+    const deleteResult = await this.entities.deleteMany({
+      name: { $in: entityNames }
+    });
+    await this.relations.deleteMany({
+      $or: [{ from: { $in: entityNames } }, { to: { $in: entityNames } }]
+    });
+    return {
+      success: true,
+      message: `Deleted ${deleteResult.deletedCount} entities and their relations`
+    };
+  }
+  /**
+   * Delete specific observations from entities (silent on non-existent)
+   */
+  async deleteObservations(deletions) {
+    let totalRemoved = 0;
+    for (const { entityName, observations } of deletions) {
+      const entity = await this.entities.findOne({ name: entityName });
+      if (entity) {
+        const observationsToRemove = new Set(observations);
+        const remaining = entity.observations.filter((obs) => !observationsToRemove.has(obs));
+        const removed = entity.observations.length - remaining.length;
+        if (removed > 0) {
+          await this.entities.updateOne({ name: entityName }, { $set: { observations: remaining } });
+          totalRemoved += removed;
+        }
+      }
+    }
+    return {
+      success: true,
+      message: `Removed ${totalRemoved} observations`
+    };
+  }
+  /**
+   * Delete specific relations (silent on non-existent)
+   */
+  async deleteRelations(relations) {
+    let totalDeleted = 0;
+    for (const relation of relations) {
+      const result = await this.relations.deleteOne({
+        from: relation.from,
+        to: relation.to,
+        relationType: relation.relationType
+      });
+      totalDeleted += result.deletedCount;
+    }
+    return {
+      success: true,
+      message: `Deleted ${totalDeleted} relations`
+    };
+  }
+  /**
+   * Read the complete knowledge graph
+   */
+  async readGraph() {
+    const entities = await this.entities.find({}).toArray();
+    const relations = await this.relations.find({}).toArray();
+    return {
+      entities: entities.map(({ _id, ...entity }) => entity),
+      relations: relations.map(({ _id, ...relation }) => relation)
+    };
+  }
+  /**
+   * Search nodes by query (matches name, type, or observations)
+   */
+  async searchNodes(query) {
+    const lowerQuery = query.toLowerCase();
+    const allEntities = await this.entities.find({}).toArray();
+    const matchingEntities = allEntities.filter((entity) => {
+      const nameMatch = entity.name.toLowerCase().includes(lowerQuery);
+      const typeMatch = entity.entityType.toLowerCase().includes(lowerQuery);
+      const observationMatch = entity.observations.some(
+        (obs) => obs.toLowerCase().includes(lowerQuery)
+      );
+      return nameMatch || typeMatch || observationMatch;
+    });
+    const matchingNames = new Set(matchingEntities.map((e) => e.name));
+    const relations = await this.relations.find({}).toArray();
+    const matchingRelations = relations.filter(
+      (rel) => matchingNames.has(rel.from) && matchingNames.has(rel.to)
+    );
+    return {
+      entities: matchingEntities.map(({ _id, ...entity }) => entity),
+      relations: matchingRelations.map(({ _id, ...relation }) => relation)
+    };
+  }
+  /**
+   * Open specific nodes by name and return them with their inter-relations
+   */
+  async openNodes(names) {
+    const nameSet = new Set(names);
+    const entities = await this.entities.find({ name: { $in: names } }).toArray();
+    const relations = await this.relations.find({
+      from: { $in: names },
+      to: { $in: names }
+    }).toArray();
+    return {
+      entities: entities.map(({ _id, ...entity }) => entity),
+      relations: relations.map(({ _id, ...relation }) => relation)
+    };
+  }
+  /**
+   * Get a single entity by name
+   */
+  async getEntity(name) {
+    const entity = await this.entities.findOne({ name });
+    if (!entity) return null;
+    const { _id, ...rest } = entity;
+    return rest;
+  }
+  /**
+   * Get all relations for an entity
+   */
+  async getRelationsFor(entityName) {
+    const relations = await this.relations.find({
+      $or: [{ from: entityName }, { to: entityName }]
+    }).toArray();
+    return relations.map(({ _id, ...relation }) => relation);
+  }
+};
+
+// src/types.ts
+import { z } from "zod";
+var EntitySchema = z.object({
+  name: z.string().describe("Unique identifier for the entity"),
+  entityType: z.string().describe("Type classification of the entity"),
+  observations: z.array(z.string()).describe("Array of atomic facts about the entity")
+});
+var RelationSchema = z.object({
+  from: z.string().describe("Source entity name"),
+  to: z.string().describe("Target entity name"),
+  relationType: z.string().describe("Type of relationship (active voice)")
+});
+var KnowledgeGraphSchema = z.object({
+  entities: z.array(EntitySchema),
+  relations: z.array(RelationSchema)
+});
+var CreateEntitiesInputSchema = z.object({
+  entities: z.array(EntitySchema).describe("Array of entities to create")
+});
+var CreateRelationsInputSchema = z.object({
+  relations: z.array(RelationSchema).describe("Array of relations to create")
+});
+var AddObservationsInputSchema = z.object({
+  observations: z.array(
+    z.object({
+      entityName: z.string().describe("Name of the entity to add observations to"),
+      contents: z.array(z.string()).describe("Array of observations to add")
+    })
+  ).describe("Array of observation additions")
+});
+var DeleteEntitiesInputSchema = z.object({
+  entityNames: z.array(z.string()).describe("Array of entity names to delete")
+});
+var DeleteObservationsInputSchema = z.object({
+  deletions: z.array(
+    z.object({
+      entityName: z.string().describe("Name of the entity"),
+      observations: z.array(z.string()).describe("Observations to remove")
+    })
+  ).describe("Array of observation deletions")
+});
+var DeleteRelationsInputSchema = z.object({
+  relations: z.array(RelationSchema).describe("Array of relations to delete")
+});
+var SearchNodesInputSchema = z.object({
+  query: z.string().describe("Search query to match against entity names, types, and observations")
+});
+var OpenNodesInputSchema = z.object({
+  names: z.array(z.string()).describe("Array of entity names to retrieve")
+});
+
+// src/mcp/server.ts
+var McpErrorCode = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603
+};
+function createGraphMcpServer(config) {
+  const { name = "graph.do", version = "0.1.0", graphManager } = config;
+  const tools = [
+    {
+      name: "create_entities",
+      description: "Create multiple new entities in the knowledge graph. Entities are nodes with a unique name, type, and observations.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          entities: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                name: { type: "string", description: "Unique identifier for the entity" },
+                entityType: { type: "string", description: "Type classification of the entity" },
+                observations: {
+                  type: "array",
+                  items: { type: "string" },
+                  description: "Array of atomic facts about the entity"
+                }
+              },
+              required: ["name", "entityType", "observations"]
+            },
+            description: "Array of entities to create"
+          }
+        },
+        required: ["entities"]
+      }
+    },
+    {
+      name: "create_relations",
+      description: "Create multiple new relations between entities. Relations are directed edges with a type.",
+      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 relationship (active voice)"
+                }
+              },
+              required: ["from", "to", "relationType"]
+            },
+            description: "Array of relations to create"
+          }
+        },
+        required: ["relations"]
+      }
+    },
+    {
+      name: "add_observations",
+      description: "Add new observations to existing entities. Observations are atomic facts about an entity.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          observations: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                entityName: {
+                  type: "string",
+                  description: "Name of the entity to add observations to"
+                },
+                contents: {
+                  type: "array",
+                  items: { type: "string" },
+                  description: "Array of observations to add"
+                }
+              },
+              required: ["entityName", "contents"]
+            },
+            description: "Array of observation additions"
+          }
+        },
+        required: ["observations"]
+      }
+    },
+    {
+      name: "delete_entities",
+      description: "Delete multiple entities and their relations from the knowledge graph by name.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          entityNames: {
+            type: "array",
+            items: { type: "string" },
+            description: "Array of entity names to delete"
+          }
+        },
+        required: ["entityNames"]
+      }
+    },
+    {
+      name: "delete_observations",
+      description: "Delete specific observations from entities.",
+      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"
+                }
+              },
+              required: ["entityName", "observations"]
+            },
+            description: "Array of observation deletions"
+          }
+        },
+        required: ["deletions"]
+      }
+    },
+    {
+      name: "delete_relations",
+      description: "Delete specific relations from the knowledge graph.",
+      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 relationship" }
+              },
+              required: ["from", "to", "relationType"]
+            },
+            description: "Array of relations to delete"
+          }
+        },
+        required: ["relations"]
+      }
+    },
+    {
+      name: "read_graph",
+      description: "Read the entire knowledge graph including all entities and relations.",
+      inputSchema: {
+        type: "object",
+        properties: {}
+      }
+    },
+    {
+      name: "search_nodes",
+      description: "Search for nodes in the knowledge graph by matching names, types, or observations.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Search query to match against entity names, types, and observations"
+          }
+        },
+        required: ["query"]
+      }
+    },
+    {
+      name: "open_nodes",
+      description: "Open specific nodes by name and retrieve them with their inter-relations.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          names: {
+            type: "array",
+            items: { type: "string" },
+            description: "Array of entity names to retrieve"
+          }
+        },
+        required: ["names"]
+      }
+    }
+  ];
+  const toolHandlers = {
+    create_entities: async (input) => {
+      const { entities } = CreateEntitiesInputSchema.parse(input);
+      const created = await graphManager.createEntities(entities);
+      return formatGraphResponse(created, `Created ${created.length} entities`);
+    },
+    create_relations: async (input) => {
+      const { relations } = CreateRelationsInputSchema.parse(input);
+      const created = await graphManager.createRelations(relations);
+      return formatGraphResponse(created, `Created ${created.length} relations`);
+    },
+    add_observations: async (input) => {
+      const { observations } = AddObservationsInputSchema.parse(input);
+      const results = await graphManager.addObservations(observations);
+      return formatGraphResponse(results, "Observations added");
+    },
+    delete_entities: async (input) => {
+      const { entityNames } = DeleteEntitiesInputSchema.parse(input);
+      const result = await graphManager.deleteEntities(entityNames);
+      return {
+        content: [{ type: "text", text: result.message }]
+      };
+    },
+    delete_observations: async (input) => {
+      const { deletions } = DeleteObservationsInputSchema.parse(input);
+      const result = await graphManager.deleteObservations(deletions);
+      return {
+        content: [{ type: "text", text: result.message }]
+      };
+    },
+    delete_relations: async (input) => {
+      const { relations } = DeleteRelationsInputSchema.parse(input);
+      const result = await graphManager.deleteRelations(relations);
+      return {
+        content: [{ type: "text", text: result.message }]
+      };
+    },
+    read_graph: async () => {
+      const graph = await graphManager.readGraph();
+      return formatGraphResponse(graph, `Graph contains ${graph.entities.length} entities and ${graph.relations.length} relations`);
+    },
+    search_nodes: async (input) => {
+      const { query } = SearchNodesInputSchema.parse(input);
+      const graph = await graphManager.searchNodes(query);
+      return formatGraphResponse(graph, `Found ${graph.entities.length} matching entities`);
+    },
+    open_nodes: async (input) => {
+      const { names } = OpenNodesInputSchema.parse(input);
+      const graph = await graphManager.openNodes(names);
+      return formatGraphResponse(graph, `Opened ${graph.entities.length} entities`);
+    }
+  };
+  function formatGraphResponse(data, summary) {
+    return {
+      content: [
+        { type: "text", text: summary },
+        {
+          type: "resource",
+          resource: {
+            uri: "graph://result",
+            mimeType: "application/json",
+            text: JSON.stringify(data, null, 2)
+          }
+        }
+      ]
+    };
+  }
+  async function handleRequest(request) {
+    const { id, method, params } = request;
+    try {
+      switch (method) {
+        case "initialize":
+          return {
+            jsonrpc: "2.0",
+            id,
+            result: {
+              protocolVersion: "2024-11-05",
+              capabilities: {
+                tools: {}
+              },
+              serverInfo: {
+                name,
+                version
+              }
+            }
+          };
+        case "notifications/initialized":
+          return { jsonrpc: "2.0", id, result: {} };
+        case "tools/list":
+          return {
+            jsonrpc: "2.0",
+            id,
+            result: { tools }
+          };
+        case "tools/call": {
+          const toolName = params?.name;
+          const toolInput = params?.arguments ?? {};
+          const handler = toolHandlers[toolName];
+          if (!handler) {
+            return {
+              jsonrpc: "2.0",
+              id,
+              error: {
+                code: McpErrorCode.METHOD_NOT_FOUND,
+                message: `Unknown tool: ${toolName}`
+              }
+            };
+          }
+          try {
+            const result = await handler(toolInput);
+            return { jsonrpc: "2.0", id, result };
+          } catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            return {
+              jsonrpc: "2.0",
+              id,
+              result: {
+                content: [{ type: "text", text: `Error: ${error.message}` }],
+                isError: true
+              }
+            };
+          }
+        }
+        case "ping":
+          return { jsonrpc: "2.0", id, result: {} };
+        default:
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: {
+              code: McpErrorCode.METHOD_NOT_FOUND,
+              message: `Unknown method: ${method}`
+            }
+          };
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+          code: McpErrorCode.INTERNAL_ERROR,
+          message: error.message
+        }
+      };
+    }
+  }
+  return {
+    name,
+    version,
+    tools,
+    handleRequest,
+    graphManager
+  };
+}
+
+// src/mcp/stdio-transport.ts
+async function runStdioTransport(server) {
+  const stdin = process.stdin;
+  const stdout = process.stdout;
+  const stderr = process.stderr;
+  stdin.setEncoding("utf8");
+  let buffer = "";
+  stderr.write(`${server.name} v${server.version} MCP server started (stdio)
+`);
+  stdin.on("data", async (chunk) => {
+    buffer += chunk;
+    while (true) {
+      const newlineIndex = buffer.indexOf("\n");
+      if (newlineIndex === -1) break;
+      const line = buffer.slice(0, newlineIndex).trim();
+      buffer = buffer.slice(newlineIndex + 1);
+      if (!line) continue;
+      try {
+        const request = JSON.parse(line);
+        const response = await server.handleRequest(request);
+        stdout.write(JSON.stringify(response) + "\n");
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        const errorResponse = {
+          jsonrpc: "2.0",
+          id: 0,
+          error: {
+            code: -32700,
+            message: `Parse error: ${error.message}`
+          }
+        };
+        stdout.write(JSON.stringify(errorResponse) + "\n");
+      }
+    }
+  });
+  stdin.on("end", () => {
+    stderr.write("stdin closed, shutting down\n");
+    process.exit(0);
+  });
+  stdin.on("error", (err) => {
+    stderr.write(`stdin error: ${err.message}
+`);
+    process.exit(1);
+  });
+  await new Promise(() => {
+  });
+}
+
+// src/cli/index.ts
+var DEFAULT_URL = "https://graph.do";
+function parseArgs(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (arg === "--url" || arg === "-u") {
+      options.url = args[++i];
+    }
+  }
+  return options;
+}
+function printHelp() {
+  console.log(`
+graph.do - Knowledge Graph MCP Server
+
+Usage:
+  graph.do [options]
+
+Options:
+  -u, --url <url>    graph.do URL (default: https://graph.do)
+  -h, --help         Show this help message
+
+Environment Variables:
+  GRAPH_URL          graph.do URL (default: https://graph.do)
+
+Examples:
+  # Start with defaults (uses https://graph.do)
+  graph.do
+
+  # Use a custom deployment
+  graph.do --url https://my-graph.workers.dev
+
+The server communicates via stdio using the MCP protocol.
+`);
+}
+async function main() {
+  const args = process.argv.slice(2);
+  const options = parseArgs(args);
+  if (options.help) {
+    printHelp();
+    process.exit(0);
+  }
+  const graphUrl = options.url || process.env.GRAPH_URL || DEFAULT_URL;
+  try {
+    const client = new MongoClient(graphUrl);
+    const db = client.db("graph");
+    const entitiesCollection = db.collection("entities");
+    const relationsCollection = db.collection("relations");
+    const graphManager = new KnowledgeGraphManager({
+      entities: entitiesCollection,
+      relations: relationsCollection
+    });
+    const server = createGraphMcpServer({
+      name: "graph.do",
+      version: "0.1.0",
+      graphManager
+    });
+    await runStdioTransport(server);
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    console.error(`Fatal error: ${error.message}`);
+    process.exit(1);
+  }
+}
+main();
+//# sourceMappingURL=index.js.map