miadi 1.0.14

package/src/tools/workflow-tools.ts

@@ -0,0 +1,65 @@
+import { miadiApi } from '../api-client';
+import {
+  AgentRegisterRequest,
+  AgentRegisterResponse,
+  AgentEventsResponse,
+  WorkflowHowtoResponse
+} from '../types';
+
+export const workflowTools = {
+  /**
+   * Register an agent for GitHub event notifications
+   */
+  registerAgent: async (
+    agentId: string,
+    eventTypes: string[],
+    callbackUrl?: string
+  ): Promise<AgentRegisterResponse> => {
+    try {
+      if (!agentId || !eventTypes || eventTypes.length === 0) {
+        throw new Error('Agent ID and event types are required');
+      }
+
+      const requestBody: AgentRegisterRequest = {
+        agentId,
+        eventTypes
+      };
+
+      if (callbackUrl) requestBody.callbackUrl = callbackUrl;
+
+      return await miadiApi.registerAgent(requestBody);
+    } catch (error: any) {
+      throw new Error(`Failed to register agent: ${error.message}`);
+    }
+  },
+
+  /**
+   * Check for GitHub events for an agent
+   */
+  getAgentEvents: async (agentId: string): Promise<AgentEventsResponse> => {
+    try {
+      if (!agentId) {
+        throw new Error('Agent ID is required');
+      }
+
+      return await miadiApi.getAgentEvents(agentId);
+    } catch (error: any) {
+      throw new Error(`Failed to get agent events: ${error.message}`);
+    }
+  },
+
+  /**
+   * Get workflow setup guides and HOWTO information
+   */
+  getWorkflowHowto: async (
+    topic?: 'github-webhook-setup' | 'agent-registration' | 'agent-event-polling' | 'inter-agent-communication' | 'workflow-management' | 'authentication' | 'troubleshooting'
+  ): Promise<WorkflowHowtoResponse | any> => {
+    try {
+      return await miadiApi.getWorkflowHowto(topic);
+    } catch (error: any) {
+      throw new Error(`Failed to get workflow howto: ${error.message}`);
+    }
+  }
+};
+
+export default workflowTools;

package/src/types.ts

