recommend_models

Get AI-recommended mental models for problem-solving by describing your challenge in natural language.

Instructions

Get recommended mental models based on a natural language problem description using HUMMBL REST API.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`problem`	Yes	Detailed description of the problem or challenge

Implementation Reference

src/tools/models.ts:275-353 (handler)

The core handler function that executes the recommend_models tool by sending the problem description to the HUMMBL REST API (/v1/recommend) and returning structured recommendations.

async ({ problem }) => {
  try {
    if (!API_CONFIG.apiKey) {
      return {
        content: [
          {
            type: "text",
            text: "HUMMBL API key not configured. Please set HUMMBL_API_KEY environment variable.",
          },
        ],
        isError: true,
        structuredContent: undefined,
      } as const;
    }

    const response = await fetch(`${API_CONFIG.baseUrl}/v1/recommend`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${API_CONFIG.apiKey}`,
      },
      body: JSON.stringify({ problem }),
    });

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

    const payload = await response.json();

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(payload, null, 2),
        },
      ],
      structuredContent: payload as {
        problem: string;
        recommendationCount: number;
        recommendations: Array<{
          pattern: string;
          transformations: Array<{
            key: string;
            name: string;
            description: string;
          }>;
          topModels: Array<{
            code: string;
            name: string;
            definition: string;
            priority: number;
          }>;
        }>;
      },
    } as const;
  } catch (error) {
    return {
      content: [
        {
          type: "text",
          text: `Failed to call HUMMBL API: ${error instanceof Error ? error.message : "Unknown error"}`,
        },
      ],
      isError: true,
      structuredContent: undefined,
    } as const;
  }
}

src/tools/models.ts:243-274 (schema)

Input and output schemas defined using Zod for the recommend_models tool, specifying the problem input and structured recommendation output.

{
  title: "Recommend Models for Problem",
  description:
    "Get recommended mental models based on a natural language problem description using HUMMBL REST API.",
  inputSchema: z.object({
    problem: z.string().min(10).describe("Detailed description of the problem or challenge"),
  }),
  outputSchema: z.object({
    problem: z.string(),
    recommendationCount: z.number(),
    recommendations: z.array(
      z.object({
        pattern: z.string(),
        transformations: z.array(
          z.object({
            key: z.string(),
            name: z.string(),
            description: z.string(),
          })
        ),
        topModels: z.array(
          z.object({
            code: z.string(),
            name: z.string(),
            definition: z.string(),
            priority: z.number(),
          })
        ),
      })
    ),
  }),
},

src/tools/models.ts:241-354 (registration)

Local registration of the recommend_models tool within the registerModelTools function using server.registerTool.

server.registerTool(
  "recommend_models",
  {
    title: "Recommend Models for Problem",
    description:
      "Get recommended mental models based on a natural language problem description using HUMMBL REST API.",
    inputSchema: z.object({
      problem: z.string().min(10).describe("Detailed description of the problem or challenge"),
    }),
    outputSchema: z.object({
      problem: z.string(),
      recommendationCount: z.number(),
      recommendations: z.array(
        z.object({
          pattern: z.string(),
          transformations: z.array(
            z.object({
              key: z.string(),
              name: z.string(),
              description: z.string(),
            })
          ),
          topModels: z.array(
            z.object({
              code: z.string(),
              name: z.string(),
              definition: z.string(),
              priority: z.number(),
            })
          ),
        })
      ),
    }),
  },
  async ({ problem }) => {
    try {
      if (!API_CONFIG.apiKey) {
        return {
          content: [
            {
              type: "text",
              text: "HUMMBL API key not configured. Please set HUMMBL_API_KEY environment variable.",
            },
          ],
          isError: true,
          structuredContent: undefined,
        } as const;
      }

      const response = await fetch(`${API_CONFIG.baseUrl}/v1/recommend`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${API_CONFIG.apiKey}`,
        },
        body: JSON.stringify({ problem }),
      });

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

      const payload = await response.json();

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(payload, null, 2),
          },
        ],
        structuredContent: payload as {
          problem: string;
          recommendationCount: number;
          recommendations: Array<{
            pattern: string;
            transformations: Array<{
              key: string;
              name: string;
              description: string;
            }>;
            topModels: Array<{
              code: string;
              name: string;
              definition: string;
              priority: number;
            }>;
          }>;
        },
      } as const;
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Failed to call HUMMBL API: ${error instanceof Error ? error.message : "Unknown error"}`,
          },
        ],
        isError: true,
        structuredContent: undefined,
      } as const;
    }
  }
);

src/server.ts:21-23 (registration)
Top-level registration call to registerModelTools in the MCP server creation, which includes the recommend_models tool.
```
// Register all tools
registerModelTools(server);
registerMethodologyTools(server);
```

src/config/mcp.ts:21-23 (helper)

Configuration warning if API key is missing, which is required for the recommend_models tool.

if (MCP_CONFIG.HYBRID_MODE && !MCP_CONFIG.HUMMBL_API_KEY) {
  console.warn("⚠️  HUMMBL_API_KEY not set - recommend_models tool will fail in hybrid mode");
}

HUMMBL MCP Server