npm install @reaatech/media-pipeline-mcp-server
# or
pnpm add @reaatech/media-pipeline-mcp-server

# Start with auto-detected providers
export OPENAI_API_KEY=sk-...
export STABILITY_API_KEY=sk-...
export DEEPGRAM_API_KEY=...
npx @reaatech/media-pipeline-mcp-server start
 
# Server listening on http://0.0.0.0:8080

# Enable Phase 2 features
FEATURE_WEBHOOKS=true \
FEATURE_STREAMING=true \
FEATURE_BATCH=true \
FEATURE_STT_STREAM=true \
npx @reaatech/media-pipeline-mcp-server start

import { MCPServer, loadConfig } from "@reaatech/media-pipeline-mcp-server";
 
const config = loadConfig();
const server = new MCPServer(config);
await server.start();
 
// Graceful shutdown
process.on("SIGTERM", async () => {
  await server.stop();
  process.exit(0);
});

class MCPServer {
  constructor(config: ServerConfig);
 
  start(): Promise<void>;
  stop(): Promise<void>;
 
  getAuthMiddleware(): AuthMiddleware | undefined;
  getRateLimiter(): RateLimiter | undefined;
  getCostTracker(): CostTracker;
}

function loadConfig(env?: NodeJS.ProcessEnv): ServerConfig;

function validateConfig(config: unknown): ServerConfig;

class CostTracker {
  constructor(budgetConfig?: BudgetConfig);
 
  canAfford(cost: number, pipelineId?: string): boolean;
  getBudgetStatus(pipelineId?: string): BudgetStatus;
  record(record: CostRecord): void;
  getSummary(): CostSummary;
  getRecords(): CostRecord[];
  getPipelineCost(pipelineId: string): number;
  getOperationCost(operation: string): number;
  getProviderCost(provider: string): number;
  reset(): void;
}

class ProviderRegistry {
  register(provider: Provider): void;
  getProvider(operation: string): Provider | undefined;
  getProviderByName(name: string): Provider | undefined;
  getAllProviders(): Provider[];
  getHealthStatus(): ProviderHealthStatus[];
  checkHealth(providerName: string): Promise<ProviderHealthStatus>;
  checkAllHealth(): Promise<ProviderHealthStatus[]>;
  isAvailable(operation: string): boolean;
}

function createProvider(config: ProviderConfig, keyVault?: KeyVault): Promise<Provider | null>;
function createProviders(configs: ProviderConfig[], keyVault?: KeyVault): Promise<Provider[]>;

class IdempotencyMiddleware {
  constructor(options: IdempotencyMiddlewareOptions);
  extractIdempotencyKey(args: Record<string, unknown>): string | undefined;
  extractProgressToken(args: Record<string, unknown>): string | undefined;
  wrap<TArgs, TResult>(handler: (args: TArgs, runId: string) => Promise<TResult>): (args: TArgs) => Promise<TResult>;
}

class InMemoryIdempotencyStore implements IdempotencyStore {
  get(key: string): Promise<IdempotencyEntry | undefined>;
  set(entry: IdempotencyEntry): Promise<void>;
  delete(key: string): Promise<void>;
}

class StreamingBridge {
  constructor(eventBus: EventBus<PipelineEvent>, throttleMs?: number);
  subscribe(runId: string, progressToken: string, onProgress?: (n: ProgressNotification) => void): void;
  unsubscribe(progressToken: string): void;
  unsubscribeAll(): void;
}

class ToolRegistry {
  getTool(name: string): ToolDefinition | undefined;
  getToolForOperation(operation: string): ToolDefinition | undefined;
  getAllTools(): ToolDefinition[];
  getToolsByCategory(category: string): ToolDefinition[];
  getSupportedOperations(): string[];
  toMCPTools(): Tool[];  // MCP SDK-compatible tool list
  isOperationSupported(operation: string): boolean;
  validateInput(toolName: string, input: Record<string, unknown>): { valid: boolean; errors: string[] };
}

interface PipelineEstimator {
  estimate(pipeline: PipelineDefinition): Promise<PipelineEstimate>;
}
 
function handlePipelineEstimate(
  estimator: PipelineEstimator,
  args: { pipeline: PipelineDefinition },
): Promise<{ content: { type: string; text: string }[]; estimate: PipelineEstimate; success: boolean }>;

