MCP Server API Reference

Complete API documentation for the @muzie/mcp-server package.

Table of Contents

• Initialization
• Core Exports
• Security Context
• ActionTypes
• Error Handling
• Response Formats

Initialization

createMCPServer(config)

Factory function to initialize the MCP server with dependency injection.

import { createMCPServer } from '@muzie/mcp-server';

const mcp = createMCPServer(config);

Parameters

config.models (Required)

config.services (Optional)

config.aiConfig (Optional)

Returns

{
  MCPClient,              // Express→MCP bridge
  SmartRouter,            // Query routing analyzer
  RouteType,              // Route type enum
  primitives,             // Primitive tool functions
  ActionTypes,            // Frontend action contracts
  buildSecurityContext,   // Security context builder
  authorization,          // Authorization helpers
  mcpIntentClassifier,    // AI intent detection
  MCPAgentOrchestrator,   // Complex query agent
  handleAgentQuery,       // Agent entry point
  shouldUseAgent,         // Pre-check if agent needed
  aiQueryGenerator,       // AI query service
  TOOLS,                  // Tool definitions
  toolHandlers            // Tool handler functions
}

Example

const mcp = createMCPServer({
  models: {
    Room, Schedule, Recording, UserProfile,
    StoredRoom, FileIndex, Transcription, Transcribing
  },
  services: {
    UnifiedAIService,
    AISearchService,
    GraphContextService
  },
  utils: { normalizeRoomName },
  aiConfig: {
    openaiKey: process.env.OPENAI_API_KEY,
    xaiKey: process.env.XAI_API_KEY
  }
});

Core Exports

MCPClient

Express→MCP bridge that spawns a child process for tool execution.

import { MCPClient } from '@muzie/mcp-server';

const client = new MCPClient();
await client.connect();

const result = await client.callTool('query_rooms', {
  limit: 10,
  apiKey: 'org_123'
}, userContext, 30000);

Methods

callTool Parameters

SmartRouter

Query routing analyzer that determines the best execution path.

import { SmartRouter, RouteType } from '@muzie/mcp-server';

const analysis = SmartRouter.analyze(query);

Methods

AnalysisResult

{
  route: RouteType,      // DIRECT, SIMPLE, AGENT, or CLASSIFY
  tool: string,          // Recommended tool name
  params: Object,        // Extracted parameters
  confidence: number,    // Confidence score (0-1)
  reason: string         // Explanation for routing decision
}

RouteType Enum

import { RouteType } from '@muzie/mcp-server';

RouteType.DIRECT   // Single-step action (fastest)
RouteType.SIMPLE   // Single database query
RouteType.AGENT    // Multi-step reasoning required
RouteType.CLASSIFY // Ambiguous, needs classification

toolHandlers

Direct tool handler functions for in-process execution.

import { toolHandlers } from '@muzie/mcp-server';

const result = await toolHandlers.query_rooms({
  limit: 10,
  apiKey: 'org_123',
  userId: 'user_id',
  _userContext: securityContext
});

Available Handlers

See Tools Reference for complete tool documentation.

Security Context

buildSecurityContext(userContext)

Builds a security context for authorization checks.

import { buildSecurityContext } from '@muzie/mcp-server';

const securityContext = await buildSecurityContext({
  email: 'user@example.com',
  userId: 'user_example_com',
  apiKey: 'org_123456',
  isAdmin: false,
  timezone: 'UTC'
});

Input Parameters

Returns

{
  userEmail: string,     // Original email
  userId: string,        // Cleaned user ID
  apiKey: string,        // Organization key
  isOrgOwner: boolean,   // Owner status
  orgUserIds: string[],  // Accessible user IDs
  isAdmin: boolean,      // Admin status
  timezone: string       // Timezone
}

Authorization Helpers

import { authorization } from '@muzie/mcp-server';

const {
  buildUserContext,
  MCPAuthorizationError,
  getAccessibleRoomIds,
  validateRoomAccess,
  applyAuthorizationFilters
} = authorization;

MCPAuthorizationError

Custom error class for authorization failures.

throw new MCPAuthorizationError('Access denied to room', {
  userId: 'user_123',
  resource: 'room_456',
  action: 'read'
});

ActionTypes

Frontend action contracts returned by tools.

import { ActionTypes } from '@muzie/mcp-server';

Available Actions

ConfirmationTypes

import { ConfirmationTypes } from '@muzie/mcp-server';

ConfirmationTypes.SCHEDULE  // Schedule confirmation type

Usage in Frontend

// Tool response
{
  success: true,
  actionType: ActionTypes.VIEW_TRANSCRIPT,
  data: {
    recordingId: 'rec_123',
    transcriptId: 'trans_456'
  }
}

// Frontend handler
switch (result.actionType) {
  case ActionTypes.VIEW_TRANSCRIPT:
    openTranscriptViewer(result.data.transcriptId);
    break;
  case ActionTypes.NAVIGATE_TO_ROOM:
    navigateToRoom(result.data.roomName);
    break;
  case ActionTypes.CONFIRMATION_REQUIRED:
    showConfirmationDialog(result.data);
    break;
}

Error Handling

Standard Error Response

{
  success: false,
  error: 'Error message',
  code: 'ERROR_CODE',       // Optional error code
  details: {}               // Optional additional context
}

Error Codes

Handling Errors

try {
  const result = await toolHandlers.query_rooms(params);
  if (!result.success) {
    console.error('Tool error:', result.error);
  }
} catch (error) {
  if (error instanceof MCPAuthorizationError) {
    console.error('Authorization failed:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Response Formats

Success Response

{
  success: true,
  data: { ... },              // Tool-specific data
  actionType: ActionTypes.*, // Frontend action (optional)
  message: 'Human-readable'  // Display message (optional)
}

Query Response

{
  success: true,
  rooms: [...],      // Array of results
  total: 42,         // Total count
  page: 1,           // Current page
  limit: 10          // Results per page
}

Agent Response

{
  success: true,
  response: 'Markdown formatted response',
  steps: [
    { type: 'THINKING', content: '...' },
    { type: 'TOOL_CALL', tool: 'query_rooms', args: {...} },
    { type: 'TOOL_RESULT', data: {...} },
    { type: 'RESPONSE', content: '...' }
  ],
  tokensUsed: {
    input: 1500,
    output: 800
  }
}

Related Documentation

• Getting Started - Quick start guide
• Tools Reference - Complete tool documentation
• Architecture - System design
• Security - Security context and authorization
• Examples - Integration examples