# Interactive Collection Builder Demo

## Quick Start

The `orchestra new` command provides an interactive wizard to help you create test collections without memorizing YAML syntax.

## Usage

```bash
orchestra new [output_file]

# Examples:
orchestra new schemas/my_test.yaml
orchestra new tests/api_test.yaml
orchestra new  # Defaults to schemas/my_collection.yaml
```

## Walkthrough

### 1. Welcome Screen

```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ 🎵 Orchestra Collection Builder                      ┃
┃                                                        ┃
┃ This wizard will help you create a new test          ┃
┃ collection. Answer a few questions, and we'll        ┃
┃ generate the YAML for you!                           ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
```

### 2. Collection Name

```
What would you like to name this collection? [My MCP Test]: DeepWiki API Test
✓ Collection name: DeepWiki API Test
```

### 3. Transport Type

```
How does your MCP server run?
  1. Local (STDIO) - Runs as a subprocess (e.g., npx, python)
  2. Remote (HTTP) - Cloud-hosted server with a URL
  3. SSE - Server-Sent Events

Choose transport type [2]: 2
```

### 4. Server Configuration

**For HTTP:**
```
Remote Server Configuration
Enter server URL [https://api.example.com/mcp]: https://mcp.deepwiki.com/mcp
✓ URL: https://mcp.deepwiki.com/mcp
```

**For STDIO:**
```
Local Server Configuration

Common patterns:
  1. npx -y @modelcontextprotocol/server-name
  2. python -m my_server
  3. node server.js
  4. Custom command

Choose a pattern [1]: 1
Enter npx package name [@modelcontextprotocol/server-memory]: 
✓ Command: npx -y @modelcontextprotocol/server-memory
```

### 5. Authentication

```
Does your server require authentication?
Add authentication? [y/N]: n
```

If yes:
```
  1. Bearer Token - Authorization: Bearer <token>
  2. API Key - X-API-Key: <key>
  3. Basic Auth - Username and password

Choose auth type [1]: 1
✓ Using Bearer token (set via environment variable)
```

### 6. Test Steps

```
Would you like to add test steps now?
You can add these later by editing the YAML file

Add test steps? [Y/n]: y

💡 Tip: Run orchestra inspect on your generated file
   to discover available tools and their parameters!

Add an example tool call step? [Y/n]: y
Enter tool name [example_tool]: ask_question
✓ Added example tool call + assertion
```

### 7. Preview & Save

```
📄 Generated Collection:

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ # Orchestra Test Collection                          ┃
┃ # Generated by: orchestra new                        ┃
┃ # Edit this file to customize your tests             ┃
┃                                                        ┃
┃ version: 1                                            ┃
┃ name: "DeepWiki API Test"                            ┃
┃                                                        ┃
┃ server:                                               ┃
┃   transport: "http"                                   ┃
┃   url: "https://mcp.deepwiki.com/mcp"                ┃
┃                                                        ┃
┃ defaults:                                             ┃
┃   timeout_ms: 30000                                   ┃
┃   retries: 0                                          ┃
┃                                                        ┃
┃ steps:                                                ┃
┃   - id: call_tool                                     ┃
┃     type: tool_call                                   ┃
┃     tool: "ask_question"                              ┃
┃     input:                                            ┃
┃       # Add your parameters here                      ┃
┃     save: "$"                                         ┃
┃                                                        ┃
┃   - id: verify_success                                ┃
┃     type: assert                                      ┃
┃     from: "call_tool"                                 ┃
┃     check:                                            ┃
┃       op: "no_error"                                  ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Save to schemas/deepwiki_test.yaml? [Y/n]: y

✅ Collection saved to schemas/deepwiki_test.yaml

Next steps:
  1. Run orchestra inspect schemas/deepwiki_test.yaml to discover tools
  2. Edit schemas/deepwiki_test.yaml to add your test steps
  3. Run orchestra run schemas/deepwiki_test.yaml to execute tests
```

## Workflow

The interactive builder streamlines the "cold start" problem:

### Before (Manual YAML)
```
1. Read docs to understand schema        [10 min]
2. Look up YAML syntax                    [5 min]
3. Write collection by hand              [15 min]
4. Fix indentation errors                 [5 min]
5. Run and debug                         [10 min]
────────────────────────────────────────
Total: ~45 minutes
```

### After (Interactive Builder)
```
1. Run orchestra new                      [3 min]
2. Answer questions                       [2 min]
3. Get generated YAML                     [instant]
4. Run orchestra inspect to discover tools [1 min]
5. Fill in actual parameters              [5 min]
────────────────────────────────────────
Total: ~11 minutes (75% faster!)
```

## Benefits

### For New Users
- ✅ No need to memorize YAML syntax
- ✅ Guided questions prevent mistakes
- ✅ Common patterns provided (npx, python, node)
- ✅ Automatic validation (can't generate invalid YAML)
- ✅ Clear next steps after generation

### For Experienced Users
- ✅ Fast boilerplate generation
- ✅ Can still edit YAML directly after
- ✅ Useful for trying new servers quickly
- ✅ Consistent structure across projects

### For Teams
- ✅ Standardized collection format
- ✅ Lower barrier to entry for QA engineers
- ✅ Self-documenting (comments in generated YAML)
- ✅ Reduces onboarding time

## Tips

1. **Start simple** - Add basic structure with wizard, fill details later
2. **Use inspect** - After generating, run `inspect` to see actual tools
3. **Iterate** - Generate scaffold → inspect → edit → test
4. **Save templates** - Keep generated files as starting points

## Examples

### Quick Remote Server Test
```bash
orchestra new schemas/api_test.yaml
# Answer: HTTP, https://api.example.com/mcp, no auth, no steps
orchestra inspect schemas/api_test.yaml  # See what's available
# Edit file to add actual test steps
orchestra run schemas/api_test.yaml
```

### Local Development
```bash
orchestra new schemas/dev_test.yaml
# Answer: STDIO, npx -y my-server, no auth, add example step
orchestra run schemas/dev_test.yaml  # Quick smoke test
```

### Authenticated API
```bash
orchestra new schemas/auth_test.yaml
# Answer: HTTP, url, bearer token, add example
# Edit to add actual tool calls
export API_TOKEN="your-token"
orchestra run schemas/auth_test.yaml
```

## Future Enhancements

Potential improvements:
- [ ] Multi-step wizard (add multiple tool calls)
- [ ] Load existing collection and modify it
- [ ] Server auto-detection (probe URL to discover transport)
- [ ] Tool discovery during wizard (if server is live)
- [ ] Template library (common patterns: CRUD, search, etc.)
- [ ] Export to different formats (JSON, Python code)

---

The interactive builder reduces the learning curve from 45 minutes to 11 minutes, making Orchestra accessible to a much wider audience.

