Cursor Integration

Orchex integrates with Cursor through the Model Context Protocol (MCP), enabling you to orchestrate complex development workflows directly from your editor.

Overview

Cursor's MCP support allows you to:

  • Execute manifests from within Cursor's AI chat
  • View execution history and artifacts
  • Generate manifests based on your project context
  • Monitor progress with real-time updates

Prerequisites

  • Cursor IDE version 0.40.0 or later
  • Node.js 18+ installed
  • Orchex installed globally or in your project

Installation

1. Install Orchex

npm install -g @wundam/orchex

2. Configure MCP in Cursor

Cursor uses a configuration file to define MCP servers. The location depends on your operating system:

macOS/Linux:

~/.cursor/mcp.json

Windows:

%APPDATA%\Cursor\mcp.json

3. Add Orchex Server

Edit your mcp.json file to include the Orchex MCP server. Configure for your preferred LLM provider:

Anthropic (Claude):

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

OpenAI (GPT-4, GPT-4.5):

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Google Gemini:

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Ollama (local models):

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"],
      "env": {
        "OLLAMA_BASE_URL": "http://localhost:11434"
      }
    }
  }
}

Alternative: Project-Local Installation

If you prefer to use a project-local installation:

{
  "mcpServers": {
    "orchex": {
      "command": "node",
      "args": ["./node_modules/.bin/orchex", "mcp"],
      "cwd": "/path/to/your/project",
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. Restart Cursor

Restart Cursor to load the new MCP configuration.

Configuration Options

Environment Variables

You can configure Orchex behavior through environment variables in the env section:

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "ORCHEX_PROVIDER": "openai",
        "ORCHEX_CONCURRENCY": "3",
        "ORCHEX_OUTPUT_DIR": ".orchex",
        "ORCHEX_CLOUD_API_KEY": "your-cloud-api-key"
      }
    }
  }
}

LLM Provider Variables (one required):

  • ANTHROPIC_API_KEY - Anthropic Claude API key
  • OPENAI_API_KEY - OpenAI GPT-4/4.5 API key
  • GEMINI_API_KEY or GOOGLE_API_KEY - Google Gemini API key
  • OLLAMA_BASE_URL - Ollama server URL (default: http://localhost:11434)

Provider Selection (optional):

  • ORCHEX_PROVIDER - Force specific provider: anthropic, openai, gemini, ollama

Other Variables:

  • ORCHEX_CONCURRENCY - Maximum parallel streams (default: 5)
  • ORCHEX_OUTPUT_DIR - Directory for artifacts (default: .orchex)
  • ORCHEX_CLOUD_API_KEY - API key for Orchex Cloud features
  • ORCHEX_LOG_LEVEL - Logging verbosity: debug, info, warn, error

Working Directory

By default, Orchex runs in the directory where Cursor is opened. You can override this with the cwd option:

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"],
      "cwd": "/absolute/path/to/project"
    }
  }
}

Using Orchex in Cursor

Basic Workflow

  1. Open Cursor's AI Chat (Cmd+L or Ctrl+L)
  2. Ask Cursor to use Orchex for complex tasks
  3. Review the execution plan before approving
  4. Monitor progress in the chat interface
  5. Review artifacts in the .orchex directory

Example Interactions

Execute an Existing Manifest

You: Use Orchex to execute the manifest at ./manifests/add-auth.yaml

Cursor will:

  1. Read the manifest file
  2. Show you the execution plan
  3. Execute each stream in dependency order
  4. Report results and artifacts

Generate and Execute a Manifest

You: Use Orchex to add TypeScript support to this project. 
I need:
- tsconfig.json configuration
- Rename .js files to .ts
- Add type definitions
- Update package.json

Cursor will:

  1. Generate a manifest based on your request
  2. Show you the proposed manifest
  3. Execute it after your approval
  4. Report results

View Execution History

You: Show me the last Orchex execution

Cursor will display:

  • Execution summary
  • Stream results
  • Artifacts produced
  • Any errors or warnings

Orchestration Workflow

How Cursor + Orchex Works Together

sequenceDiagram
    participant User
    participant Cursor
    participant MCP
    participant Orchex
    participant Claude

    User->>Cursor: Request complex task
    Cursor->>MCP: Invoke orchex_execute
    MCP->>Orchex: Execute manifest
    Orchex->>Claude: Execute stream 1
    Claude-->>Orchex: Results
    Orchex->>Claude: Execute stream 2
    Claude-->>Orchex: Results
    Orchex-->>MCP: Execution complete
    MCP-->>Cursor: Results + artifacts
    Cursor-->>User: Display results

Stream Execution Flow

  1. Manifest Parsing: Orchex reads and validates the manifest
  2. Dependency Resolution: Builds execution graph from stream dependencies
  3. Context Building: Gathers files and information for each stream
  4. Parallel Execution: Runs independent streams concurrently
  5. Artifact Collection: Saves outputs to .orchex directory
  6. Verification: Runs optional quality checks
  7. Reporting: Returns results to Cursor

