Hummbl Dev Mcp Server

HUMMBL MCP Server

Give Claude access to 120 validated mental models — for sharper analysis, clearer decision-making, and systematic problem-solving across six cognitive transformations.

[](https://github.com/hummbl-dev/mcp-server/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@hummbl/mcp-server) [](https://www.npmjs.com/package/@hummbl/mcp-server) [](https://www.npmjs.com/package/@hummbl/mcp-server) [](LICENSE) [](https://github.com/hummbl-dev/mcp-server/commits/main)

Repository health contract: [docs/REPOHEALTH.md](docs/REPOHEALTH.md)

Overview

HUMMBL Base120 is a comprehensive cognitive framework consisting of 120 validated mental models organized across 6 transformations:

• P (Perspective): Change viewpoint to see problems differently
• IN (Inversion): Flip problem to find solution by avoiding failure
• CO (Composition): Combine elements to create emergent properties
• DE (Decomposition): Break down complexity into manageable components
• RE (Recursion): Apply patterns at multiple scales and iterations
• SY (Meta-Systems): Understand rules, patterns, and systems governing systems

Learn more at hummbl.io.

Installation

npm is the authoritative public registry for v1.2.0. The GitHub Packages mirror is pending — see [PACKAGEPUBLICATIONRECEIPT.md](PACKAGEPUBLICATIONRECEIPT.md) for details.

Global Installation (Recommended)

npm install -g @hummbl/mcp-server

Using npx (No Installation Required)

npx @hummbl/mcp-server

From GitHub Packages (alternate registry, v1.2.0 mirror pending)

The same build is mirrored to GitHub Packages as @hummbl-dev/mcp-server. GitHub Packages requires a GitHub personal access token with read:packages scope even for public installs — create one at .

Note: The v1.2.0 GitHub Packages mirror is pending. Use npm for the current v1.2.0 release. See [PACKAGEPUBLICATIONRECEIPT.md](PACKAGEPUBLICATIONRECEIPT.md) for details.

Add to your project's .npmrc:

@hummbl-dev:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT

Then install:

npm install @hummbl-dev/mcp-server

Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hummbl": {
      "command": "npx",
      "args": ["-y", "@hummbl/mcp-server"]
    }
  }
}

get_methodology

Retrieve the canonical Self-Dialectical AI Systems methodology, including all stages and HUMMBL Base120 references.

Example:

{}

audit_model_references

Audit a list of HUMMBL model references for validity, duplication, and transformation alignment.

Example:

{
  "items": [
    { "code": "IN11", "expectedTransformation": "IN" },
    { "code": "CO4" }
  ]
}

After configuration, restart Claude Desktop. The HUMMBL tools will appear in the attachment menu.

Available Tools

get_model

Retrieve detailed information about a specific mental model.

Example:

{
  "code": "P1"
}

list_all_models

List all 120 mental models, optionally filtered by transformation type.

Example:

{
  "transformation_filter": "P"
}

search_models

Search models by keyword across names, descriptions, and examples.

Example:

{
  "query": "decision"
}

recommend_models

Get AI-recommended models based on problem description.

Example:

{
  "problem_description": "Our startup is growing rapidly but systems are breaking down. We need to scale operations without losing quality."
}

get_transformation

Retrieve information about a specific transformation type and all its models.

Example:

{
  "type": "IN"
}

search_problem_patterns

Find pre-defined problem patterns with recommended approaches.

Example:

{
  "query": "innovation"
}

export_models

Export a curated subset of Base120 models as Markdown or JSON — useful for docs, decks, or feeding models into another LLM's context. Pass codes for a specific list, transformation for a whole group, or neither for all 120.

Example:

{
  "format": "markdown",
  "codes": ["P1", "IN3", "CO5", "DE1"]
}

Usage Examples

Example 1: Getting a Specific Model

Scenario: You want to understand "First Principles Thinking" before applying it to a problem.

// Request
{
  "tool": "get_model",
  "arguments": {
    "code": "P1"
  }
}

// Response
{
  "model": {
    "code": "P1",
    "name": "First Principles Framing",
    "definition": "Reduce complex problems to foundational truths that cannot be further simplified",
    "priority": 1,
    "transformation": "P"
  }
}

When to use: Starting a new problem analysis by identifying core assumptions and fundamentals.

---

Example 2: Listing Models by Transformation

Scenario: You know you need to look at a problem from different perspectives but want to see all available perspective models.

// Request
{
  "tool": "list_all_models",
  "arguments": {
    "transformation_filter": "P"
  }
}

// Response
{
  "total": 20,
  "models": [
    {
      "code": "P1",
      "name": "First Principles Framing",
      "definition": "Reduce complex problems to foundational truths...",
      "priority": 1,
      "transformation": "P"
    },
    {
      "code": "P2",
      "name": "Stakeholder Mapping",
      "definition": "Identify all parties with interest, influence...",
      "priority": 1,
      "transformation": "P"
    }
    // ... 18 more models
  ]
}

