HUMMBL MCP Server

Instructions

Implementation Reference

• src/tools/models.ts:54-93 (handler)

  The execution handler for the 'get_model' tool. It validates and normalizes the code input, retrieves the model using the helper function, enriches it with transformation data, and formats the response as MCP structured content.

  async ({ code }) => {
    const normalizedCode = code.toUpperCase();
    const result = getModelByCode(normalizedCode);
  
    if (!isOk(result)) {
      return {
        content: [
          {
            type: "text",
            text: `Model code '${code}' not found in HUMMBL Base120 framework. Valid codes follow the pattern [P|IN|CO|DE|RE|SY][1-20].`,
          },
        ],
        isError: true,
      } as const;
    }
  
    const model = result.value;
  
    const transformation = Object.values(TRANSFORMATIONS).find((t) =>
      t.models.some((m) => m.code === model.code)
    );
  
    const payload = {
      code: model.code,
      name: model.name,
      definition: model.definition,
      priority: model.priority,
      transformation: transformation?.key ?? null,
    };
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({ model: payload }, null, 2),
        },
      ],
      structuredContent: payload,
    } as const;
  }

• src/tools/models.ts:36-52 (schema)

  Input and output JSON schemas (using Zod) for the 'get_model' tool, defining validation for code parameter and expected response structure.

  {
    title: "Get Mental Model by Code",
    description:
      "Retrieve detailed information about a specific HUMMBL mental model using its code (e.g., P1, IN3, CO5).",
    inputSchema: z.object({
      code: z
        .string()
        .regex(/^(P|IN|CO|DE|RE|SY)\d{1,2}$/i)
        .describe("Model code (e.g., P1, IN3, CO5)"),
    }),
    outputSchema: z.object({
      code: z.string(),
      name: z.string(),
      definition: z.string(),
      priority: z.number(),
      transformation: z.string().nullable(),
    }),

• src/tools/models.ts:34-94 (registration)

  The MCP server.registerTool call that registers the 'get_model' tool, specifying its name, metadata, schemas, and handler function.

  server.registerTool(
    "get_model",
    {
      title: "Get Mental Model by Code",
      description:
        "Retrieve detailed information about a specific HUMMBL mental model using its code (e.g., P1, IN3, CO5).",
      inputSchema: z.object({
        code: z
          .string()
          .regex(/^(P|IN|CO|DE|RE|SY)\d{1,2}$/i)
          .describe("Model code (e.g., P1, IN3, CO5)"),
      }),
      outputSchema: z.object({
        code: z.string(),
        name: z.string(),
        definition: z.string(),
        priority: z.number(),
        transformation: z.string().nullable(),
      }),
    },
    async ({ code }) => {
      const normalizedCode = code.toUpperCase();
      const result = getModelByCode(normalizedCode);
  
      if (!isOk(result)) {
        return {
          content: [
            {
              type: "text",
              text: `Model code '${code}' not found in HUMMBL Base120 framework. Valid codes follow the pattern [P|IN|CO|DE|RE|SY][1-20].`,
            },
          ],
          isError: true,
        } as const;
      }
  
      const model = result.value;
  
      const transformation = Object.values(TRANSFORMATIONS).find((t) =>
        t.models.some((m) => m.code === model.code)
      );
  
      const payload = {
        code: model.code,
        name: model.name,
        definition: model.definition,
        priority: model.priority,
        transformation: transformation?.key ?? null,
      };
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({ model: payload }, null, 2),
          },
        ],
        structuredContent: payload,
      } as const;
    }
  );

• src/framework/base120.ts:849-859 (helper)

  Core helper function getModelByCode used by the tool handler to lookup and return a MentalModel by its code from the Base120 data structure, returning a Result type.

  export function getModelByCode(code: string): Result<MentalModel, DomainError> {
    const allModels = getAllModels();
    const normalizedCode = code.toUpperCase();
    const model = allModels.find((m) => m.code === normalizedCode) || null;
  
    if (!model) {
      return err({ type: "NotFound", entity: "MentalModel", code: normalizedCode });
    }
  
    return ok(model);
  }

• src/server.ts:22-22 (registration)

  Invocation of registerModelTools in the main server setup, which in turn registers the get_model tool.

  registerModelTools(server);