@@ -0,0 +1,291 @@
+// TypeScript interfaces based on Miadi Three-Pathway Agent System OpenAPI specification
+
+export interface ErrorResponse {
+  error: string;
+  message: string;
+  code?: number;
+}
+
+// Memory Management Types
+export interface GetMemoryResponse {
+  key?: string;
+  type?: 'string' | 'hash' | 'list' | 'set' | 'zset';
+  value?: any;
+  timestamp: string;
+  keys?: string[]; // For list=true
+  count?: number; // For list=true
+}
+
+export interface StoreMemoryRequest {
+  key: string;
+  value: string;
+  ttl?: number;
+  type?: 'string' | 'hash' | 'list';
+}
+
+export interface StoreMemoryResponse {
+  key: string;
+  value: string;
+  ttl?: number;
+  timestamp: string;
+  message: string;
+}
+
+export interface ScanResponse {
+  keys: string[];
+  count: number;
+  timestamp: string;
+}
+
+export interface GatherMemoryResponse {
+  items: Array<{
+    key: string;
+    value: any;
+  }>;
+  count: number;
+  timestamp: string;
+}
+
+// Session Management Types
+export interface ContextVariable {
+  name: string;
+  type: 'location' | 'device' | 'activity' | 'time' | 'custom';
+  value: any;
+  description?: string;
+}
+
+export interface SessionStartRequest {
+  persona: string;
+  mode: string;
+  contextOverrides?: ContextVariable[];
+  userId?: string;
+}
+
+export interface AgentSession {
+  id: string;
+  userId?: string;
+  activePersona: string;
+  currentMode: string;
+  resolvedCapabilities: ResolvedCapability[];
+  contextOverrides?: ContextVariable[];
+  startTime: number;
+  lastActivity: number;
+  metadata?: any;
+}
+
+export interface SessionStartResponse {
+  session: AgentSession;
+  availableCapabilities: ResolvedCapability[];
+  currentContext: ContextVariable[];
+  timestamp: string;
+}
+
+export interface SessionCurrentResponse {
+  session: AgentSession | null;
+  availableCapabilities: ResolvedCapability[];
+  currentContext: ContextVariable[];
+  timestamp: string;
+}
+
+export interface SessionSwitchModeRequest {
+  sessionId: string;
+  newMode: string;
+  contextOverrides?: ContextVariable[];
+}
+
+export interface SessionSwitchPersonaRequest {
+  sessionId: string;
+  newPersona: string;
+  preserveMode?: boolean;
+}
+
+export interface SessionListResponse {
+  sessions: AgentSession[];
+  count: number;
+  limit: number;
+  offset: number;
+  timestamp: string;
+}
+
+// Capability Types
+export interface Capability {
+  id: string;
+  description: string;
+  category?: 'communication' | 'analysis' | 'creation' | 'navigation' | 'wellness' | 'system';
+  permissions?: string[];
+}
+
+export interface ResolvedCapability extends Capability {
+  source: 'persona' | 'mode' | 'global' | 'context';
+  priority: number;
+}
+
+export interface CapabilityResolveRequest {
+  persona: string;
+  mode: string;
+  context?: ContextVariable[];
+}
+
+export interface CapabilityResolveResponse {
+  capabilities: ResolvedCapability[];
+  timestamp: string;
+}
+
+// Agent Info Types
+export interface AgentInfoResponse {
+  personas: Array<{
+    id: string;
+    name: string;
+    agentId: string;
+    description: string;
+    capabilities: string[];
+    defaultMode: string;
+  }>;
+  modes: Array<{
+    id: string;
+    name: string;
+    description: string;
+    defaultCapabilities: string[];
+    triggers: Array<{
+      phrase: string;
+      confidence: number;
+      autoSwitch: boolean;
+    }>;
+  }>;
+  capabilities: Capability[];
+  examples: Record<string, {
+    method: string;
+    url: string;
+    body: any;
+  }>;
+}
+
+// AI Integration Types
+export interface OpenAIRequest {
+  prompt: string;
+  modelId?: string;
+  maxTokens?: number;
+  temperature?: number;
+  stream?: boolean;
+}
+
+export interface OpenAIResponse {
+  id: string;
+  model: string;
+  choices: Array<{
+    text: string;
+    index: number;
+    finish_reason: string;
+  }>;
+  usage: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}
+
+export interface AIRequest {
+  prompt: string;
+  modelId?: string;
+  maxTokens?: number;
+  temperature?: number;
+}
+
+export interface AIResponse {
+  id: string;
+  model: string;
+  choices: Array<{
+    text: string;
+    index: number;
+    finish_reason: string;
+  }>;
+  usage: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}
+
+// Workflow Types
+export interface AgentRegisterRequest {
+  agentId: string;
+  eventTypes: string[];
+  callbackUrl?: string;
+}
+
+export interface AgentRegisterResponse {
+  message: string;
+  agentId: string;
+  eventTypes: string[];
+  timestamp: string;
+}
+
+export interface AgentEventsResponse {
+  agentId: string;
+  events: Array<{
+    eventId: string;
+    type: string;
+    payload: any;
+    timestamp: string;
+  }>;
+  count: number;
+  timestamp: string;
+}
+
+export interface WorkflowHowtoResponse {
+  topic: string;
+  guide: {
+    title: string;
+    steps: string[];
+  };
+  timestamp: string;
+}
+
+// Forge State Types
+export interface ForgeStateRequest {
+  state: boolean;
+}
+
+export interface ForgeStateResponse {
+  isOpen: boolean;
+  timestamp: string;
+}
+
+export interface ForgeStateUpdateResponse {
+  isOpen: boolean;
+  timestamp: string;
+  message: string;
+}
+
+// Cue Detection Types
+export interface CueTrigger {
+  phrase: string;
+  confidence: number;
+  autoSwitch: boolean;
+}
+
+export interface CueDetection {
+  targetId: string;
+  type: 'mode' | 'persona';
+  confidence: number;
+  autoSwitch: boolean;
+  trigger: CueTrigger;
+}
+
+export interface CueDetectRequest {
+  text: string;
+  currentSession?: AgentSession;
+  availableModes?: string[];
+  availablePersonas?: string[];
+}
+
+export interface CueDetectResponse {
+  detections: CueDetection[];
+  suggestedAction?: {
+    type: 'mode' | 'persona';
+    targetId: string;
+    confidence: number;
+    autoSwitch: boolean;
+  };
+  timestamp: string;
+}

