HUMMBL 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.

Repository health contract: docs/REPO_HEALTH.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 PACKAGE_PUBLICATION_RECEIPT.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 https://github.com/settings/tokens.

Note: The v1.2.0 GitHub Packages mirror is pending. Use npm for the current v1.2.0 release. See PACKAGE_PUBLICATION_RECEIPT.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 problemsDuration: 20-30 minutesSequence: P → IN → DE → SY

Systematically find root causes, not just symptoms.

2. Strategy Design

Use when: Creating strategies, planning initiatives, entering marketsDuration: 30-45 minutesSequence: P → CO → SY → RE

Design comprehensive strategies with creative combinations and systemic thinking.

3. Decision Making

Use when: High-stakes decisions with uncertaintyDuration: 15-25 minutesSequence: 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 failureStep 3 (Decomposition): Isolate the failing componentStep 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.

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 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, Swagger UI, or any OpenAPI-compatible client. No authentication is required to read the spec.

HUMMBL Ecosystem

This repo is part of the HUMMBL cognitive AI architecture. Related repos:

Learn more at hummbl.io.

The governance package is a HUMMBL-owned integration and discovery path. It isnot independent validation or evidence of external adoption.

Privacy Policy

Data Collection

The HUMMBL MCP Server operates locally on your machine and does not collect, transmit, or store any personal data. All processing happens entirely within your local environment.

Data Usage

• The server reads mental models framework data from its internal database
• Problem descriptions and user inputs are processed locally to generate model recommendations
• No data is sent to external servers or third-party services
• No telemetry or analytics are collected

Data Storage

• No persistent storage of user inputs or problem descriptions
• All processing is ephemeral and happens in memory
• No logs or audit trails are retained beyond the current session

Third-Party Sharing

• We do not share any data with third parties
• The server does not make network requests except for MCP protocol communication with Claude Desktop
• No data is transmitted to HUMMBL servers or any external services

Data Retention

• No data is retained after processing
• All data is cleared from memory when the server process terminates
• No historical records or user data are stored

Contact

For privacy-related questions or concerns, contact: [email protected]

License

Apache 2.0 © HUMMBL, LLC

Version

1.2.0

Repository Health

See docs/REPO_HEALTH.md for health contract, validationcommands, canonical source, and branch-protection expectations.