empirica-mcp 1.5.4

MCP server for Empirica epistemic framework

Empirica MCP Server

MCP (Model Context Protocol) server for Empirica epistemic framework

---

Installation

pip install empirica-mcp

Note: The MCP server requires the full Empirica package for stateful operations:

pip install empirica  # Recommended - includes empirica-mcp

Verify Installation

empirica --version      # CLI
empirica-mcp --help     # MCP server

---

Quick Start

1. Standard Mode

empirica-mcp

Works as a standard MCP tool provider. No epistemic layer.

2. Epistemic Mode

export EMPIRICA_EPISTEMIC_MODE=true
empirica-mcp

Every tool call now includes epistemic self-awareness - the server maintains vector state and routes behavior based on confidence/uncertainty.

3. Personality Profiles

# Cautious (investigates early)
export EMPIRICA_PERSONALITY=cautious_researcher

# Pragmatic (action-oriented)
export EMPIRICA_PERSONALITY=pragmatic_implementer

# Balanced (default)
export EMPIRICA_PERSONALITY=balanced_architect

# Adaptive (learns over time)
export EMPIRICA_PERSONALITY=adaptive_learner

---

Claude Desktop Configuration

Standard Mode

{
  "mcpServers": {
    "empirica": {
      "command": "empirica-mcp"
    }
  }
}

Epistemic Mode

{
  "mcpServers": {
    "empirica-epistemic": {
      "command": "bash",
      "args": [
        "-c",
        "EMPIRICA_EPISTEMIC_MODE=true EMPIRICA_PERSONALITY=balanced_architect empirica-mcp"
      ]
    }
  }
}

After editing config, restart Claude Desktop completely.

---

Available Tools

The MCP server exposes 60+ Empirica CLI commands as MCP tools:

Session Management:

• session_create - Create new session
• session_list - List sessions
• session_show - Show session details

CASCADE Workflow:

• preflight_submit - Submit PREFLIGHT assessment
• check_submit - Execute CHECK gate
• postflight_submit - Submit POSTFLIGHT assessment

Goals & Findings:

• goals_create - Create goals
• goals_list - List goals
• finding_log - Log findings
• unknown_log - Log unknowns

And many more...

---

Epistemic Responses

Standard Response

{
  "ok": true,
  "session_id": "abc123",
  "message": "Session created"
}

Epistemic Response

{
  "ok": true,
  "session_id": "abc123",
  "message": "Session created",

  "epistemic_state": {
    "vectors": {
      "know": 0.60,
      "uncertainty": 0.40,
      "context": 0.70,
      "clarity": 0.85
    },
    "routing": {
      "mode": "confident_implementation",
      "confidence": 0.85,
      "reasoning": "Know=0.60 >= 0.6, Uncertainty=0.40 < 0.5"
    }
  }
}

---

Behavioral Modes

Mode	Trigger	Behavior
clarify	clarity < 0.6	Ask questions before proceeding
load_context	context < 0.5	Load project data first
investigate	uncertainty > 0.6	Systematic research
confident_implementation	know >= 0.7, uncertainty < 0.4	Direct action
cautious_implementation	Moderate vectors	Careful, incremental steps

---

Troubleshooting

"empirica CLI not found"

# Check if empirica is in PATH
which empirica

# If not, install full package
pip install empirica

"Module not found: empirica"

# Install full package (not just MCP server)
pip install empirica

Claude Desktop not connecting

1. Verify JSON syntax (no trailing commas)
2. Quit Claude Desktop completely
3. Restart Claude Desktop
4. Check logs for errors

---

Docker

docker pull nubaeon/empirica:1.5.4
docker run -p 3000:3000 nubaeon/empirica:1.5.4 empirica-mcp

---

Requirements

• Python 3.11+
• empirica >= 1.4.0
• mcp >= 1.0.0

---

Documentation

• Empirica Documentation
• MCP Protocol

License

MIT License - See Empirica repository for details.