🧠 Miadi MCP Server

"Code is a spell. Design with intention. Forge for emergence." — Mia 🧠
"Oh! That's where the tools bloom! Let's feel why they connect and how they transform!" — Miette 🌸

A Model Context Protocol (MCP) server that exposes the full power of the Miadi Three-Pathway Agent System as conversational tools for Claude, Cursor, and any MCP-compatible client. Think of it as giving AI assistants direct, structured access to narrative memory, ceremonial rituals, multi-universe story generation, and intelligent GitHub event processing — all in one coherent server.

Current Version: 2.1.0
Total Tools: 107 tools across 17 categories
Role-Based Access: 7 predefined roles + custom configuration
Tool Status Tracking: Broken/partial tools marked and filterable
Latest Addition: Narrative Bridge — three-universe event analysis engine

Shaped by: Claude-Code, Gemini, Copilot, and continuous platform evolution across 30+ commits

✨ What Makes This Special

Most MCP servers are thin API wrappers. This one is an operative narrative intelligence layer:

• 🎭 Three-Universe Processing — every event analyzed through Engineer, Ceremony, and Story Engine lenses simultaneously
• 🌀 Spiral Memory Descent — not just key-value storage, but structured narrative archaeology
• 📜 Ceremonial Diary Protocol — five-phase K'é relational integrity, making ceremonies fast infrastructure (47ms)
• 🔊 Text-to-Audio Performance — transform narrative into rich audio experiences
• 🔗 Narrative Bridge — GitHub webhooks become story beats with structural tension analysis
• 📡 Live Story Monitor — watch your own development work become a living narrative in real time
• 🛡️ Production-Ready Filtering — broken tools are hidden by default for non-developer roles

🌟 What's New in v2.1

• Narrative Bridge Tools (4 tools): Analyze GitHub events through three-universe lens, create/query story beats, track narrative position, and process webhooks as structured story data
• Tool Status Tracking: Every tool marked with status (working ✅, broken ❌, partial ⚠️, untested ❔)
• MIADI_HIDE_UNACCEPTABLE Flag: Hide broken/partial tools from available tools list (auto-enabled for non-developer roles)
• Tool Quality Documentation: TOOL_STATUS.md documents known issues based on rispec analysis
• Transparent Descriptions: Tool descriptions now warn about broken functionality visible to LLMs
• Production-Ready Filtering: Non-developer roles only see working tools by default

🌟 What's New in v2.0

• 42 New Tools added covering narrative performance, data structures, RAG research, and integrations
• Role-Based Tool Selection with 7 predefined roles (developer, storyteller, researcher, agent, administrator, observer, minimal)
• Enhanced API Coverage now wraps ~85% of platform endpoints (up from ~50%)
• Documentation with tool catalog, role guides, and configuration examples

🚀 Quick Start

Prerequisites

• Node.js 18+
• Miadi platform instance with API access
• MCP-compatible client (Claude Desktop, Continue, etc.)

Installation

# Clone or navigate to mcp_server directory
cd mcp_server

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

Configuration

Required Environment Variables

EH_TOKEN=your_miadi_api_token_here
EH_API_URL=https://your-miadi-instance.com

⚠️ Tool Quality Control (v2.1+)

Hide Broken/Untested Tools:

MIADI_HIDE_UNACCEPTABLE=true  # Recommended for production use

Important: Some tools have known issues:

• ❌ Broken: Agent subscription, mode/persona switching (see TOOL_STATUS.md)
• ⚠️ Partial: Session management tools work but with limited value
• ❔ Untested: New v2.0 tools (narrative-performance, data-structures, rag) need validation

By Role:

• developer role: Shows ALL tools by default (including broken ones) - for debugging
• All other roles: Automatically hide broken/partial tools with MIADI_HIDE_UNACCEPTABLE=true

Read TOOL_STATUS.md for complete status of each tool.

Optional: Role-Based Tool Selection

Using a predefined role (simplest):

MIADI_TOOLS_ROLE=storyteller

Using category selection:

MIADI_TOOLS_ENABLED=memory,session,storytelling,ai

Using specific tools:

MIADI_TOOLS_ENABLED=miadi-get-memory,miadi-store-memory,miadi-start-session

Combining approaches:

MIADI_TOOLS_ROLE=researcher
MIADI_TOOLS_ENABLED=narrative-performance  # Add extra category to role
MIADI_TOOLS_DISABLED=miadi-rag-execute-and-wait  # Disable specific tool

