Mimir

Prerequisites

• Python 3.11 or higher
• IDE with MCP support (Claude Desktop, Cursor, Windsurf, etc.)
• Access credentials for HOMEBASE (optional, for syncing)

Quick Start with Docker

Two containers: FOB (Django web UI + API) and MCP Facade (connects your AI IDE to FOB).

Setup Steps

1. Clone the repository

   git clone https://github.com/petelind/mimir.git
   cd mimir
   

2. Create virtual environment

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Initialize database

   python manage.py migrate
   

1. Ensure local superuser

Create or restore the conventional dev superuser used by MCP/facade tests:

   python manage.py create_default_admin
   

Run this whenever your SQLite auth drifts after local experiments (recommended before pytest facade tests).

For production or shared environments:

   python manage.py createsuperuser
   

You'll be prompted for: - Username (required) - Email (optional, for password reset) - Password (minimum 8 characters)

6. Run tests Run unit and integration tests:

   pytest tests/
   

How to Use

Mimir runs as two processes that work together:

Run with persistent storage (optional: pass GITHUB_TOKEN + GITHUB_BUG_REPO for Feedback → Issues)

docker run -d \ --name mimir-fob \ -p 8000:8000 \ -v ~/mimir-data:/app/data \ -e MIMIR_USER=admin \ -e MIMIR_PASSWORD=changeme \ -e MIMIR_EMAIL=admin@localhost \ 411113550285.dkr.ecr.us-east-1.amazonaws.com/mimir:latest

open http://localhost:8000 ```

Step 3 — Configure MCP in your IDE

The MCP facade is published as a public Docker Hub image (featurefactory/mimir-mcp) — no registry login needed.

Windsurf (~/.codeium/windsurf/mcp_config.json), Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json), Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "mimir": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MIMIR_SERVER_URL=http://localhost:8000",
        "-e", "MIMIR_TOKEN=<your-token>",
        "-e", "MCP_TRANSPORT=stdio",
        "featurefactory/mimir-mcp:latest"
      ]
    }
  }
}

Replace <your-token> with the token from Step 2. Restart your IDE after saving.

Multi-platform: amd64 + arm64 · Data safety: SQLite in mounted volume · Hosted FOB: change MIMIR_SERVER_URL to https://mimir.featurefactory.io

See docs/DOCKER_QUICK_START.md for docker-compose setup and full reference.

MCP Configuration Files

• Windsurf: ~/.codeium/windsurf/mcp_config.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json

See the Quick Start section above for the config snippet.

---

2. Configure MCP in Your IDE

Register at mimir.featurefactory.io to get your token, then add to your IDE config:

Windsurf (~/.codeium/windsurf/mcp_config.json) · Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) · Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "mimir": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MIMIR_SERVER_URL=https://mimir.featurefactory.io",
        "-e", "MIMIR_TOKEN=<your-token>",
        "-e", "MCP_TRANSPORT=stdio",
        "featurefactory/mimir-mcp:latest"
      ]
    }
  }
}

For a local FOB, set MIMIR_SERVER_URL=http://localhost:8000. Restart your IDE after saving.

Step 2 — Get your API token

curl -s -X POST http://localhost:8000/api/auth/token/ \
  -d "username=admin&password=changeme" | python3 -c \
  "import sys,json; print(json.load(sys.stdin)['token'])"

Quick Reference

1. Start the Web Interface

python manage.py runserver 8000

Open http://localhost:8000 in your browser and log in with your credentials.

Once logged in, you can: - Browse playbooks: View activities, workflows, phases, artifacts, roles, and howtos - Review PIPs: Approve or reject Playbook Improvement Proposals - Compare versions: See what changed between playbook versions - Edit locally: Customize playbooks for your team

Typical Workflow

Answer Playbook Questions via MCP

Your AI assistant can query Mimir directly from your IDE (powered by FastMCP):

You: "How do I build a TSX component per FDD playbook?"
AI: → Queries Mimir → Returns activity guidance and relevant Howtos

Troubleshooting