Revenant MCP Server

A FastMCP server providing Scanner Daybook daily log analysis and Obsidian vault navigation for multi-passionate individuals. Built on Scanner psychology principles and designed for seamless integration with Claude Desktop.

Overview

The Revenant MCP server bridges Scanner psychology theory with practical daily workflow automation. It provides tools for loading daily logs and prompts for LLM-driven analysis that honors the multi-passionate nature of Scanner personalities.

Key Features

• Scanner Psychology Integration - Honors multi-passionate interests as gifts, not flaws
• Zeigarnik Effect Management - Documentation-based psychological closure
• Energy Pattern Analysis - Framework-guided recognition of energy cycles and body wisdom
• Reward-Based Completion - Celebrates learning/creating/connecting over external standards
• Vault Navigation - Context loading for broader knowledge system exploration
• LLM-Driven Analysis - Flexible pattern recognition adaptable to personal notation styles

Scanner Psychology Foundation

What is a Scanner?

Scanners are people with multiple passionate interests who thrive on variety, learning, and cross-pollination between fields. Unlike traditional productivity approaches that assume single-focus dedication, Scanner psychology recognizes:

• Multiple interests are gifts, not character flaws
• Boredom signals completion, not failure
• Cross-connections between interests create innovation
• Personal "enough" criteria matter more than external standards

Core Scanner Principles

1. The Zeigarnik Effect & Documentation

Problem: Unfinished tasks stick in memory, creating psychological tension
Scanner Solution: Documentation achieves closure like bookmarking a browser tab - the information is preserved, mental space is cleared, but you can return when interest calls again.

Implementation: The server provides zeigarnik_closure_check() prompt to identify open loops and suggest documentation strategies for psychological release.

2. Reward-Based Completion

Traditional Approach: External completion criteria (finish the course, ship the product)
Scanner Approach: Internal reward recognition (learned something new, created a connection, discovered an insight)

Implementation: The project_completion_check() prompt celebrates Scanner-style wins:

• Learning achieved - New insights or skills acquired
• Creating accomplished - Something built, made, or expressed
• Connecting completed - Links discovered between interests or ideas

3. Energy Management Over Time Management

Philosophy: Scanners work best when they align activities with natural energy rhythms rather than forcing rigid schedules.

Implementation: Multiple energy-focused prompts:

• weekly_energy_review() - Identify peak performance windows and energy drains
• energy_optimization_plan() - Create personalized energy management recommendations
• morning_briefing() - Daily energy pattern analysis with body wisdom integration

4. Permission-Based Productivity

Core Insight: Scanners need explicit permission to stop when reward is achieved, rotate interests naturally, and honor their multi-passionate nature.

Implementation: All prompts integrate permission slip concepts:

• Permission to rotate interests when boredom signals completion
• Permission to pursue cross-connections over linear progression
• Permission to define personal "enough" criteria
• Permission to follow body signals and intuitive timing

5. Cross-Connection Discovery

Scanner Superpower: The ability to see unexpected links between seemingly unrelated interests, creating innovative solutions and insights.

Implementation:

• interest_rotation_analysis() maps how interests interconnect over time
• hyperfocus_session_analysis() identifies patterns in deep-focus periods
• All prompts look for cross-pollination opportunities between different areas of engagement

Technical Architecture

Current Stack

• FastMCP 2.x - Async-first server framework
• 6 Tools - Data loading and context retrieval (4 navigation + 2 Scanner Daybook)
• 7 Prompts - Scanner-psychology aligned workflow orchestration
• LLM-Driven Analysis - Flexible pattern recognition using Scanner philosophical framework

Project Structure

revenant-mcp/
├── main.py                          # Entry point
├── src/revenant_mcp/
│   ├── config.py                    # Server configuration
│   ├── server.py                    # FastMCP instance with tool & prompt registration
│   ├── tools/                       # Data retrieval tools
│   │   ├── time.py                  # Current time with timezone
│   │   ├── navigation.py            # Obsidian vault context loading (4 tools)
│   │   └── scanner_daybook.py       # Daily log loading (2 tools)
│   └── prompts/                     # Scanner workflow prompts
│       └── scanner_daybook.py       # LLM workflow orchestration (7 prompts)
└── llm_ctx/                        # FastMCP documentation and patterns

Available Tools & Prompts

Data Loading Tools (6 total)

Navigation & Context

• load_navigation_context() - Load vault-level CLAUDE.md guidance
• discover_subdirectory_navigation(subdirectory) - Explore specific areas
• list_navigation_files() - Discover all available navigation files
• get_current_time() - Current timestamp with timezone

Scanner Daybook Data

• load_daily_logs_range(days_back=7) - Load daily logs with date range validation
• load_scanner_context() - Load Scanner philosophical framework and guidance

Scanner Workflow Prompts (7 total)

morning_briefing(days_back=7)

Purpose: Comprehensive morning briefing with energy and pattern analysis
Philosophy: Framework-first approach loads Scanner context before analyzing logs
Analysis: Energy levels, body signals, emotion-impulse patterns, hyperfocus sessions, cross-connections

weekly_energy_review()

Purpose: Weekly energy optimization insights
Philosophy: Energy management over time management - identify natural rhythms
Analysis: Peak performance windows, energy drains, hyperfocus patterns, activity correlations

