MCP Tools Reference

{
  sessionId: string;        // Unique session identifier
  status: "initialized";    // Session status
  task: string;             // Confirmed task description
  context: {
    files: string[];        // Files included in context
    fileCount: number;      // Number of context files
  };
  options: {
    maxSteps: number;       // Maximum execution steps
    dryRun: boolean;        // Dry run mode enabled
  };
}

const session = await orchex_init({
  task: "Add user authentication to the API",
  files: [
    "src/server.ts",
    "src/routes/",
    "src/models/user.ts"
  ],
  maxSteps: 15,
  dryRun: false
});

console.log(session.sessionId);
// => "sess_abc123def456"

{
  files?: string[];          // Additional files for this stream
  depth?: "minimal" | "moderate" | "comprehensive";
}

[
  {
    command: string;         // Command to execute
    critical: boolean;       // Fail on error if true
  }
]

{
  maxSteps?: number;         // Override session maxSteps
  timeout?: number;          // Timeout in milliseconds
  requireTests?: boolean;    // Require test validation
}

{
  sessionId: string;         // Session identifier
  streamId: string;          // Added stream identifier
  status: "stream_added";    // Confirmation status
  streamCount: number;       // Total streams in session
  plan: {
    steps: number;           // Estimated execution steps
    files: string[];         // Files this stream will modify
  };
}

const result = await orchex_add_stream({
  sessionId: "sess_abc123def456",
  streamId: "api-auth-routes",
  description: "Create authentication API routes",
  plan: `
    1. Create src/routes/auth.ts with login/logout endpoints
    2. Add JWT token generation and validation
    3. Integrate with existing Express server
    4. Add authentication middleware
  `,
  context: {
    files: ["src/middleware/", "src/utils/jwt.ts"],
    depth: "moderate"
  },
  commands: [
    { command: "npm test", critical: true },
    { command: "npm run lint", critical: false }
  ],
  constraints: {
    maxSteps: 8,
    requireTests: true
  }
});

console.log(result.streamCount);
// => 1

{
  sessionId: string;              // Session identifier
  status: "initialized" |         // Current session status
          "planning" |
          "executing" |
          "completed" |
          "failed" |
          "cancelled";
  
  progress?: {                    // Present during execution
    currentStream: string;        // Active stream ID
    currentStep: number;          // Current step number
    totalSteps: number;           // Total estimated steps
    percentage: number;           // Completion percentage (0-100)
  };
  
  streams: Array<{                // All streams in session
    streamId: string;
    status: "pending" | "running" | "completed" | "failed";
    steps?: number;               // Steps executed
    duration?: number;            // Execution time (ms)
  }>;
  
  metrics?: {                     // Present after execution
    totalDuration: number;        // Total execution time (ms)
    tokensUsed: number;           // Total tokens consumed
    filesModified: number;        // Number of files changed
  };
  
  error?: {                       // Present on failure
    message: string;              // Error description
    stream: string;               // Stream where error occurred
    step: number;                 // Step where error occurred
  };
}

const status = await orchex_status({
  sessionId: "sess_abc123def456"
});

if (status.status === "executing") {
  console.log(`Progress: ${status.progress.percentage}%`);
  console.log(`Current: ${status.progress.currentStream}`);
}

if (status.status === "completed") {
  console.log(`Completed in ${status.metrics.totalDuration}ms`);
  console.log(`Modified ${status.metrics.filesModified} files`);
}

if (status.status === "failed") {
  console.error(`Error: ${status.error.message}`);
  console.error(`Failed at: ${status.error.stream} step ${status.error.step}`);
}

{
  sessionId: string;              // Session identifier
  executionId: string;            // Unique execution identifier
  status: "executing";            // Initial execution status
  startedAt: string;              // ISO 8601 timestamp
  
  plan: {                         // Execution plan overview
    streams: number;              // Number of streams
    estimatedSteps: number;       // Total estimated steps
    estimatedDuration: number;    // Estimated duration (ms)
  };
  
  options: {                      // Execution configuration
    dryRun: boolean;              // Dry run mode
    parallel: boolean;            // Parallel execution
    maxSteps: number;             // Maximum steps
  };
}

