HUMMBL MCP Server

Instructions

Implementation Reference

• src/tools/models.ts:194-237 (handler)

  MCP tool handler that performs model search via searchModels helper, enriches results with transformation information, handles errors, and returns structured JSON response with content and metadata.

  async ({ query }) => {
    const result = searchModels(query);
  
    if (!isOk(result)) {
      return {
        content: [
          {
            type: "text",
            text: `Unable to search models: ${result.error.type}`,
          },
        ],
        isError: true,
      } as const;
    }
  
    const enriched = result.value.map((m) => {
      const trans = Object.values(TRANSFORMATIONS).find((t) =>
        t.models.some((model) => model.code === m.code)
      );
      return {
        code: m.code,
        name: m.name,
        definition: m.definition,
        priority: m.priority,
        transformation: trans?.key ?? "UNKNOWN",
      };
    });
  
    const payload = {
      query,
      resultCount: enriched.length,
      results: enriched,
    };
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(payload, null, 2),
        },
      ],
      structuredContent: payload,
    } as const;
  }

• src/tools/models.ts:174-193 (schema)

  Zod inputSchema (query: string min length 2) and outputSchema (query, resultCount, results array of models with code/name/definition/priority/transformation) for the search_models tool.

  {
    title: "Search Mental Models",
    description: "Search HUMMBL mental models by keyword across codes, names, and definitions.",
    inputSchema: z.object({
      query: z.string().min(2).describe("Search query (minimum 2 characters)"),
    }),
    outputSchema: z.object({
      query: z.string(),
      resultCount: z.number(),
      results: z.array(
        z.object({
          code: z.string(),
          name: z.string(),
          definition: z.string(),
          priority: z.number(),
          transformation: z.string(),
        })
      ),
    }),
  },

• src/tools/models.ts:172-238 (registration)

  MCP server.registerTool invocation that registers the search_models tool, specifying name, metadata, schemas, and handler function.

  server.registerTool(
    "search_models",
    {
      title: "Search Mental Models",
      description: "Search HUMMBL mental models by keyword across codes, names, and definitions.",
      inputSchema: z.object({
        query: z.string().min(2).describe("Search query (minimum 2 characters)"),
      }),
      outputSchema: z.object({
        query: z.string(),
        resultCount: z.number(),
        results: z.array(
          z.object({
            code: z.string(),
            name: z.string(),
            definition: z.string(),
            priority: z.number(),
            transformation: z.string(),
          })
        ),
      }),
    },
    async ({ query }) => {
      const result = searchModels(query);
  
      if (!isOk(result)) {
        return {
          content: [
            {
              type: "text",
              text: `Unable to search models: ${result.error.type}`,
            },
          ],
          isError: true,
        } as const;
      }
  
      const enriched = result.value.map((m) => {
        const trans = Object.values(TRANSFORMATIONS).find((t) =>
          t.models.some((model) => model.code === m.code)
        );
        return {
          code: m.code,
          name: m.name,
          definition: m.definition,
          priority: m.priority,
          transformation: trans?.key ?? "UNKNOWN",
        };
      });
  
      const payload = {
        query,
        resultCount: enriched.length,
        results: enriched,
      };
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(payload, null, 2),
          },
        ],
        structuredContent: payload,
      } as const;
    }
  );

• src/framework/base120.ts:873-883 (helper)

  Core searchModels utility function that performs case-insensitive fuzzy search across all mental models' code, name, and definition fields using getAllModels() and returns Result<MentalModel[]>. Used by the MCP tool handler.

  export function searchModels(query: string): Result<MentalModel[], DomainError> {
    const lowerQuery = query.toLowerCase();
    const results = getAllModels().filter(
      (m) =>
        m.code.toLowerCase().includes(lowerQuery) ||
        m.name.toLowerCase().includes(lowerQuery) ||
        m.definition.toLowerCase().includes(lowerQuery)
    );
  
    return ok(results);
  }