Advanced Usage

Using with Cursor Composer

Cursor's Composer feature works seamlessly with Orchex for multi-file edits:

You: @orchex Use Composer to refactor the authentication system.
Create a manifest that:
1. Extracts auth logic to separate module
2. Updates all imports
3. Adds tests
4. Updates documentation

Orchex will coordinate with Composer to:

  • Show all file changes in diff view
  • Allow you to accept/reject each change
  • Maintain consistency across files

Manifest Generation

Ask Cursor to generate manifests for you:

You: Generate an Orchex manifest to migrate from Jest to Vitest.
Include:
- Config file updates
- Test file migrations
- Package.json changes
- CI/CD updates

Cursor will:

  1. Analyze your project structure
  2. Generate a comprehensive manifest
  3. Save it to your project
  4. Optionally execute it

Combining with Other MCP Tools

Orchex works alongside other MCP servers in Cursor:

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token"
      }
    }
  }
}

Example workflow:

You: 
1. Use GitHub MCP to fetch issue #123
2. Use Orchex to implement the feature
3. Use GitHub MCP to create a PR

Best Practices

1. Start Small

Begin with simple manifests and gradually increase complexity:

# Good: Simple, focused manifest
feature: fix-typo
streams:
  - id: fix-readme
    plan: Fix typos in README.md
    owns:
      - README.md

2. Use Descriptive Stream IDs

Helps with debugging and understanding execution flow:

streams:
  - id: update-types        # ✅ Clear
  - id: update-tests        # ✅ Clear
  - id: stream-1           # ❌ Unclear

3. Leverage Dependencies

Ensure streams execute in the correct order:

streams:
  - id: create-types
    plan: Create TypeScript type definitions
    
  - id: update-implementation
    plan: Update implementation to use new types
    deps:
      - create-types  # Waits for types to be created

4. Review Before Execution

Always review the execution plan:

You: Show me the execution plan before running this manifest

5. Use Verification

Add verification steps to catch issues early:

streams:
  - id: add-feature
    plan: Add new feature
    verify:
      - npm run type-check
      - npm test

6. Organize Manifests

Keep manifests in a dedicated directory:

project/
├── .orchex/          # Artifacts
├── manifests/        # Your manifests
│   ├── features/
│   ├── bugs/
│   └── refactors/
└── src/

Troubleshooting

MCP Server Not Found

Symptom: Cursor shows "Orchex MCP server not available"

Solutions:

  1. Check mcp.json syntax
  2. Verify Node.js and Orchex are installed
  3. Restart Cursor
  4. Check logs in Cursor's Developer Tools (Cmd+Shift+I)

API Key Issues

Symptom: "API key not configured" error

Solutions:

  1. Add the appropriate API key to mcp.json env section:
    • Anthropic: ANTHROPIC_API_KEY
    • OpenAI: OPENAI_API_KEY
    • Gemini: GEMINI_API_KEY or GOOGLE_API_KEY
    • Ollama: OLLAMA_BASE_URL (no key needed)
  2. Or set globally: export OPENAI_API_KEY=your-key
  3. Restart Cursor after changes
  4. Optionally set ORCHEX_PROVIDER to explicitly select your provider

Execution Hangs

Symptom: Orchex execution never completes

Solutions:

  1. Check for circular dependencies in manifest
  2. Reduce concurrency: ORCHEX_CONCURRENCY=1
  3. Enable debug logging: ORCHEX_LOG_LEVEL=debug
  4. Check .orchex/artifacts/*/execution.json for errors

File Permission Errors

Symptom: "EACCES: permission denied"

Solutions:

  1. Ensure Cursor has write permissions to project directory
  2. Check .orchex directory permissions
  3. Run Cursor with appropriate user permissions

Context Too Large

Symptom: "Context exceeds token limit"

Solutions:

  1. Use more specific reads paths
  2. Split into smaller streams
  3. Exclude large files from reads and owns
  4. See Token Management for details

Performance Tips

1. Optimize Concurrency

Adjust based on your API rate limits:

{
  "env": {
    "OPENAI_API_KEY": "your-key",
    "ORCHEX_CONCURRENCY": "3"
  }
}

Tip: OpenAI and Anthropic have similar rate limits. Ollama can handle higher concurrency since it runs locally.

2. Minimize Context

Only include necessary files:

streams:
  - id: update-component
    reads:
      - src/components/Button.tsx  # Specific file
    # Instead of:
    # - src/**/*.tsx  # All TypeScript files

3. Use Stream Dependencies

Parallelize independent work:

streams:
  - id: update-frontend
    # No dependencies - runs immediately
    
  - id: update-backend
    # No dependencies - runs in parallel with frontend
    
  - id: integration-test
    deps:
      - update-frontend
      - update-backend

4. Cache Artifacts

Reuse previous execution results when iterating:

You: Re-run the manifest, but skip streams that succeeded last time

Examples

Example 1: Adding a New Feature

# manifests/add-search.yaml
feature: add-search
description: Add search functionality to the app

streams:
  - id: create-search-component
    plan: |
      Create a SearchBar React component with:
      - Text input for search query
      - Debounced search (300ms)
      - Loading state
      - TypeScript types
    owns:
      - src/components/SearchBar.tsx
    reads:
      - src/components/Button.tsx  # Reference for styling
      
  - id: add-search-api
    plan: Create API endpoint for search at /api/search
    owns:
      - src/api/search.ts
    reads:
      - src/api/users.ts  # Reference for API patterns
      
  - id: integrate-search
    plan: |
      Integrate SearchBar component into HomePage:
      - Import and render SearchBar
      - Handle search results
      - Show loading state
    owns:
      - src/pages/HomePage.tsx
    deps:
      - create-search-component
      - add-search-api
      
  - id: add-tests
    plan: |
      Add tests for:
      - SearchBar component
      - Search API endpoint
    owns:
      - src/components/SearchBar.test.tsx
      - src/api/search.test.ts
    deps:
      - create-search-component
      - add-search-api
    verify:
      - npm test

Usage in Cursor:

You: Execute manifests/add-search.yaml with Orchex

Example 2: Bug Fix

# manifests/fix-auth-bug.yaml
feature: fix-auth-timeout
description: Fix authentication timeout issue (#142)

streams:
  - id: analyze-issue
    plan: |
      Analyze the authentication timeout issue:
      1. Review current token refresh logic
      2. Identify the race condition
      3. Document findings in comments
    reads:
      - src/auth/tokenManager.ts
      - src/api/client.ts
      
  - id: fix-race-condition
    plan: |
      Fix the race condition:
      1. Add mutex lock to token refresh
      2. Queue concurrent refresh requests
      3. Add error handling
    owns:
      - src/auth/tokenManager.ts
    deps:
      - analyze-issue
      
  - id: update-tests
    plan: |
      Add tests for:
      - Concurrent token refresh
      - Race condition prevention
      - Error scenarios
    owns:
      - src/auth/tokenManager.test.ts
    deps:
      - fix-race-condition
    verify:
      - npm test -- tokenManager

Example 3: Refactoring

# manifests/refactor-state-management.yaml
feature: refactor-to-zustand
description: Migrate from Redux to Zustand

streams:
  - id: create-stores
    plan: |
      Create Zustand stores to replace Redux:
      - userStore (from userSlice)
      - appStore (from appSlice)
      - cartStore (from cartSlice)
    owns:
      - src/stores/userStore.ts
      - src/stores/appStore.ts
      - src/stores/cartStore.ts
    reads:
      - src/redux/userSlice.ts
      - src/redux/appSlice.ts
      - src/redux/cartSlice.ts
      
  - id: update-components
    plan: |
      Update all components to use Zustand stores:
      - Replace useSelector with store hooks
      - Replace useDispatch with store actions
      - Remove Redux Provider
    owns:
      - src/components/**/*.tsx
    deps:
      - create-stores
      
  - id: cleanup-redux
    plan: Remove Redux files and dependencies
    owns:
      - src/redux/
      - src/store.ts
    owns:
      - package.json
    deps:
      - update-components
      
  - id: update-tests
    plan: Update tests to use Zustand stores
    owns:
      - src/**/*.test.tsx
    deps:
      - update-components
    verify:
      - npm test
      - npm run type-check

Integration with Cursor Features

Cursor Rules

Combine Orchex with Cursor's .cursorrules file:

# .cursorrules
When using Orchex:
- Always review the manifest before execution
- Use descriptive stream IDs
- Add verification steps for critical changes
- Keep manifests focused and modular

Cursor Tab

Use Cursor's Tab autocomplete with Orchex:

  1. Start typing a manifest path
  2. Tab suggests existing manifests
  3. Execute with @orchex execute <path>

Cursor Chat Context

Orchex automatically includes:

  • Current file context
  • Selected code
  • Recent changes
  • Project structure

Cloud Features

When using Orchex Cloud:

Team Sharing

You: Execute the manifest and share with my team

Orchex will:

  1. Execute locally
  2. Upload to Orchex Cloud
  3. Generate shareable link

Execution History

You: Show me our team's Orchex executions from last week

Intelligence Features

Orchex Cloud provides:

  • Pattern detection from team executions
  • Automatic healing suggestions
  • Performance optimization tips

See Cloud Overview for details.

Next Steps

Resources

Feedback

Have issues or suggestions for the Cursor integration?