project_completion_check(days_back=7)

Purpose: Celebrate Scanner-style wins using reward-based criteria
Philosophy: "My enough is defined by me, not external standards"
Recognition: Learning achieved, creating accomplished, connecting completed, successful boundaries

hyperfocus_session_analysis(days_back=14)

Purpose: Deep analysis of hyperfocus triggers and outcomes
Philosophy: Understanding Scanner hyperfocus patterns for intentional optimization
Analysis: Entry conditions, session duration, outcomes, recovery patterns

interest_rotation_analysis(days_back=30)

Purpose: Map interest rotation patterns and cross-connections
Philosophy: Multi-passionate engagement is natural and valuable
Analysis: Rotation cycles, cross-pollination opportunities, natural transition triggers

energy_optimization_plan()

Purpose: Personalized energy management recommendations
Philosophy: Align activities with natural energy rhythms
Output: Daily/weekly guidelines, hyperfocus windows, recovery practices, boundary recommendations

zeigarnik_closure_check(days_back=14)

Purpose: Identify open loops needing documentation for psychological closure
Philosophy: Documentation achieves closure without forced completion
Process: Find cognitive burdens, suggest documentation strategies, create "parking lot" entries

Scanner Daily Practice

Daily Log Format

Scanner Daybook uses YYYY-MM-DD.md files in the "Daily Logs" directory with:

• Energy Tracking: Energy levels (1-5 scale) with descriptive context
• Body Signals: Physical state awareness and wisdom
• Emotion-Impulse Patterns: "Felt X, wanted Y, did Z" recognition
• Hyperfocus Sessions: Tags and context for deep-focus periods
• Cross-Connections: Unexpected links between interests
• Permission Slips: Boundaries and self-permission practices
• Reward Recognition: Learning/creating/connecting achievements

Integration Philosophy

The Scanner Daybook system recognizes that:

• Documentation creates closure - Writing about experiences provides psychological completion
• Patterns emerge over time - Daily logs reveal natural rhythms and preferences
• Body wisdom guides timing - Physical and emotional signals indicate optimal engagement
• Interest rotation is healthy - Boredom signals readiness for the next fascinating thing
• Cross-connections spark innovation - Seemingly unrelated interests inform each other

Usage Examples

Morning Briefing Workflow

1. Use morning_briefing(7) prompt in Claude Desktop
2. Reviews past week with Scanner framework
3. Identifies energy patterns and optimization opportunities
4. Suggests natural next actions based on body wisdom and interest cycles

Project Completion Celebration

1. Use project_completion_check(7) prompt
2. Finds Scanner-style completions (learning/creating/connecting)
3. Celebrates rewards achieved rather than external completion criteria
4. Validates permission to rotate interests when boredom signals completion

Weekly Energy Optimization

1. Use weekly_energy_review() prompt
2. Analyzes energy patterns across different activities and times
3. Identifies peak performance windows and energy drains
4. Provides recommendations for aligning activities with natural rhythms

Installation & Setup

Prerequisites

• Python 3.11+
• uv package manager
• Claude Desktop (for MCP integration)

Quick Start

# Clone and setup
git clone <repository-url>
cd revenant-mcp
uv sync

# Test installation
PYTHONPATH=src uv run python -c "import revenant_mcp.server; print('✅ Server working')"

# Test with MCP inspector
npx @modelcontextprotocol/inspector uv --directory . run python main.py

Claude Desktop Integration

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "revenant-mcp": {
      "command": "uv",
      "args": [
        "--directory", 
        "/path/to/revenant-mcp",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}

Development & Testing

Testing Commands

# Test prompt registration
PYTHONPATH=src uv run python -c "
from revenant_mcp.server import mcp
print(f'✅ {len(mcp._prompt_manager._prompts)} prompts registered')
"

# Test with real data
# In Claude Desktop: "Use the morning_briefing prompt with 7 days back"

Key Development Principles

• Framework-First: Load Scanner context before log analysis
• LLM-Driven: Flexible pattern recognition over rigid regex
• Async I/O: All file operations use anyio for responsiveness
• Error Handling: User-friendly errors via ToolError
• Scanner-Aligned: All prompts honor multi-passionate psychology

Scanner Philosophy in Action

This server doesn't just analyze daily logs - it embodies Scanner psychology in its design:

• Multiple Tools & Prompts - Like a Scanner's multiple interests, the server provides diverse analysis approaches
• Cross-Connection Discovery - Links insights between daily experiences and broader vault knowledge
• Flexible Analysis - LLM-driven approach adapts to personal notation styles rather than forcing rigid formats
• Permission-Based Features - Every prompt includes permission to stop, rotate, or redefine completion
• Energy-Centric - Prioritizes energy management and body wisdom over external productivity metrics
• Documentation-Driven Closure - Uses the act of analysis itself to achieve psychological completion

The result is a system that works with Scanner nature rather than against it, celebrating the gifts of multi-passionate engagement while providing practical support for daily productivity and insight generation.

License

MIT License - Feel free to adapt for your own Scanner journey.

---

"Scanners are not failed specialists. They are a different kind of thinking person, one who needs to follow their natural inclinations in order to be happy and productive." - Barbara Sher