graph-node-upsert

Create or update graph nodes with labels, types, and properties using MCP Index Notes. Returns node ID for efficient knowledge graph management and relationship mapping.

Instructions

Create or update a graph node with label/type/props. Returns node id.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`id`	No
`label`	Yes
`props`	No
`type`	No

Implementation Reference

src/mcp.ts:164-168 (registration)

Tool registration in the tools array defining name, description, and inputSchema.

{
  name: 'graph-node-upsert',
  description: 'Create or update a graph node with label/type/props. Returns node id.',
  inputSchema: { type: 'object', properties: { id: { type: 'number' }, label: { type: 'string' }, type: { type: 'string' }, props: { type: 'object' } }, required: ['label'] },
},

src/mcp.ts:1269-1273 (handler)

MCP tool handler that parses input with GraphNodeSchema and calls graph.upsertNode, returning the node ID.

case 'graph-node-upsert': {
  const parsed = GraphNodeSchema.parse(args);
  const id = graph.upsertNode(parsed);
  return { content: [{ type: 'text', text: JSON.stringify({ id }) }] };
}

src/types.ts:52-58 (schema)

Zod schema for validating graph node upsert input: id (opt), label (req), type (opt), props (opt).

export const GraphNodeSchema = z.object({
  id: z.number().int().positive().optional(),
  label: z.string().min(1),
  type: z.string().optional(),
  props: z.record(z.any()).optional().default({}),
});
export type GraphNodeInput = z.infer<typeof GraphNodeSchema>;

src/graph.ts:75-91 (helper)

Core upsertNode implementation in SqliteGraphStore: updates by id or label/type, inserts new if not exists, returns id.

upsertNode(node: GraphNode): number {
  const props = JSON.stringify(node.props ?? {});
  if (node.id) {
    const info = this.db.prepare(`UPDATE graph_nodes SET label=?, type=?, props=? WHERE id=?`).run(node.label, node.type ?? null, props, node.id);
    if (info.changes === 0) throw new Error(`Node with id ${node.id} not found`);
    return node.id;
  }
  // Try find existing
  const existing = this.getNodeByLabel(node.label, node.type);
  if (existing) {
this.db.prepare(`UPDATE graph_nodes SET props=? WHERE id=?`).run(props, existing.id);
    return existing.id!;
  }
  const info = this.db.prepare(`INSERT INTO graph_nodes(label, type, props) VALUES (?, ?, ?)`)
    .run(node.label, node.type ?? null, props);
  return Number(info.lastInsertRowid);
}

src/graph.ts:238-258 (helper)

Core upsertNode implementation in LiteGraphStore (fallback): in-memory upsert by id or label/type, returns id.

upsertNode(node: GraphNode): number {
  if (node.id) {
    const existing = this.nodes.get(node.id);
    if (!existing) throw new Error(`Node with id ${node.id} not found`);
    const updated = { ...existing, label: node.label, type: node.type, props: node.props ?? existing.props };
    this.nodes.set(node.id, updated);
    this.labelIndex.set(this.keyFor(updated.label, updated.type), node.id);
    return node.id;
  }
  const idxKey = this.keyFor(node.label, node.type);
  const id = this.labelIndex.get(idxKey);
  if (id) {
    const updated = { ...this.nodes.get(id)!, props: node.props ?? this.nodes.get(id)!.props };
    this.nodes.set(id, updated);
    return id;
  }
  const newId = this.nextNodeId++;
  this.nodes.set(newId, { id: newId, label: node.label, type: node.type, props: node.props ?? {} });
  this.labelIndex.set(idxKey, newId);
  return newId;
}

MCP Index Notes