When to use: Exploring all models within a specific transformation category to find the right approach.

---

Example 3: Searching for Decision-Related Models

Scenario: You're making a strategic decision and want to find all mental models related to decision-making.

// Request
{
  "tool": "search_models",
  "arguments": {
    "query": "decision"
  }
}

// Response
{
  "query": "decision",
  "resultCount": 8,
  "results": [
    {
      "code": "P2",
      "name": "Stakeholder Mapping",
      "definition": "Identify all parties with interest, influence, or impact in a system or decision",
      "priority": 1,
      "transformation": "P"
    },
    {
      "code": "SY3",
      "name": "Decision Trees & Game Theory",
      "definition": "Model sequential choices and strategic interactions with payoff structures",
      "priority": 1,
      "transformation": "SY"
    }
    // ... 6 more results
  ]
}

When to use: Finding relevant models across all transformations for a specific concept or challenge.

---

Example 4: Getting Recommendations for a Complex Problem

Scenario: Your startup is scaling rapidly but systems are breaking down—you need guidance on which mental models to apply.

// Request
{
  "tool": "recommend_models",
  "arguments": {
    "problem": "Our startup is growing rapidly but systems are breaking down. We need to scale operations without losing quality."
  }
}

// Response
{
  "problem": "Our startup is growing rapidly but systems are breaking down...",
  "recommendationCount": 2,
  "recommendations": [
    {
      "pattern": "Complex system to understand",
      "transformations": [
        {
          "key": "DE",
          "name": "Decomposition",
          "description": "Break down complexity into manageable components"
        }
      ],
      "topModels": [
        {
          "code": "DE1",
          "name": "Modular Decomposition",
          "definition": "Break systems into independent, interchangeable components...",
          "priority": 1
        },
        {
          "code": "DE2",
          "name": "Layered Architecture",
          "definition": "Organize systems into hierarchical strata with clear interfaces",
          "priority": 1
        }
      ]
    },
    {
      "pattern": "Strategic or coordination challenge",
      "transformations": [
        {
          "key": "SY",
          "name": "Meta-Systems",
          "description": "Understand rules, patterns, and systems governing systems"
        }
      ],
      "topModels": [
        {
          "code": "SY1",
          "name": "Feedback Loops & Causality",
          "definition": "Trace how outputs loop back as inputs creating reinforcing or balancing dynamics",
          "priority": 1
        }
      ]
    }
  ]
}

When to use: You have a complex, multi-faceted problem and need AI-driven recommendations on where to start.

---

Example 5: Exploring the Inversion Transformation

Scenario: You've heard about "inversion thinking" and want to understand all the models in that category.

// Request
{
  "tool": "get_transformation",
  "arguments": {
    "key": "IN"
  }
}

// Response
{
  "key": "IN",
  "name": "Inversion",
  "description": "Reverse assumptions. Examine opposites, edges, negations.",
  "modelCount": 20,
  "models": [
    {
      "code": "IN1",
      "name": "Subtractive Thinking",
      "definition": "Improve systems by removing elements rather than adding complexity",
      "priority": 1
    },
    {
      "code": "IN2",
      "name": "Premortem Analysis",
      "definition": "Assume failure has occurred and work backward to identify causes",
      "priority": 1
    }
    // ... 18 more models
  ]
}

When to use: Deep-diving into a transformation to understand its philosophy and available models.

---

Example 6: Finding Problem Patterns

Scenario: Your team struggles with innovation—everything feels incremental. You want to find pre-defined patterns that match this challenge.

// Request
{
  "tool": "search_problem_patterns",
  "arguments": {
    "query": "innovation"
  }
}

// Response
{
  "query": "innovation",
  "patternCount": 1,
  "patterns": [
    {
      "pattern": "Stuck in conventional thinking",
      "transformations": ["IN"],
      "topModels": ["IN1", "IN2", "IN3"]
    }
  ]
}

When to use: You recognize a common problem type and want to quickly jump to the recommended mental models and approaches.

---

Guided Workflows (NEW in Phase 2)

HUMMBL now includes guided multi-turn workflows that walk you through systematic problem-solving using mental models. Perfect for complex problems that benefit from structured analysis.

Available Workflows

1. Root Cause Analysis

Use when: Investigating failures, incidents, or recurring problems Duration: 20-30 minutes Sequence: P → IN → DE → SY

Systematically find root causes, not just symptoms.

2. Strategy Design

Use when: Creating strategies, planning initiatives, entering markets Duration: 30-45 minutes Sequence: P → CO → SY → RE

Design comprehensive strategies with creative combinations and systemic thinking.

