Twining MCP Server

Instructions

Implementation Reference

• src/tools/graph-tools.ts:57-104 (handler)

  MCP tool registration for twining_add_relation which calls the graph engine's addRelation method.

  // twining_add_relation — Add a relation between two entities
  server.registerTool(
    "twining_add_relation",
    {
      description:
        "Add a relation between two knowledge graph entities. Source and target can be entity IDs or names. Returns an error for ambiguous name matches.",
      inputSchema: {
        source: z
          .string()
          .describe("Source entity ID or name"),
        target: z
          .string()
          .describe("Target entity ID or name"),
        type: z
          .string()
          .describe(
            'Relation type: "depends_on", "implements", "decided_by", "affects", "tested_by", "calls", "imports", "related_to"',
          ),
        properties: z
          .record(z.string().max(1000))
          .optional()
          .refine(
            (obj) => obj === undefined || Object.keys(obj).length <= 50,
            { message: "Maximum 50 properties per relation" },
          )
          .describe("Key-value properties for this relation (max 50 entries, values ≤1000 chars)"),
      },
    },
    async (args) => {
      try {
        const relation = await engine.addRelation({
          source: args.source,
          target: args.target,
          type: args.type as Parameters<typeof engine.addRelation>[0]["type"],
          properties: args.properties,
        });
        return toolResult({ id: relation.id });
      } catch (e) {
        if (e instanceof TwiningError) {
          return toolError(e.message, e.code);
        }
        return toolError(
          e instanceof Error ? e.message : "Unknown error",
          "INTERNAL_ERROR",
        );
      }
    },
  );

• src/engine/graph.ts:47-55 (handler)

  GraphEngine implementation of addRelation, which delegates to the graph store.

  /** Delegate relation creation to store. */
  async addRelation(input: {
    source: string;
    target: string;
    type: Relation["type"];
    properties?: Record<string, string>;
  }): Promise<Relation> {
    return this.graphStore.addRelation(input);
  }