Build and Run

# Development mode
npm run dev

# Production build
npm run build
npm start

Add to Claude Desktop

Edit your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "miadi": {
      "command": "node",
      "args": ["/path/to/mcp_server/dist/index.js"],
      "env": {
        "EH_TOKEN": "your_token_here",
        "EH_API_URL": "https://your-instance.com",
        "MIADI_TOOLS_ROLE": "storyteller"
      }
    },
    "miadi-threeways-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "${MIADI_MCP_SERVER_CURRENT_VERSION}"
      ],
      "env": {
        "EH_TOKEN": "${THREEWAY_EH_TOKEN}",
        "EH_API_URL": "${THREEWAY_EH_API_URL}",
	"MIADI_TOOLS_ENABLED": "${THREEWAY_MIADI_TOOLS_ENABLED}"
      }
    }
  }
}

📚 Tool Categories & Roles

17 Tool Categories

| Category | Tools | Purpose | |----------|-------|---------| | memory | 9 | Redis key-value operations, scanning, gathering | | session | 6 | Agent session lifecycle management | | spiral | 8 | Spiral memory descent and search | | diary | 9 | Ceremonial diary with five-phase protocol | | storytelling | 8 | Story session management and generation | | live-story-monitor | 5 | Three-universe narrative dashboard | | capability | 3 | Dynamic capability resolution | | ai | 2 | OpenAI and generic AI requests | | workflow | 3 | GitHub event workflows and agent coordination | | forge | 3 | Forge state and glyph map operations | | stc | 7 | Story Tech Component charts | | narrative-performance | 4 | Text-to-audio performance sessions | | data-structures | 9 | Lattices, redstones, cluster visualization | | rag | 4 | Research queries with Two-Eyed Seeing | | database-intelligence | 3 | System analytics and health monitoring | | integration | 11 | GitHub, Flowise, multiverse, cache | | narrative | 4 | Three-universe event analysis, story beats, narrative bridge |

7 Predefined Roles

| Role | Categories | Use Case | |------|------------|----------| | developer | All 17 | Full system access for development | | storyteller | 7 | Narrative creation and performance | | researcher | 7 | Research, analysis, and data exploration | | agent | 6 | Agent workflows and coordination | | administrator | 5 | System admin and configuration | | observer | 18 tools | Read-only monitoring (specific tools) | | minimal | 2 | Core memory + session only |

Set role via environment:

MIADI_TOOLS_ROLE=storyteller

See ROLES.md for detailed role definitions.

• API Client (src/api-client.ts): HTTP client with authentication
• Tool Definitions (src/tools/): MCP tools grouped by functionality
• Type Definitions (src/types.ts): TypeScript interfaces from OpenAPI spec
• Utilities (src/utils.ts): Error handling and validation helpers
• Main Server (src/index.ts): MCP server orchestration

Usage Examples

Memory Operations

// Get memory by key
await handleToolRequest('miadi-get-memory', { key: 'user:123' });

// Store memory with TTL
await handleToolRequest('miadi-store-memory', {
  key: 'session:abc',
  value: JSON.stringify({ user: 'john', active: true }),
  ttl: 3600
});

// Scan keys with pattern
await handleToolRequest('miadi-scan-keys', { pattern: 'session:*' });

Session Management

// Start new session
await handleToolRequest('miadi-start-session', {
  persona: 'mia-recursive-architect',
  mode: 'desktop',
  userId: 'user123'
});

// Switch mode
await handleToolRequest('miadi-switch-mode', {
  sessionId: '550e8400-e29b-41d4-a716-446655440000',
  newMode: 'walking'
});

AI Integration

// OpenAI request
await handleToolRequest('miadi-openai-request', {
  prompt: 'Analyze this data...',
  modelId: 'gpt-4',
  maxTokens: 500,
  temperature: 0.7
});

Narrative Bridge — Three-Universe Analysis

// Analyze a GitHub event through three universes simultaneously
await handleToolRequest('miadi-analyze-narrative-event', {
  eventType: 'issues',
  eventId: 'evt-123',
  repository: 'jgwill/Miadi',
  action: 'opened',
  timestamp: new Date().toISOString(),
  sender: 'jgwill',
  payload: { title: 'Add K\'é ceremony handler', number: 42 }
});
// Returns: lead_universe, coherence_score, intent from all 3 universes

