mcp-server

HUMMBL MCP Server – User Guide

1. Purpose & Audience

This guide explains how strategists, operators, and engineers can install, configure, and operate the HUMMBL MCP Server to access the Base120 mental models and Self-Dialectical AI Systems methodology through Model Context Protocol (MCP) clients. Follow these steps to deliver consistent cognition support across Claude Desktop, IDE copilots, and internal tools.

2. Prerequisites

• Node.js 20+ and npm (preferred package manager)
• Network access to fetch npm packages
• An MCP-capable client (e.g., Claude Desktop, Perplexity Labs, VS Code MCP extension)
• HUMMBL Base120 familiarity (see README.md Overview)

3. Installation Options

Scenario	Command	Notes
Global install (recommended)	npm install -g @hummbl/mcp-server	Makes hummbl-mcp CLI available system-wide
On-demand	npx @hummbl/mcp-server	Pulls latest version without persistent install
Project dependency	npm install @hummbl/mcp-server --save-dev	Useful when bundling with bespoke tooling

After installation, run hummbl-mcp --help to confirm availability.

4. Client Configuration

4.1 Claude Desktop (macOS & Windows)

1. Locate the config file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json
2. Add the HUMMBL entry (keep npm/npx consistent with installation):

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

1. Restart Claude Desktop. HUMMBL tools appear under the attachments menu.

4.2 Perplexity or Other MCP-Aware Copilots

1. Consult the client’s MCP settings UI.
2. Set command to hummbl-mcp (or npx -y @hummbl/mcp-server).
3. Choose stdio transport when asked; no API keys are required today.

4.3 VS Code / JetBrains Extensions

1. Install an MCP-compatible extension (e.g., Perplexity MCP for VS Code).
2. Register a new server pointing to hummbl-mcp.
3. Enable the extension. The HUMMBL tools become callable within the editor command palette.

4.4 Automation & CI Pipelines

Use the CLI directly inside scripts:

hummbl-mcp --transport stdio <<'EOF'
{"method":"hummbl/get_model","params":{"code":"DE3"}}
EOF

This enables batch audits of model references or automated methodology exports.

5. Using HUMMBL Tools (Base120)

Tool	Purpose	Minimal Params
get_model	Fetch a single model with description, example, tags	{ "code": "P1" }
list_all_models	Enumerate the 120 models or filter by transformation	{ "transformation_filter": "IN" } (optional)
search_models	Keyword search across names, descriptions, examples	{ "query": "decision" }
recommend_models	Receive recommendations based on a problem statement	{ "problem_description": "Scaling ops" }
get_transformation	Return all models within a transformation (P/IN/CO/DE/RE/SY)	{ "type": "SY" }
search_problem_patterns	Retrieve HUMMBL problem patterns plus suggested models	{ "query": "ethics" }
get_methodology	Download the Self-Dialectical AI methodology bundle	{}
audit_model_references	Validate lists of model references in briefs	{ "items": [{"code": "IN11"}] }

All responses follow the HUMMBL Result pattern with explicit ok/error fields. Handle errors by inspecting error.code and error.message.

6. Resources (URI Access)

• hummbl://model/{code}
• hummbl://transformation/{type}
• hummbl://models
• hummbl://methodology/self-dialectical-ai
• hummbl://methodology/self-dialectical-ai/overview

Clients that support MCP resources can fetch the canonical JSON/Markdown directly without invoking tools.

7. Troubleshooting Checklist

1. Server will not start – ensure Node.js 20+, run npm install, then retry npx @hummbl/mcp-server.
2. Claude does not list HUMMBL tools – confirm config JSON syntax, remove trailing commas, restart Claude Desktop.
3. Tool errors referencing missing models – run get_model with the exact code (e.g., DE3). The audit tool flags typos.
4. Network restrictions – preload the package (npm pack @hummbl/mcp-server) inside restricted environments.
5. Review TROUBLESHOOTING.md for deeper diagnostics and support escalation paths.

8. Operational Best Practices

• Pin server versions in regulated environments: npx @hummbl/mcp-server@1.0.0-beta.2.
• Log all tool invocations when integrating with internal platforms for post-incident reviews.
• Use HUMMBL transformations explicitly in prompts (e.g., “Use SY6 to evaluate meta-constraints”).
• Pair HUMMBL outputs with human validation before high-stakes deployment.

9. Support & Feedback

• Issues: GitHub issue tracker
• Security reporting: see SECURITY.md
• For feature requests or Base120 clarifications, contact Reuben (reuben@hummbl.io)

Stay aligned with HUMMBL Base120 principles and cite transformation codes in prompts for maximum fidelity.

This site is open source. Improve this page.