package/src/utils.ts

@@ -0,0 +1,279 @@
+import { ErrorResponse } from './types';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+/**
+ * Utility functions for the Miadi MCP Server
+ */
+
+/**
+ * Standardized error handler for MCP tools
+ */
+export function handleMCPError(error: any, operation: string): never {
+  const message = error.message || error.toString();
+  console.error(`MCP Tool Error [${operation}]:`, message);
+  throw new Error(`${operation} failed: ${message}`);
+}
+
+/**
+ * Validate required parameters for MCP tools
+ */
+export function validateRequired(params: Record<string, any>, requiredFields: string[]): void {
+  const missing = requiredFields.filter(field => !params[field]);
+  if (missing.length > 0) {
+    throw new Error(`Required parameters missing: ${missing.join(', ')}`);
+  }
+}
+
+/**
+ * Sanitize input parameters to prevent injection
+ */
+export function sanitizeInput(input: string): string {
+  if (typeof input !== 'string') return input;
+  
+  // Basic sanitization - remove potentially dangerous characters
+  return input
+    .replace(/[<>]/g, '') // Remove HTML tags
+    .replace(/['"]/g, '') // Remove quotes
+    .trim();
+}
+
+/**
+ * Format timestamp for consistent output
+ */
+export function formatTimestamp(date?: Date): string {
+  return (date || new Date()).toISOString();
+}
+
+/**
+ * Check if a value is a valid UUID
+ */
+export function isValidUUID(uuid: string): boolean {
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  return uuidRegex.test(uuid);
+}
+
+/**
+ * Validate session ID format
+ */
+export function validateSessionId(sessionId: string): void {
+  if (!sessionId) {
+    throw new Error('Session ID is required');
+  }
+  if (!isValidUUID(sessionId)) {
+    throw new Error('Session ID must be a valid UUID');
+  }
+}
+
+/**
+ * Enhanced environment loading that supports:
+ * 1. MCP configuration environment variables (highest priority)
+ * 2. Current process environment variables
+ * 3. $HOME/.env file as fallback (lowest priority)
+ */
+export function loadEnvironmentVariables(): void {
+  // First, try to load from $HOME/.env as fallback
+  const homeEnvPath = path.join(os.homedir(), '.env');
+  
+  if (fs.existsSync(homeEnvPath)) {
+    try {
+      const homeEnvContent = fs.readFileSync(homeEnvPath, 'utf8');
+      const homeEnvVars = parseEnvFile(homeEnvContent);
+      
+      // Only set variables that don't already exist in process.env
+      Object.entries(homeEnvVars).forEach(([key, value]) => {
+        if (!process.env[key]) {
+          process.env[key] = value;
+        }
+      });
+      
+      console.error(`✅ Loaded fallback environment variables from ${homeEnvPath}`);
+    } catch (error) {
+      console.error(`⚠️ Failed to load ${homeEnvPath}:`, error);
+    }
+  }
+}
+
+/**
+ * Parse .env file content into key-value pairs
+ */
+function parseEnvFile(content: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  
+  const lines = content.split('\n');
+  
+  for (const line of lines) {
+    const trimmedLine = line.trim();
+    
+    // Skip empty lines and comments
+    if (!trimmedLine || trimmedLine.startsWith('#')) {
+      continue;
+    }
+    
+    // Parse KEY=VALUE format
+    const equalIndex = trimmedLine.indexOf('=');
+    if (equalIndex === -1) {
+      continue;
+    }
+    
+    const key = trimmedLine.substring(0, equalIndex).trim();
+    let value = trimmedLine.substring(equalIndex + 1).trim();
+    
+    // Remove surrounding quotes if present
+    if ((value.startsWith('"') && value.endsWith('"')) || 
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    
+    if (key) {
+      result[key] = value;
+    }
+  }
+  
+  return result;
+}
+
+/**
+ * Parse environment variables with defaults
+ * This function now relies on the enhanced environment loading
+ */
+export function getEnvVar(name: string, defaultValue?: string): string {
+  const value = process.env[name];
+  if (!value && !defaultValue) {
+    throw new Error(`Environment variable ${name} is required`);
+  }
+  return value || defaultValue!;
+}
+
+/**
+ * Safe JSON parsing with error handling
+ */
+export function safeJsonParse(jsonString: string): any {
+  try {
+    return JSON.parse(jsonString);
+  } catch (error) {
+    throw new Error(`Invalid JSON format: ${error}`);
+  }
+}
+
+/**
+ * Format API error response for MCP tools
+ */
+export function formatApiError(error: any): ErrorResponse {
+  return {
+    error: error.name || 'API Error',
+    message: error.message || 'Unknown error occurred',
+    code: error.status || error.code || 500
+  };
+}
+
+/**
+ * Validate context variables array
+ */
+export function validateContextVariables(contextOverrides?: any[]): void {
+  if (!contextOverrides) return;
+  
+  if (!Array.isArray(contextOverrides)) {
+    throw new Error('contextOverrides must be an array');
+  }
+  
+  const validTypes = ['location', 'device', 'activity', 'time', 'custom'];
+  
+  contextOverrides.forEach((context, index) => {
+    if (!context.name || !context.type) {
+      throw new Error(`Context variable at index ${index} must have 'name' and 'type' properties`);
+    }
+    
+    if (!validTypes.includes(context.type)) {
+      throw new Error(`Context variable '${context.name}' has invalid type. Must be one of: ${validTypes.join(', ')}`);
+    }
+  });
+}
+
+/**
+ * Log tool usage for debugging
+ */
+export function logToolUsage(toolName: string, parameters: any): void {
+  const logLevel = process.env.LOG_LEVEL || 'info';
+  
+  if (logLevel === 'debug') {
+    console.log(`[MCP Tool] ${toolName}:`, JSON.stringify(parameters, null, 2));
+  } else if (logLevel === 'info') {
+    console.log(`[MCP Tool] ${toolName} called`);
+  }
+}
+
+/**
+ * Create consistent response format for MCP tools
+ */
+export function createMCPResponse<T>(data: T, toolName: string): { content: Array<{ type: "text"; text: string }>; _meta?: { tool: string; timestamp: string } } {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(data, null, 2)
+      }
+    ],
+    _meta: {
+      tool: toolName,
+      timestamp: formatTimestamp()
+    }
+  };
+}
+
+/**
+ * Parse tool selection configuration from environment variables
+ */
+export function parseToolSelection(): import('./tool-registry').ToolRegistryConfig {
+  const enabled = process.env.MIADI_TOOLS_ENABLED;
+  const disabled = process.env.MIADI_TOOLS_DISABLED;
+  const defaultEnabled = process.env.MIADI_TOOLS_DEFAULT_ENABLED !== 'false';
+
+  const config: import('./tool-registry').ToolRegistryConfig = { defaultEnabled };
+
+  if (enabled) {
+    const items = enabled.split(',').map(s => s.trim()).filter(s => s.length > 0);
+    const categories = items.filter(item => !item.startsWith('miadi-') && !item.startsWith('-'));
+    const tools = items.filter(item => item.startsWith('miadi-'));
+    const excludedTools = items.filter(item => item.startsWith('-')).map(item => item.substring(1));
+
+    if (categories.length > 0) config.enabledCategories = categories;
+    if (tools.length > 0) config.enabledTools = tools;
+    if (excludedTools.length > 0) config.disabledTools = excludedTools;
+  }
+
+  if (disabled) {
+    const items = disabled.split(',').map(s => s.trim()).filter(s => s.length > 0);
+    const categories = items.filter(item => !item.startsWith('miadi-'));
+    const tools = items.filter(item => item.startsWith('miadi-'));
+
+    if (categories.length > 0) config.disabledCategories = categories;
+    if (tools.length > 0) {
+      config.disabledTools = [...(config.disabledTools || []), ...tools];
+    }
+  }
+
+  return config;
+}
+
+/**
+ * Rate limiting helper (simple in-memory implementation)
+ */
+const rateLimitMap = new Map<string, { count: number; resetTime: number }>();
+
+export function checkRateLimit(identifier: string, maxRequests: number = 100, windowMs: number = 60000): void {
+  const now = Date.now();
+  const entry = rateLimitMap.get(identifier);
+  
+  if (!entry || now > entry.resetTime) {
+    rateLimitMap.set(identifier, { count: 1, resetTime: now + windowMs });
+    return;
+  }
+  
+  if (entry.count >= maxRequests) {
+    throw new Error(`Rate limit exceeded for ${identifier}. Try again later.`);
+  }
+  
+  entry.count++;
+}