miadi 1.0.14 → 2.0.0

package/README.md

@@ -1,264 +0,0 @@
-# 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
-
-```bash
-# Install dependencies
-npm install
-
-# Copy environment template
-cp .env.example .env
-```
-
-### 2. Configuration
-
-Edit `.env` with your Miadi API credentials:
-
-```bash
-EH_TOKEN=your_miadi_api_token_here
-EH_API_URL=https://__YOUR_CUSTOM_DOMAIN__.ngrok-free.app
-```
-
-### 3. Build and Run
-
-```bash
-# 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
-```typescript
-// 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
-```typescript
-// 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
-```typescript
-// 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
-
-```bash
-# 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:
-
-```bash
-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

package/REMOTE_MCP_TRANSFORMATION_GUIDE.md

@@ -1,384 +0,0 @@
-# Remote MCP Transformation Guide
-
-**Transform Standard MCP Servers → Claude.ai Remote Connectors**
-
-## 🎯 Overview
-
-This guide shows how to transform any standard MCP server (typically using `StdioServerTransport`) into a remote HTTP-based server that works as a Claude.ai connector.
-
-**Success Story**: We transformed a complex Miadi MCP server from 1,600+ lines of custom HTTP code to a working 150-line connector using official SDK patterns.
-
-## ⚠️ Critical Success Factor: Use Official SDK Patterns
-
-**DON'T**: Build custom HTTP transports, JSON-RPC parsers, or OAuth middleware  
-**DO**: Use the MCP TypeScript SDK's `StreamableHTTPServerTransport`
-
-## 📋 Step-by-Step Transformation
-
-### Phase 1: Analysis & Preparation
-
-#### 1.1 Identify Current Architecture
-```bash
-# Check if you have a standard MCP server
-grep -r "StdioServerTransport" src/
-grep -r "McpServer" src/
-```
-
-**Standard Pattern**:
-```typescript
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-
-const server = new McpServer({ name: "my-server", version: "1.0.0" });
-const transport = new StdioServerTransport();
-await server.connect(transport);
-```
-
-#### 1.2 Audit Dependencies
-```bash
-# Check package.json for unnecessary HTTP/OAuth libraries
-# You likely only need: express, cors, and the MCP SDK
-```
-
-### Phase 2: Create Remote HTTP Server
-
-#### 2.1 Create Remote Server File
-**File**: `src/index-remote.ts`
-
-```typescript
-#!/usr/bin/env node
-
-import express from 'express';
-import cors from 'cors';
-import { randomUUID } from 'node:crypto';
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-
-// Create MCP server instance (keep your existing server config)
-const server = new McpServer({
-  name: 'your-server-name',
-  version: '1.0.0'
-}, {
-  capabilities: {
-    tools: {},
-    resources: {},
-    prompts: {}
-  }
-});
-
-// TODO: Copy your existing tool registrations here
-// server.registerTool('tool-name', {...}, async (args) => {...});
-
-// Create Express app
-const app = express();
-const PORT = parseInt(process.env.MCP_PORT || '3000');
-
-// Essential CORS for Claude.ai
-app.use(cors({
-  origin: [
-    'https://claude.ai',
-    'https://api.claude.ai',
-    'https://app.claude.ai',
-    /\.ngrok\.io$/,
-    /\.ngrok-free\.app$/
-  ],
-  credentials: true,
-  methods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
-  allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With', 'Mcp-Session-Id']
-}));
-
-app.use(express.json({ limit: '10mb' }));
-
-// Health check
-app.get('/health', (req, res) => {
-  res.json({
-    status: 'healthy',
-    server: 'your-server-name',
-    version: '1.0.0',
-    timestamp: new Date().toISOString()
-  });
-});
-
-// Session management for StreamableHTTP
-const transports: { [sessionId: string]: StreamableHTTPServerTransport } = {};
-
-// MCP endpoint handler - THE CRITICAL PART
-const handleMcpRequest = async (req: express.Request, res: express.Response) => {
-  const sessionId = req.headers['mcp-session-id'] as string | undefined;
-
-  try {
-    let currentTransport: StreamableHTTPServerTransport;
-
-    if (sessionId && transports[sessionId]) {
-      // Use existing transport
-      currentTransport = transports[sessionId];
-    } else {
-      // Create new transport with session management
-      currentTransport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: () => randomUUID(),
-        onsessioninitialized: (sessionId) => {
-          console.log(`Session initialized: ${sessionId}`);
-          transports[sessionId] = currentTransport;
-        }
-      });
-
-      // Cleanup handler
-      currentTransport.onclose = () => {
-        const sid = currentTransport.sessionId;
-        if (sid && transports[sid]) {
-          delete transports[sid];
-        }
-      };
-
-      // Connect server to transport - CRITICAL STEP
-      await server.connect(currentTransport);
-    }
-
-    // Let the SDK handle the request - DON'T PARSE JSON-RPC MANUALLY
-    await currentTransport.handleRequest(req, res, req.body);
-
-  } catch (error: any) {
-    console.error('MCP request error:', error);
-    if (!res.headersSent) {
-      res.status(500).json({
-        jsonrpc: '2.0',
-        id: req.body?.id || null,
-        error: {
-          code: -32603,
-          message: 'Internal server error'
-        }
-      });
-    }
-  }
-};
-
-// Set up MCP endpoints
-app.post('/mcp', handleMcpRequest);
-app.get('/mcp', handleMcpRequest);
-app.delete('/mcp', handleMcpRequest);
-
-// Start server
-app.listen(PORT, '0.0.0.0', () => {
-  console.log(`🚀 Remote MCP Server listening on http://0.0.0.0:${PORT}`);
-  console.log(`📡 MCP endpoint: http://0.0.0.0:${PORT}/mcp`);
-});
-```
-
-#### 2.2 Update Package.json
-```json
-{
-  "scripts": {
-    "build:remote": "esbuild src/index-remote.ts --bundle --platform=node --outfile=dist/index-remote.js --external:@modelcontextprotocol/sdk",
-    "start:remote": "node dist/index-remote.js"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.17.0",
-    "express": "^4.18.2",
-    "cors": "^2.8.5"
-  }
-}
-```
-
-### Phase 3: Tool Migration
-
-#### 3.1 Copy Existing Tool Registrations
-If you have existing tools, copy them directly:
-
-```typescript
-// FROM: Your existing server
-server.registerTool('existing-tool', {
-  description: 'Tool description',
-  inputSchema: {
-    param: z.string()
-  }
-}, async ({ param }) => {
-  // Your existing logic
-  return {
-    content: [{
-      type: 'text',
-      text: `Result: ${param}`
-    }]
-  };
-});
-```
-
-#### 3.2 Handle Complex Tool Systems
-If you have a complex tool registry system, simplify it:
-
-```typescript
-// INSTEAD OF: Complex registry pattern
-const registry = new ToolRegistry();
-registry.registerAllTools();
-
-// DO: Direct registration
-const tools = {
-  'tool-1': async (args) => { /* logic */ },
-  'tool-2': async (args) => { /* logic */ },
-};
-
-Object.entries(tools).forEach(([name, handler]) => {
-  server.registerTool(name, {
-    description: `${name} tool`,
-    inputSchema: { /* your schema */ }
-  }, handler);
-});
-```
-
-### Phase 4: Deployment Setup
-
-#### 4.1 Create Launch Script
-**File**: `scripts/start-remote.sh`
-
-```bash
-#!/bin/bash
-
-PORT=${1:-3000}
-echo "🚀 Starting Remote MCP Server on port $PORT"
-
-# Build
-npm run build:remote
-
-# Start server
-MCP_PORT="$PORT" node dist/index-remote.js &
-SERVER_PID=$!
-
-# Start ngrok tunnel
-ngrok http $PORT &
-NGROK_PID=$!
-
-# Wait and get URL
-sleep 5
-NGROK_URL=$(curl -s http://localhost:4040/api/tunnels | jq -r '.tunnels[0].public_url')
-
-echo "🌍 Public URL: $NGROK_URL"
-echo "📋 Add this URL to Claude.ai connectors"
-
-# Cleanup on exit
-trap 'kill $SERVER_PID $NGROK_PID' SIGINT SIGTERM
-wait $SERVER_PID
-```
-
-#### 4.2 Test the Server
-```bash
-# Build and start
-chmod +x scripts/start-remote.sh
-./scripts/start-remote.sh 3000
-
-# Test endpoints
-curl http://localhost:3000/health
-curl http://localhost:3000/mcp
-```
-
-### Phase 5: Claude.ai Integration
-
-#### 5.1 Add Connector
-1. Go to Claude.ai → Settings → Connectors
-2. Click "Add Custom Connector"
-3. Enter your ngrok URL: `https://abc123.ngrok-free.app`
-4. Save and test
-
-#### 5.2 Verify Connection
-- Check ngrok logs for incoming requests
-- Verify tool discovery works
-- Test actual tool calls
-
-## 🚫 Common Mistakes to Avoid
-
-### ❌ DON'T Build Custom HTTP Transport
-```typescript
-// WRONG - Custom Express handling
-app.post('/mcp', (req, res) => {
-  const jsonRpc = req.body;
-  if (jsonRpc.method === 'tools/list') {
-    // Manual JSON-RPC parsing...
-  }
-});
-```
-
-### ✅ DO Use SDK Transport
-```typescript
-// RIGHT - Let SDK handle it
-await transport.handleRequest(req, res, req.body);
-```
-
-### ❌ DON'T Implement Custom OAuth
-```typescript
-// WRONG - Custom JWT middleware
-app.use((req, res, next) => {
-  const token = req.headers.authorization;
-  // Custom token validation...
-});
-```
-
-### ✅ DO Start Simple (No Auth)
-The MCP SDK supports authless servers - Claude.ai will work without OAuth for many use cases.
-
-### ❌ DON'T Overcomplicate Tool Registration
-```typescript
-// WRONG - Complex registry systems
-class ToolRegistry {
-  // 200+ lines of complexity
-}
-```
-
-### ✅ DO Register Tools Directly
-```typescript
-// RIGHT - Simple and clear
-server.registerTool('tool-name', config, handler);
-```
-
-## 📊 Success Metrics
-
-After transformation, you should have:
-- ✅ Server starts without errors
-- ✅ ngrok tunnel connects successfully
-- ✅ Claude.ai discovers the connector
-- ✅ Tool calls work end-to-end
-- ✅ Simplified codebase (likely 80%+ reduction in lines)
-
-## 🔧 Debugging Tips
-
-### Server Won't Start
-```bash
-# Check for import errors
-node --check dist/index-remote.js
-
-# Test direct execution
-MCP_PORT=3000 node dist/index-remote.js
-```
-
-### Claude.ai Connection Issues
-```bash
-# Test health endpoint
-curl https://your-ngrok.ngrok-free.app/health
-
-# Check MCP endpoint
-curl -X POST https://your-ngrok.ngrok-free.app/mcp \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","method":"ping","id":1}'
-```
-
-### Tool Discovery Problems
-- Ensure all tools return proper MCP response format
-- Check tool schemas are valid
-- Verify error handling doesn't break JSON-RPC
-
-## 📚 Key Resources
-
-- **MCP Specification**: https://modelcontextprotocol.io/specification/
-- **TypeScript SDK**: https://github.com/modelcontextprotocol/typescript-sdk
-- **Official Examples**: `/examples/server/` in the SDK
-- **Claude.ai Connectors**: https://support.anthropic.com/en/articles/11503834-building-custom-connectors-via-remote-mcp-servers
-
-## 🎉 Final Notes
-
-The key insight is **simplicity**: The MCP SDK handles all the complex protocol details. Your job is just to:
-1. Create an MCP server
-2. Register your tools
-3. Use `StreamableHTTPServerTransport` for HTTP
-4. Let the SDK handle everything else
-
-**Result**: A working Claude.ai connector with minimal code and maximum reliability.
-
----
-**Success Rate**: Following this guide should result in working connectors 95%+ of the time, compared to ~10% success rate when building custom HTTP implementations.