add_relationship

Create connections between mental models by specifying relationship types, confidence levels, and supporting evidence to build a structured knowledge network.

Instructions

Add a relationship between two mental models with evidence.

Input Schema

TableJSON Schema

Name	Required	Description
`source_code`	Yes	Source model code
`target_code`	Yes	Target model code
`relationship_type`	Yes	Type of relationship (e.g., 'enables', 'reinforces')
`confidence`	Yes	Confidence level: A=High, B=Moderate, C=Hypothesis
`evidence`	No	Evidence supporting this relationship

Implementation Reference

src/tools/models.ts:952-1003 (handler)

The handler function for the 'add_relationship' tool. It validates inputs via schema, makes a POST request to the HUMMBL API at `/v1/relationships` with the relationship details, and returns the API response or error.

async ({ source_code, target_code, relationship_type, confidence, evidence }) => {
  try {
    const response = await fetch(`${API_CONFIG.baseUrl}/v1/relationships`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${API_CONFIG.apiKey}`,
      },
      body: JSON.stringify({
        source_code,
        target_code,
        relationship_type,
        confidence,
        evidence,
      }),
    });

    if (!response.ok) {
      const errorText = await response.text();
      return {
        content: [
          {
            type: "text",
            text: `API request failed: ${response.status} ${response.statusText}\n${errorText}`,
          },
        ],
        isError: true,
      };
    }

    const payload = (await response.json()) as Record<string, unknown>;

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(payload, null, 2),
        },
      ],
      structuredContent: payload,
    };
  } catch (error) {
    return {
      content: [
        {
          type: "text",
          text: `Failed to add relationship: ${error instanceof Error ? error.message : "Unknown error"}`,
        },
      ],
      isError: true,
    };
  }

src/tools/models.ts:921-951 (schema)

Zod schemas defining the input parameters (source_code, target_code, relationship_type, confidence, evidence) and expected output structure for the 'add_relationship' tool.

{
  title: "Add Model Relationship",
  description: "Add a relationship between two mental models with evidence.",
  inputSchema: z.object({
    source_code: z
      .string()
      .regex(/^(P|IN|CO|DE|RE|SY)\d{1,2}$/i)
      .describe("Source model code"),
    target_code: z
      .string()
      .regex(/^(P|IN|CO|DE|RE|SY)\d{1,2}$/i)
      .describe("Target model code"),
    relationship_type: z
      .string()
      .describe("Type of relationship (e.g., 'enables', 'reinforces')"),
    confidence: z
      .enum(["A", "B", "C"])
      .describe("Confidence level: A=High, B=Moderate, C=Hypothesis"),
    evidence: z.string().optional().describe("Evidence supporting this relationship"),
  }),
  outputSchema: z.object({
    success: z.boolean(),
    relationship: z.object({
      source_code: z.string(),
      target_code: z.string(),
      relationship_type: z.string(),
      confidence: z.string(),
      evidence: z.string().optional(),
    }),
  }),
},

src/tools/models.ts:920-1005 (registration)

Registration of the 'add_relationship' tool using server.registerTool within the registerModelTools function. This includes the schema and handler.

  "add_relationship",
  {
    title: "Add Model Relationship",
    description: "Add a relationship between two mental models with evidence.",
    inputSchema: z.object({
      source_code: z
        .string()
        .regex(/^(P|IN|CO|DE|RE|SY)\d{1,2}$/i)
        .describe("Source model code"),
      target_code: z
        .string()
        .regex(/^(P|IN|CO|DE|RE|SY)\d{1,2}$/i)
        .describe("Target model code"),
      relationship_type: z
        .string()
        .describe("Type of relationship (e.g., 'enables', 'reinforces')"),
      confidence: z
        .enum(["A", "B", "C"])
        .describe("Confidence level: A=High, B=Moderate, C=Hypothesis"),
      evidence: z.string().optional().describe("Evidence supporting this relationship"),
    }),
    outputSchema: z.object({
      success: z.boolean(),
      relationship: z.object({
        source_code: z.string(),
        target_code: z.string(),
        relationship_type: z.string(),
        confidence: z.string(),
        evidence: z.string().optional(),
      }),
    }),
  },
  async ({ source_code, target_code, relationship_type, confidence, evidence }) => {
    try {
      const response = await fetch(`${API_CONFIG.baseUrl}/v1/relationships`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${API_CONFIG.apiKey}`,
        },
        body: JSON.stringify({
          source_code,
          target_code,
          relationship_type,
          confidence,
          evidence,
        }),
      });

      if (!response.ok) {
        const errorText = await response.text();
        return {
          content: [
            {
              type: "text",
              text: `API request failed: ${response.status} ${response.statusText}\n${errorText}`,
            },
          ],
          isError: true,
        };
      }

      const payload = (await response.json()) as Record<string, unknown>;

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(payload, null, 2),
          },
        ],
        structuredContent: payload,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Failed to add relationship: ${error instanceof Error ? error.message : "Unknown error"}`,
          },
        ],
        isError: true,
      };
    }
  }
);

src/server.ts:22-22 (registration)
Top-level call to registerModelTools(server) in the main server creation, which includes the 'add_relationship' tool registration.
```
registerModelTools(server);
```

HUMMBL MCP Server