revenant-mcp by chaosisnotrandomitisrhythmic - MCP Server

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

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

Project Completion Celebration

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

Weekly Energy Optimization

Use weekly_energy_review() prompt
Analyzes energy patterns across different activities and times
Identifies peak performance windows and energy drains
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