// Execute the orchestration
const execution = await orchex_execute({
  sessionId: "sess_abc123def456",
  confirm: true,
  parallel: false
});

console.log(`Execution started: ${execution.executionId}`);
console.log(`Estimated duration: ${execution.plan.estimatedDuration}ms`);

// Poll for status
let status;
do {
  await new Promise(resolve => setTimeout(resolve, 2000));
  status = await orchex_status({ sessionId: execution.sessionId });
  console.log(`Progress: ${status.progress?.percentage}%`);
} while (status.status === "executing");

if (status.status === "completed") {
  console.log("Orchestration completed successfully!");
}

{
  sessionId: string;              // Session identifier
  status: "completed" | "failed"; // Final session status
  
  summary: {                      // Execution summary
    task: string;                 // Original task description
    streamsExecuted: number;      // Number of streams executed
    stepsExecuted: number;        // Total steps executed
    duration: number;             // Total duration (ms)
  };
  
  results: {                      // Execution results
    filesCreated: string[];       // New files created
    filesModified: string[];      // Existing files modified
    filesDeleted: string[];       // Files deleted
    artifacts: Array<{            // Generated artifacts
      path: string;               // File path
      type: string;               // Artifact type
      description: string;        // What it contains
    }>;
  };
  
  metrics: {                      // Performance metrics
    totalDuration: number;        // Total time (ms)
    tokensUsed: number;           // Total tokens consumed
    averageStepTime: number;      // Average step duration (ms)
    efficiency: number;           // Efficiency score (0-100)
  };
  
  validation: {                   // Validation results
    commandsPassed: number;       // Successful commands
    commandsFailed: number;       // Failed commands
    testsPassed: boolean;         // Overall test status
    lintPassed: boolean;          // Lint status
  };
  
  saved?: {                       // Present if saveResults=true
    historyId: string;            // Execution history ID
    url: string;                  // View URL (if cloud enabled)
  };
}

const result = await orchex_complete({
  sessionId: "sess_abc123def456",
  saveResults: true
});

console.log("Orchestration Summary:");
console.log(`- Task: ${result.summary.task}`);
console.log(`- Streams: ${result.summary.streamsExecuted}`);
console.log(`- Duration: ${result.summary.duration}ms`);
console.log(`\nFiles Changed:`);
console.log(`- Created: ${result.results.filesCreated.length}`);
console.log(`- Modified: ${result.results.filesModified.length}`);
console.log(`- Deleted: ${result.results.filesDeleted.length}`);
console.log(`\nValidation:`);
console.log(`- Tests: ${result.validation.testsPassed ? 'PASSED' : 'FAILED'}`);
console.log(`- Lint: ${result.validation.lintPassed ? 'PASSED' : 'FAILED'}`);

if (result.saved) {
  console.log(`\nView results: ${result.saved.url}`);
}

// 1. Initialize session
const session = await orchex_init({
  task: "Add user authentication to the API",
  files: ["src/server.ts", "src/routes/"],
  maxSteps: 20
});

// 2. Add streams
await orchex_add_stream({
  sessionId: session.sessionId,
  streamId: "api-auth-routes",
  description: "Create authentication routes",
  plan: `
    1. Create src/routes/auth.ts with login/logout
    2. Add JWT token generation
    3. Integrate with Express server
  `,
  commands: [
    { command: "npm test", critical: true }
  ]
});

await orchex_add_stream({
  sessionId: session.sessionId,
  streamId: "api-auth-middleware",
  description: "Add authentication middleware",
  plan: `
    1. Create src/middleware/auth.ts
    2. Add token validation
    3. Protect existing routes
  `
});

// 3. Execute
const execution = await orchex_execute({
  sessionId: session.sessionId,
  confirm: true
});

// 4. Monitor progress
let status;
do {
  await new Promise(resolve => setTimeout(resolve, 3000));
  status = await orchex_status({ 
    sessionId: session.sessionId 
  });
  
  if (status.progress) {
    console.log(
      `Progress: ${status.progress.percentage}% ` +
      `(${status.progress.currentStream})`
    );
  }
} while (status.status === "executing");

// 5. Complete and get results
const result = await orchex_complete({
  sessionId: session.sessionId,
  saveResults: true
});