3. Decision Making

Use when: High-stakes decisions with uncertainty Duration: 15-25 minutes Sequence: P → IN → SY → RE

Make quality decisions through clear framing, stress-testing, and systematic evaluation.

Workflow Tools

list_workflows

List all available guided workflows.

{
  "tool": "list_workflows"
}

start_workflow

Begin a guided workflow for your problem.

{
  "tool": "start_workflow",
  "arguments": {
    "workflow_name": "root_cause_analysis",
    "problem_description": "Our production API started failing intermittently after yesterday's deployment"
  }
}

continue_workflow

Proceed to the next step after completing current step.

{
  "tool": "continue_workflow",
  "arguments": {
    "workflow_name": "root_cause_analysis",
    "current_step": 1,
    "step_insights": "Identified 3 affected stakeholders: customers experiencing timeouts, internal services with cascading failures, and ops team receiving alerts. Core assumption: the deployment changed something fundamental in request handling."
  }
}

find_workflow_for_problem

Discover which workflow best fits your problem.

{
  "tool": "find_workflow_for_problem",
  "arguments": {
    "problem_keywords": "system failure production"
  }
}

Example: Root Cause Analysis Workflow

Step 1 (Perspective):

{
  "currentStep": 1,
  "totalSteps": 4,
  "transformation": "P",
  "guidance": "Frame the problem clearly from multiple perspectives",
  "suggestedModels": ["P1", "P2", "P15"],
  "questions": [
    "What are the foundational facts we know for certain?",
    "Who is affected and how?",
    "What assumptions are we making?"
  ]
}

After completing Step 1, continue:

{
  "tool": "continue_workflow",
  "arguments": {
    "workflow_name": "root_cause_analysis",
    "current_step": 1,
    "step_insights": "Your insights here..."
  }
}

Step 2 (Inversion): Test boundaries, work backward from failure Step 3 (Decomposition): Isolate the failing component Step 4 (Meta-Systems): Design systemic fixes and prevention

---

Available Prompts

MCP prompts are user-invocable templates. In Claude Desktop they appear in the "Attach from MCP" menu and can be selected to kick off a conversation. All prompts take a free-text problem argument; apply_model also takes a model_code.

| Prompt | What it does | |---|---| | root_cause_analysis | Kicks off the Root Cause Analysis workflow (Perspective → Inversion → Decomposition → Meta-Systems) against your problem. | | strategy_design | Kicks off the Strategy Design workflow. | | decision_making | Kicks off the Decision Making workflow. | | analyze_with_models | Open-ended: calls recommend_models, fetches the top matches, and synthesises them into concrete guidance for your problem. | | apply_model | Applies one specific model (e.g. P1, IN3) to your problem via its "how to apply" guidance. |

---

Available Resources

Direct URI-based access to models and transformations:

• hummbl://model/{code} – Individual model (e.g., hummbl://model/P1)
• hummbl://transformation/{type} – All models in transformation (e.g., hummbl://transformation/P)
• hummbl://models – Complete Base120 framework
• hummbl://methodology/self-dialectical-ai – Structured Self-Dialectical AI methodology definition
• hummbl://methodology/self-dialectical-ai/overview – Markdown overview of the methodology for quick operator reference

Self-Dialectical Methodology Overview

The HUMMBL Self-Dialectical AI Systems methodology (v1.2) enables ethical self-correction via five dialectical stages (thesis, antithesis, synthesis, convergence, meta-reflection) mapped to Base120 mental models plus SY meta-models. Use the tools/resources above to fetch the canonical JSON definition, Markdown overview, or to audit references in external documents.

Problem Patterns

HUMMBL includes pre-defined problem patterns that map common challenges to recommended transformations and models. See [Problem Patterns Documentation](./docs/problem-patterns.md) for the complete catalog with detailed guidance.

Development

Setup

git clone https://github.com/hummbl-dev/mcp-server.git
cd mcp-server
npm install

Build

npm run build

Run Locally

npm run dev

Type Checking

npm run typecheck

Architecture

src/
├── index.ts              # stdio entry point
├── server.ts             # Server configuration
├── framework/
│   └── base120.ts        # Complete mental models database
├── tools/
│   └── models.ts         # Tool registrations
├── resources/
│   └── models.ts         # Resource endpoints
├── types/
│   └── domain.ts         # Core type definitions
└── utils/
    └── result.ts         # Result pattern utilities

REST API Specification

The REST API is self-documenting via OpenAPI 3.0. Fetch the spec from:

GET https://api.hummbl.io/openapi.json

Import it into Postman, Insomnia, Hoppscotch,

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hummbl-dev
• Source: hummbl-dev/mcp-server
• License: Apache-2.0
• Homepage: https://hummbl.io

Install and usage instructions live in the source repository linked above.