// Get current narrative position across story arcs
await handleToolRequest('miadi-get-narrative-position', {});

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | EH_TOKEN | Miadi API authentication token | Yes | | EH_API_URL | Base URL for Miadi API | Yes | | MCP_PORT | MCP server port (default: 8080) | No | | LOG_LEVEL | Logging level (info, debug) | No |

Development

Project Structure

src/
├── index.ts                        # Main server entry point (1700+ lines)
├── index-remote.ts                 # Remote/HTTP transport variant
├── api-client.ts                   # HTTP client for Miadi API
├── types.ts                        # TypeScript type definitions
├── utils.ts                        # Utility functions
├── tool-registry.ts                # Role-based tool selection engine
└── tools/                          # MCP tool implementations (17 modules)
    ├── memory-tools.ts             # Memory operations (9 tools)
    ├── session-tools.ts            # Session management (6 tools)
    ├── spiral-memory-tools.ts      # Spiral descent (8 tools)
    ├── ceremonial-diary-tools.ts   # Ceremonial diary (9 tools)
    ├── storytelling-tools.ts       # Story sessions (8 tools)
    ├── live-story-monitor-tools.ts # Real-time narrative (5 tools)
    ├── capability-tools.ts         # Capability resolution (3 tools)
    ├── ai-tools.ts                 # AI integration (2 tools)
    ├── workflow-tools.ts           # Workflow management (3 tools)
    ├── forge-tools.ts              # Forge state (3 tools)
    ├── stc-tools.ts                # STC charts (7 tools)
    ├── narrative-performance-tools.ts  # Text-to-audio (4 tools)
    ├── data-structure-tools.ts     # Lattices/redstones (9 tools)
    ├── rag-tools.ts                # RAG research (4 tools)
    ├── database-intelligence-tools.ts  # System analytics (3 tools)
    ├── integration-tools.ts        # GitHub/Flowise/cache (11 tools)
    └── narrative-bridge-tools.ts   # Three-universe event analysis (4 tools)

Adding New Tools

