MCP Prompts Architecture

Overview

Orchestre introduces a revolutionary approach to AI command systems - native MCP prompts. Instead of file-based commands that need to be installed in each project, Orchestre now provides intelligent prompts directly through the MCP protocol. This architectural shift represents a fundamental improvement in how developers interact with AI orchestration tools.

The Evolution: From Files to Protocol

The Old Way (v1-v4)

Previously, Orchestre required:

• Installing command files in every project
• Managing command files in projects
• Updating commands manually when Orchestre improved
• Dealing with file system permissions and paths

The New Way

Now, Orchestre provides:

• Direct prompt availability through MCP
• No installation required per project
• Automatic updates when server improves
• Clean project directories

Architecture Components

1. MCP Prompt Registration

Orchestre registers prompts with the MCP protocol:

// Simplified example
class OrchestreServer {
  async listPrompts() {
    return [
      {
        name: "orchestrate",
        description: "Analyze requirements and generate adaptive development plans",
        arguments: [
          { name: "requirements", description: "What to build", required: true }
        ]
      },
      // ... more prompts
    ];
  }
}

2. Dynamic Prompt Engine

Prompts are generated dynamically based on:

• Project Context: Discovered architecture and patterns
• User Intent: Parsed from natural language
• Template Knowledge: Specialized guidance per template
• Historical Context: Learning from previous interactions

3. Prompt Composition

Complex prompts are built from composable pieces:

Example flow:

1. User: /orchestrate "Build a payment system"
2. Base: Core orchestration logic
3. Discovery: Find existing patterns
4. Adaptation: Adjust for Stripe/MakerKit/etc
5. Strategy: Generate specific plan

4. Protocol Integration

MCP handles the communication:

Benefits of MCP Prompts

1. Zero Installation

• No files to copy
• No directories to create
• No permissions to manage
• Works immediately when server connected

2. Always Up-to-Date

• Server improvements instantly available
• No manual updates needed
• Version conflicts eliminated
• Consistent experience across projects

3. Context-Aware Intelligence

• Prompts adapt to each project
• Discovery happens at runtime
• No static templates
• True dynamic behavior

4. Cleaner Projects

• No command file clutter
• No version control noise
• No maintenance burden
• Focus on your code, not tools

5. Better Performance

• No file I/O overhead
• Direct protocol communication
• Streaming responses
• Optimized execution

Implementation Details

Prompt Types

Orchestre provides three categories of prompts:

1. Core Prompts - Essential orchestration capabilities

   • /orchestrate - Adaptive planning
   • /create - Project initialization
   • /execute-task - Intelligent execution

2. Specialized Prompts - Domain-specific intelligence

   • /security-audit - Security analysis
   • /add-enterprise-feature - Production features
   • /migrate-to-teams - Multi-tenancy

3. Knowledge Prompts - Learning and documentation

   • /document-feature - Contextual docs
   • /discover-context - Codebase analysis

Prompt Lifecycle

Error Handling

MCP prompts include robust error handling:

• Invalid arguments → Clear error messages
• Missing context → Graceful degradation
• API failures → Fallback strategies
• Timeout handling → Partial results

Comparison with File-Based Commands

Aspect	File Commands (Legacy)	MCP Prompts (Current)
Installation	Required per project	None needed
Updates	Manual process	Automatic
Storage	Project files	Server memory
Flexibility	Static templates	Dynamic adaptation
Performance	File I/O overhead	Direct protocol
Maintenance	User responsibility	Server managed

Future Possibilities

The MCP prompt architecture enables:

1. AI-Generated Prompts - Prompts that create new prompts
2. Contextual Learning - Prompts that improve from usage
3. Team Sharing - Prompts that learn from team patterns
4. Cross-Project Intelligence - Knowledge transfer between projects
5. Real-time Adaptation - Prompts that evolve during execution

Migration Impact

For users upgrading from file-based commands:

What Changes

• No more install_commands tool needed
• No more command files in projects
• Commands available immediately via MCP

What Stays the Same

• Same command names and purposes
• Same intelligent behavior
• Same powerful orchestration

How to Migrate

1. Update Orchestre server to latest
2. Remove any legacy command directories
3. Start using prompts directly

Technical Architecture

Server-Side Components

Protocol Flow

Detailed Prompt Discovery Mechanism

When a user invokes a prompt, Orchestre follows this discovery pattern:

Resource URI Scheme

Orchestre uses a custom URI scheme for accessing different types of resources:

orchestre://[type]/[path]

Resource Types:

1. Project Resources

   orchestre://project/structure     # Project file tree
   orchestre://project/dependencies  # Package dependencies
   orchestre://project/config       # Configuration files

2. Memory Resources

   orchestre://memory/               # Root CLAUDE.md
   orchestre://memory/orchestre      # .orchestre/CLAUDE.md
   orchestre://memory/features/auth  # Feature-specific memory

3. Template Resources

   orchestre://template/makerkit/patterns    # Template patterns
   orchestre://template/makerkit/conventions # Coding conventions
   orchestre://template/makerkit/structure   # Expected structure

4. Knowledge Resources

   orchestre://knowledge/patterns    # Discovered patterns
   orchestre://knowledge/decisions   # Architecture decisions
   orchestre://knowledge/learnings   # Project learnings

Example Usage in Prompts:

// In a prompt handler
const projectStructure = await getResource('orchestre://project/structure');
const memory = await getResource('orchestre://memory/');
const templatePatterns = await getResource('orchestre://template/makerkit/patterns');

// Adapt behavior based on resources
if (projectStructure.includes('monorepo')) {
  // Adjust for monorepo structure
}

if (memory.includes('multi-tenant')) {
  // Include tenant isolation patterns
}

Memory Integration

MCP prompts seamlessly integrate with Orchestre's distributed memory:

• Read CLAUDE.md files for context
• Update documentation automatically
• Preserve knowledge across sessions
• Build on previous interactions

Best Practices

For Users

1. Trust the discovery - Let prompts explore your project
2. Provide context - Clear requirements get better results
3. Iterate naturally - Prompts learn from feedback
4. Embrace adaptation - Each run can be different

For Contributors

1. Keep prompts dynamic - Avoid static responses
2. Enable discovery - Don't assume project structure
3. Support streaming - Long operations should update
4. Handle errors gracefully - Clear, actionable messages

Conclusion

The shift to MCP prompts represents a fundamental improvement in AI-assisted development. By moving intelligence from static files to dynamic protocol interactions, Orchestre delivers a cleaner, more powerful, and more maintainable approach to AI orchestration.

No more installation. No more updates. Just intelligent prompts that adapt to your needs, available instantly through the MCP protocol.