Miadi MCP Server

A Model Context Protocol (MCP) server implementation that exposes the Miadi Three-Pathway Agent System API as MCP tools for Claude to use.

Generated by: Claude-Code and Gemini via gemini-cli MCP on 2025-07-25 / 2025-08-13

IMPORTANT NOTES

• "Miadi Three-Pathway" is not public yet and still in development internally. We plan to publish it publicly in the future.

Overview

This MCP server acts as a bridge between Claude and the Miadi Three-Pathway Agent System, enabling natural language interaction with:

• Memory Operations: Redis-based memory storage and retrieval
• Session Management: Agent persona and mode switching
• Capability Resolution: Dynamic capability resolution based on context
• AI Integration: OpenAI and generic AI model requests
• Workflow Management: GitHub event handling and agent coordination
• Forge State: System state management and glyph operations

Quick Start

1. Installation

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

2. Configuration

Edit .env with your Miadi API credentials:

EH_TOKEN=your_miadi_api_token_here
EH_API_URL=https://__YOUR_CUSTOM_DOMAIN__.ngrok-free.app

3. Build and Run

# Development mode
npm run dev

# Production build
npm run build
npm start

Available MCP Tools

Memory Operations

• miadi-get-memory - Retrieve memory data from Redis
• miadi-store-memory - Store data in memory with TTL
• miadi-scan-keys - Scan Redis keys with patterns
• miadi-gather-memory-values - Gather multiple memory values
• miadi-collect-memory - Collect specific keys
• miadi-view-key-content - View individual key content
• miadi-search-cluster - Search cluster for keys

Session Management

• miadi-start-session - Start new agent session
• miadi-get-current-session - Get current session details
• miadi-switch-mode - Switch mode in existing session
• miadi-switch-persona - Switch persona in session
• miadi-end-session - End active session
• miadi-list-sessions - List active sessions

Capability Resolution

• miadi-resolve-capabilities - Resolve capabilities for persona/mode
• miadi-get-agent-info - Get comprehensive agent system info
• miadi-detect-cues - Detect mode/persona switch cues from text

AI Integration

• miadi-openai-request - Make OpenAI API requests
• miadi-ai-request - Make generic AI requests

Workflow Management

• miadi-register-agent - Register agent for GitHub events
• miadi-get-agent-events - Check for agent events
• miadi-get-workflow-howto - Get workflow setup guides

Forge State

• miadi-get-forge-state - Get current forge state
• miadi-update-forge-state - Update forge state
• miadi-get-glyph-map - Get glyph map information

Architecture

Claude → MCP Tool Calls → MCP Server → HTTP Requests (EH_TOKEN) → Miadi API
                                    ← MCP Tool Results ← HTTP Responses ←

Key Components

• 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
});

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
├── api-client.ts            # HTTP client for Miadi API
├── types.ts                 # TypeScript type definitions
├── utils.ts                 # Utility functions
└── tools/                   # MCP tool implementations
    ├── memory-tools.ts      # Memory operations
    ├── session-tools.ts     # Session management
    ├── capability-tools.ts  # Capability resolution
    ├── ai-tools.ts          # AI integration
    ├── workflow-tools.ts    # Workflow management
    └── forge-tools.ts       # Forge state operations

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 comprehensive 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