// POST to /tools/call with MCP protocol
{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "tools/call",
  "params": {
    "name": "media.pipeline.run",
    "arguments": {
      "pipeline": {
        "id": "product-photo",
        "steps": [
          {
            "id": "generate",
            "operation": "image.generate",
            "inputs": { "prompt": "Professional product photo of a white sneaker" },
            "config": { "model": "sd3", "dimensions": "1024x1024" },
            "qualityGate": {
              "type": "llm-judge",
              "config": { "prompt": "Does this look professional?", "model": "gpt-4o-mini" },
              "action": "retry",
              "maxRetries": 2
            }
          },
          {
            "id": "upscale",
            "operation": "image.upscale",
            "inputs": { "artifact_id": "{{generate.output}}" },
            "config": { "scale": "4x" }
          },
          {
            "id": "remove_bg",
            "operation": "image.remove_background",
            "inputs": { "artifact_id": "{{upscale.output}}" }
          }
        ]
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "success": true,
    "content": [{ "type": "text", "text": "Pipeline 'product-photo' completed with status: completed\nDuration: 12.3s\nCost: $0.0280\nArtifacts: 3" }],
    "pipeline_id": "product-photo",
    "status": "completed",
    "artifacts": [
      { "id": "image-generate-1716300000000", "type": "image", "uri": "s3://bucket/...", "sourceStep": "generate" },
      { "id": "image-upscale-1716300010000", "type": "image", "uri": "s3://bucket/...", "sourceStep": "upscale" },
      { "id": "image-remove_background-1716300020000", "type": "image", "uri": "s3://bucket/...", "sourceStep": "remove_bg" }
    ],
    "cost_usd": 0.028,
    "duration_ms": 12300
  }
}

{
  "method": "tools/call",
  "params": {
    "name": "media.pipeline.run",
    "arguments": {
      "_meta": {
        "idempotencyKey": "order-1234567",
        "progressToken": "stream-xyz"
      },
      "pipeline": {
        "id": "product-photo",
        "steps": [ /* ... */ ]
      }
    }
  }
}

{
  "method": "tools/call",
  "params": {
    "name": "media.pipeline.resume",
    "arguments": {
      "runId": "run-1716300000000-abc123",
      "fromStepId": "upscale"
    }
  }
}

{
  "method": "tools/call",
  "params": {
    "name": "media.pipeline.estimate",
    "arguments": {
      "pipeline": {
        "id": "product-photo",
        "steps": [
          {
            "id": "generate",
            "operation": "image.generate",
            "inputs": { "prompt": "..." },
            "config": { "model": "sd3", "dimensions": "1024x1024" }
          }
        ]
      }
    }
  }
}

{
  "method": "tools/call",
  "params": {
    "name": "media.pipeline.batch",
    "arguments": {
      "pipeline": {
        "id": "bulk-product-photos",
        "steps": [
          {
            "id": "generate",
            "operation": "image.generate",
            "inputs": { "prompt": "{{row.prompt}}" },
            "config": { "dimensions": "1024x1024" }
          }
        ]
      },
      "source": {
        "type": "inline",
        "rows": [
          { "prompt": "White sneaker on clean white background" },
          { "prompt": "Red running shoe on gym floor" },
          { "prompt": "Blue dress shoe on wooden surface" }
        ]
      },
      "concurrency": 2,
      "onRowFailure": "continue",
      "perRunBudget": { "maxUsd": 0.05, "onExceed": "abort" }
    }
  }
}

{
  "method": "tools/call",
  "params": {
    "name": "media.pipeline.subscribe",
    "arguments": {
      "runId": "run-1716300000000-abc123",
      "webhookUrl": "https://my-app.com/webhooks/media-pipeline",
      "events": ["run-completed", "run-failed", "step-completed"],
      "secret": "my-hmac-secret"
    }
  }
}

{
  "method": "tools/call",
  "params": {
    "name": "quality_gate.evaluate",
    "arguments": {
      "artifact_id": "img-123",
      "gate": {
        "type": "llm-judge",
        "config": {
          "prompt": "Is this image appropriate for commercial use? Rate 1-10.",
          "model": "gpt-4o-mini"
        },
        "action": "fail"
      }
    }
  }
}

// Success
{
  "success": true,
  "content": [{ "type": "text", "text": "Operation completed successfully.\n..." }],
  "pipeline_id": "my-pipeline",
  "status": "completed",
  "artifacts": [{ "id": "artifact-123", "type": "image", "uri": "s3://...", "sourceStep": "step1" }],
  "cost_usd": 0.014,
  "duration_ms": 4523
}
 
// Error
{
  "success": false,
  "error": "Artifact not found: invalid-id"
}

// Programmatic subscription
import { SubscriptionManager, WebhookDeliveryService } from "@reaatech/media-pipeline-mcp-server";
 
const manager = new SubscriptionManager();
const delivery = new WebhookDeliveryService();
 
const sub = manager.subscribe({
  pipelineId: "run-123",
  url: "https://my-app.com/hooks",
  events: ["run-completed", "run-failed"],
  secret: "hmac-key-32+chars",
});

const config: ServerConfig = {
  features: { multiTenant: true },
  multiTenant: {
    enabled: true,
    keyVault: new AwsKeyVault(/* ... */),
    resolver: { kind: "header", headerName: "x-tenant-id" },
    defaultBudgetCaps: { dailyLimit: 50, monthlyLimit: 1000 },
  },
};