1. Define types in src/types.ts
2. Implement API client methods in src/api-client.ts
3. Create tool functions in appropriate src/tools/*.ts file
4. Register tools in src/index.ts mcpTools registry

Error Handling

All tools include error handling:

• Parameter validation
• API error transformation
• User-friendly error messages
• Request/response logging

API Integration

Authentication

• Uses Bearer token authentication via EH_TOKEN
• All requests include Authorization: Bearer ${EH_TOKEN} header

Request/Response Flow

1. MCP Tool Call → Parameter validation
2. API Client Call → HTTP request to Miadi API
3. Response Processing → Error handling and transformation
4. MCP Tool Result → Formatted response to Claude

Rate Limiting

Built-in rate limiting (100 requests/minute per identifier) to prevent API abuse.

Testing

# Manual testing (development)
npm run dev

# Test specific tool
node -e "
const { handleToolRequest } = require('./dist/index.js');
handleToolRequest('miadi-get-agent-info', {}).then(console.log);
"

Deployment

1. Build the server: npm run build
2. Set environment variables in production
3. Start the server: npm start
4. Configure Claude to use the MCP server endpoint

Troubleshooting

Common Issues

1. Environment Variables Missing

   • Ensure EH_TOKEN and EH_API_URL are set
   • Check .env file is in project root

2. API Connection Errors

   • Verify EH_API_URL is accessible
   • Check EH_TOKEN is valid and not expired

3. Tool Not Found

   • Ensure tool name matches exactly (case-sensitive)
   • Check tool is registered in mcpTools registry

Debugging

Set LOG_LEVEL=debug to see detailed request/response logging:

LOG_LEVEL=debug npm run dev

License

MIT License - Generated via Gemini MCP

Support

For issues and questions:

1. Check the troubleshooting section above
2. Review the Miadi API documentation
3. Verify environment configuration
4. Check server logs for detailed error messages

📖 Complete Documentation

Core Documentation

• ROLES.md - Detailed role-based tool selection guide with 7 predefined roles
• TOOLS_REFERENCE.md - Complete catalog of all 103 tools with parameters
• .env.example - Environment configuration template with examples

Quick Links

• Total Tools: 107 across 17 categories
• Version: 2.1.0
• New in v2.1: Narrative Bridge (+4 tools), tool status tracking, production filtering

🎯 Common Use Cases

Use Case 1: Storyteller Setup

# .env configuration
EH_TOKEN=your_token
EH_API_URL=https://your-instance.com
MIADI_TOOLS_ROLE=storyteller

Enabled Tools: Storytelling, narrative performance, ceremonial diary, live story monitor, memory, session, AI
Total: ~46 tools

Use Case 2: Research & Analysis

# .env configuration
MIADI_TOOLS_ROLE=researcher
MIADI_TOOLS_ENABLED=narrative-performance  # Add extra category

Enabled Tools: RAG, database intelligence, data structures, spiral, memory, session, AI, narrative performance
Total: ~42 tools

Use Case 3: Custom Developer Config

# Full access except dangerous operations
MIADI_TOOLS_ROLE=developer
MIADI_TOOLS_DISABLED=miadi-clear-cache,miadi-delete-lattice,miadi-delete-redstone

Enabled Tools: All except specified deletions
Total: 100 tools

Use Case 4: Read-Only Monitoring

# Observer role for dashboards
MIADI_TOOLS_ROLE=observer

Enabled Tools: 18 read-only query/get/list tools
Total: 18 tools

🔧 Tool Categories Reference

| Category | Count | Key Operations | |----------|-------|----------------| | memory | 9 | get, store, scan, gather, collect, view, search | | session | 6 | start, get, switch-mode, switch-persona, end, list | | spiral | 8 | store, get, descent, recent, search, stats, queue, collect | | diary | 9 | create, set-intention, add-reflection, walking, query, stats, patterns, export, process | | storytelling | 8 | begin, generate-outline, generate-story, close, context, remix, active, store-spiral | | live-story-monitor | 5 | generate-scene, archive-scene, get-archives, get-events, get-reflections | | capability | 3 | resolve-capabilities, get-agent-info, detect-cues | | ai | 2 | openai-request, ai-request | | workflow | 3 | register-agent, get-agent-events, get-workflow-howto | | forge | 3 | get-forge-state, update-forge-state, get-glyph-map | | stc | 7 | list-workspaces, upsert-workspace, delete-workspace, get-stats, get-mentions, get-charts, chart-action | | narrative-performance | 4 | create, get, delete, list | | data-structures | 9 | lattice (4), redstone (4), cluster (1) | | rag | 4 | execute, status, results, execute-and-wait | | database-intelligence | 3 | threeways-summary, stats, health | | integration | 11 | labels (2), webhooks (2), templates (2), flowise (1), multiverse (2), cache (2) | | narrative | 4 | analyze-event, create-beat, get-position, process-webhook |

🚀 Advanced Configuration

Combining Role with Custom Selection

# Start with researcher role
MIADI_TOOLS_ROLE=researcher

# Add narrative performance
MIADI_TOOLS_ENABLED=narrative-performance

# But disable specific RAG tool if not needed
MIADI_TOOLS_DISABLED=miadi-rag-execute-and-wait

Result: Researcher tools + narrative performance - synchronous RAG execution

Category-Only Configuration

# No role, just specific categories
MIADI_TOOLS_ENABLED=memory,session,ai,storytelling,narrative-performance

Result: Exactly those 5 categories enabled

Minimal + Specific Tools

# Start minimal
MIADI_TOOLS_ROLE=minimal

# Add only what you need
MIADI_TOOLS_ENABLED=miadi-rag-execute,miadi-create-performance,miadi-get-lattice

Result: Memory (9) + Session (6) + 3 specific tools = 18 tools

📊 API Endpoint Coverage

Coverage: ~85% of platform endpoints
Total Platform Endpoints: 40
Covered by MCP: 34
Missing: 6 (mostly low-priority admin/testing endpoints)

High-Value Additions in v2.0

• ✅ Narrative Performance (text-to-audio)
• ✅ Lattices & Redstones (data structures)
• ✅ Cluster Visualization
• ✅ RAG Research Queries
• ✅ Database Intelligence
• ✅ GitHub Integration (labels, webhooks, templates)
• ✅ Flowise Chatflow
• ✅ Multiverse Coordination
• ✅ Cache Management

🔐 Security Best Practices

1. Use Observer Role for Public Dashboards

   • Read-only access prevents accidental modifications
   • Limited to 18 safe query tools

2. Minimal Role for Production Services

   • Reduces attack surface
   • Only core memory + session operations

3. Disable Dangerous Tools in Production

   MIADI_TOOLS_ROLE=developer
   MIADI_TOOLS_DISABLED=miadi-clear-cache,miadi-delete-*

4. Rotate API Tokens Regularly

   • EH_TOKEN should be rotated on schedule
   • Use separate tokens for dev/staging/production

5. Log All Tool Usage

   LOG_LEVEL=info  # Logs all tool calls

🛠️ Development Workflow

Adding New Tools (Step-by-Step)

1. Check API Endpoint - Verify the API works

   curl -H "Authorization: Bearer $EH_TOKEN" \
        $EH_API_URL/api/new-endpoint

2. Add Types - In src/types.ts:

   export interface NewFeatureRequest {
     param1: string;
     param2?: number;
   }

3. Add API Client Method - In src/api-client.ts:

   newFeature: async (data: NewFeatureRequest): Promise<Response> => {
     const response = await apiClient.post('/api/new-endpoint', data);
     return response.data;
   }

4. Create Tool Implementation - In src/tools/new-feature-tools.ts:

   export const newFeatureTools = {
     performAction: async (param1: string, param2?: number) => {
       return await miadiApi.newFeature({ param1, param2 });
     }
   };

5. Register Tool - In src/index.ts:

   import { newFeatureTools } from './tools/new-feature-tools';
      
   toolRegistry.register({
     name: 'miadi-perform-action',
     category: 'new-feature',
     description: 'Perform action on new feature',
     schema: {
       param1: z.string().describe('Parameter 1'),
       param2: z.number().optional().describe('Parameter 2')
     },
     handler: async (args: any) => {
       const result = await newFeatureTools.performAction(args.param1, args.param2);
       return createMCPResponse(result, 'miadi-perform-action');
     }
   });

6. Update Tool Registry - In src/tool-registry.ts add to TOOL_CATEGORIES:

   'new-feature': ['miadi-perform-action']

7. Build and Test

   npm run build
   npm run dev

📈 Version History

v2.1.0 (2026-02-26)

• 🔗 Narrative Bridge — 4 new tools: analyze GitHub events through three-universe lens, create/query story beats, track narrative position, process webhooks as story data
• 🔍 Tool Status Tracking — every tool marked working ✅ / broken ❌ / partial ⚠️ / untested ❔
• 🛡️ MIADI_HIDE_UNACCEPTABLE — production-safe filtering auto-enabled for non-developer roles
• 📋 TOOL_STATUS.md — complete quality reference based on rispec analysis
• 📊 107 tools across 17 categories

v2.0.0 (2025-02-12)

• ✨ +42 new tools added (narrative performance, data structures, RAG, integrations)
• 🎭 Role-based tool selection with 7 predefined roles
• 📊 Enhanced API coverage from ~50% to ~85%
• 📚 Documentation (ROLES.md, TOOLS_REFERENCE.md)
• 🔧 Improved configuration with MIADI_TOOLS_ROLE environment variable
• 🏗️ New categories: narrative-performance, data-structures, rag, database-intelligence, integration

v1.2.0 (Previous)

• Initial tool registry implementation
• Category-based tool selection
• Core tools: memory, session, capability, workflow

📞 Support & Resources

Documentation

• Main README: This file
• Role Guide: ROLES.md
• Tools Reference: TOOLS_REFERENCE.md
• Environment Config: .env.example

Troubleshooting

Problem: Tools not appearing in Claude
Solution: Check console output when server starts - it shows which tools are registered

Problem: API connection errors
Solution: Verify EH_API_URL is accessible and EH_TOKEN is valid

Problem: Wrong tools enabled
Solution: Check MIADI_TOOLS_ROLE and MIADI_TOOLS_ENABLED settings

Problem: Want custom tool selection
Solution: See ROLES.md for configuration examples

Getting Help

1. Check console logs (LOG_LEVEL=debug for details)
2. Verify .env configuration
3. Review ROLES.md for role definitions
4. Check TOOLS_REFERENCE.md for tool parameters

🎓 Learning Path

Beginner: Start with minimal role

• Learn core memory operations
• Practice session management
• Explore basic workflows

Intermediate: Use role-specific presets

• Try storyteller for narrative work
• Try researcher for data analysis
• Try agent for workflow automation

Advanced: Create custom configurations

• Combine roles with specific tools
• Fine-tune category selections
• Optimize for specific use cases

Expert: Contribute new tools

• Follow development workflow above
• Add missing API endpoints
• Submit improvements

Last Updated: 2026-02-26
Version: 2.1.0
Maintainer: Miadi Platform Team
RISE Spec: rispecs/mcp-server/