if (result.status === "completed") {
  console.log("✓ Authentication added successfully!");
  console.log(`Modified ${result.results.filesModified.length} files`);
} else {
  console.error("✗ Orchestration failed");
}

{
  error: "SESSION_NOT_FOUND",
  message: "Session sess_abc123 does not exist or has expired",
  code: 404
}

{
  error: "SESSION_LOCKED",
  message: "Cannot modify session during execution",
  code: 409
}

{
  error: "NO_STREAMS",
  message: "At least one stream must be added before execution",
  code: 400
}

{
  error: "EXECUTION_FAILED",
  message: "Stream 'api-auth-routes' failed at step 3",
  details: {
    stream: "api-auth-routes",
    step: 3,
    reason: "Test command failed"
  },
  code: 500
}

try {
  const execution = await orchex_execute({
    sessionId: session.sessionId
  });
  
  // Monitor execution...
  
} catch (error) {
  if (error.code === 409) {
    // Session already executing - get status
    const status = await orchex_status({ 
      sessionId: session.sessionId 
    });
    console.log("Execution already in progress:", status);
  } else if (error.code === 404) {
    // Session expired - create new one
    console.log("Session expired, creating new session...");
  } else {
    // Other error - complete and inspect
    const result = await orchex_complete({ 
      sessionId: session.sessionId 
    });
    console.error("Execution failed:", result);
  }
}

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "orchex": {
      "command": "node",
      "args": ["/path/to/orchex/bin/orchex-server.js"],
      "env": {
        "ORCHEX_API_KEY": "orchex_sk_..."
      }
    }
  }
}

try {
  // ... orchestration workflow
} finally {
  await orchex_complete({ sessionId });
}

// One session, multiple streams
const session = await orchex_init({ task: "Feature X" });
await orchex_add_stream({ sessionId, streamId: "backend", ... });
await orchex_add_stream({ sessionId, streamId: "frontend", ... });
await orchex_execute({ sessionId });

// Overkill for simple tasks
const session = await orchex_init({ task: "Fix typo" });
// Just use orchex_run() or CLI instead

// Good: Clear separation of concerns
await orchex_add_stream({ streamId: "api-routes", ... });
await orchex_add_stream({ streamId: "api-middleware", ... });
await orchex_add_stream({ streamId: "api-tests", ... });

commands: [
  { command: "npm test", critical: true },
  { command: "npm run lint", critical: false },
  { command: "npm run typecheck", critical: true }
]

// Minimal for isolated changes
context: { depth: "minimal" }

// Moderate for feature development
context: { depth: "moderate" }

// Comprehensive for refactoring
context: { depth: "comprehensive" }

let pollInterval = 2000;
while (status.status === "executing") {
  await new Promise(resolve => setTimeout(resolve, pollInterval));
  status = await orchex_status({ sessionId });
  pollInterval = Math.min(pollInterval * 1.5, 10000);
}

if (status.progress) {
  console.log(
    `[${status.progress.percentage}%] ` +
    `${status.progress.currentStream} ` +
    `(${status.progress.currentStep}/${status.progress.totalSteps})`
  );
}

// Independent streams can run in parallel
await orchex_add_stream({ 
  streamId: "backend-tests",
  // ... backend test stream
});

await orchex_add_stream({ 
  streamId: "frontend-tests",
  // ... frontend test stream  
});

// Execute in parallel
await orchex_execute({ 
  sessionId,
  parallel: true  // Faster for independent streams
});

// Preview changes without executing
const session = await orchex_init({
  task: "Refactor authentication",
  dryRun: true
});

await orchex_add_stream({ ... });
const execution = await orchex_execute({ sessionId });

// Get plan details
const result = await orchex_complete({ sessionId });
console.log("Planned changes:", result.results);

// Start with minimal context
await orchex_add_stream({
  streamId: "core-changes",
  context: { 
    files: ["src/auth.ts"],
    depth: "minimal" 
  },
  // ...
});

// Expand context for dependent changes
await orchex_add_stream({
  streamId: "integration",
  context: { 
    files: ["src/auth.ts", "src/routes/"],
    depth: "moderate"
  },
  // ...
});