A control plane for authoring, managing, and orchestrating AI personas and workflows through MCP (Model Context Protocol).

Pilot Framework enables you to create structured AI personas with defined missions, workflows, and constraints, then expose them as tools that AI agents (like Cursor, Claude Desktop) can discover and use. Build complex multi-step workflows that orchestrate multiple personas to accomplish sophisticated tasks.

Part of the PilotFrame ecosystem

Pilot Framework is a platform that bridges the gap between AI agent capabilities and structured, reusable expertise. Instead of asking an AI agent to "be a code reviewer" every time, you define a persona once with specific instructions, constraints, and workflows. That persona becomes a discoverable tool that any MCP-compatible AI agent can use.

• Personas: Structured AI roles with defined missions, inputs, workflows, success criteria, and constraints. Each persona is a reusable expert that AI agents can invoke.
• Workflows: Multi-step processes that orchestrate multiple personas in sequence, cycles, or parallel execution patterns.
• MCP Integration: Personas and workflows are automatically exposed as MCP tools, making them discoverable by AI agents like Cursor and Claude Desktop.

Create personas and workflows through natural language conversation. The AI Assistant understands your requirements and guides you through the creation process, generating valid specifications that match Pilot Framework schemas.

• Visual Editor: Create and edit persona specifications through an intuitive UI
• Schema Validation: Automatic validation ensures personas meet Pilot Framework standards
• Version Control: Track changes and maintain persona history
• MCP Tool Generation: Each persona automatically becomes an MCP tool (e.g., persona.seo_specialist.get_specification)

• Multi-Persona Workflows: Chain multiple personas together to accomplish complex tasks
• Execution Patterns: Support for sequential, parallel, cycle, and mixed execution patterns
• Conditional Logic: Define handoff rules and conditions between workflow steps
• Workflow Tools: Workflows are exposed as MCP tools for AI agents to execute

• HTTP-Based MCP Server: Built-in MCP server endpoint (/mcp) that exposes personas and workflows
• Tool Discovery: AI agents automatically discover available personas and workflows
• Resource Access: Personas and workflows are accessible as MCP resources
• No Separate Process: MCP server is integrated into the control plane

• Persistent Conversations: All AI Assistant conversations are saved and can be resumed
• Context Management: Attach personas/workflows to conversations to maintain context
• Message Exclusion: Mark messages as excluded from API context to reduce token usage
• History Truncation: Automatic truncation to last 40 messages to prevent token limits

The central server that manages personas, workflows, and exposes them via REST API and MCP protocol. Includes:

• REST API for CRUD operations
• MCP server endpoint for AI agent integration
• Schema validation engine
• Conversation persistence
• AI Assistant service

React-based web interface for:

• Creating and editing personas
• Designing workflows
• Managing conversations with the AI Assistant
• Testing MCP tools

JSON-based specifications that define:

• Mission: What the persona does
• Inputs: What information it needs
• Workflow: Step-by-step process
• Success Criteria: How to measure success
• Constraints: Rules and limitations
• Handoff Expectations: How it interacts with other personas

JSON-based definitions that specify:

• Steps: Sequence of personas to execute
• Execution Pattern: Sequential, parallel, cycle, or mixed
• Execution Guidance: Rules for when and how to proceed
• Exit Conditions: When the workflow is complete

• Node.js 20+
• Azure OpenAI account (for AI Assistant feature)

1. Clone and install dependencies:

   npm install
   cd frontend && npm install && cd ..

2. Configure environment: Create a .env file:

   PORT=4000
   AUTH_JWT_SECRET=LOCAL_DEV_TOKEN
   AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
   AZURE_OPENAI_API_KEY=your-api-key
   AZURE_OPENAI_DEPLOYMENT_NAME=gpt-5-chat

3. Start the control plane:

   npm run dev

4. Start the frontend (in a new terminal):

   cd frontend
   npm run dev

5. Configure Cursor for MCP: Add to ~/.cursor/mcp.json:

   {
     "mcpServers": {
       "pilotframe-mcp": {
         "url": "http://localhost:4000/mcp",
         "headers": {
           "Authorization": "Bearer <YOUR_JWT_TOKEN>"
         }
       }
     }
   }

For detailed setup instructions, see the Complete Setup Guide below.

node -e "console.log(require('jsonwebtoken').sign({ sub: 'dev-user', roles: ['Persona.Author'] }, 'LOCAL_DEV_TOKEN'))"

Save this token for frontend and MCP configuration.

Terminal 1 - Control Plane:

npm run dev

Terminal 2 - Frontend:

cd frontend && npm run dev

1. Open http://localhost:5173
2. Enter Control Plane URL: http://localhost:4000
3. Paste your JWT token
4. Click "Save Connection"

Add to ~/.cursor/mcp.json (or C:\Users\<YourUsername>\.cursor\mcp.json on Windows):

{
  "mcpServers": {
    "pilotframe-mcp": {
      "url": "http://localhost:4000/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_JWT_TOKEN>"
      }
    }
  }
}

Restart Cursor to activate MCP integration.

1. In the frontend UI, click "+ New Persona"
2. Enter an ID (e.g., seo_specialist)
3. Fill in the specification JSON
4. Click "Save Persona"

The persona will automatically be available as an MCP tool: persona.seo_specialist.get_specification

• Port 4000 in use: Change PORT in .env or kill the process using the port
• 401 Unauthorized: Verify AUTH_JWT_SECRET matches the secret used to generate your token
• MCP not working: Ensure control plane is running and Cursor is restarted after configuration changes

For detailed troubleshooting and advanced configuration, see the technical documentation in /docs.

All technical documentation is located in the /docs folder:

• Architecture - System architecture and design decisions

  • Spec Registry Domain
  • Adapter Template
  • Sandbox Runner

• Features - Feature documentation

  • AI-Assisted Creation

• MCP Integration - MCP protocol details and tool structure

• UI Guidelines - UI rules and MCP compliance

• Operations - Deployment and CI/CD guides

  • CI/CD Blueprint
  • Secrets Management

• Vision - Project vision and roadmap

• REST API endpoints are documented in the codebase
• MCP tools are automatically discoverable via the /mcp/tools endpoint

pf-framework/
├── src/server/          # Control plane server (Express + TypeScript)
├── frontend/            # React UI for persona/workflow management
├── schemas/             # JSON schemas for persona and workflow validation
├── examples/            # Example personas and workflows
├── docs/                # Technical documentation
├── migrations/          # Database migrations
└── mcp-server/          # Standalone MCP server (optional, HTTP endpoint preferred)

• REST API: Full CRUD operations for personas and workflows
• Schema Validation: Automatic validation using JSON Schema
• Type Safety: Full TypeScript support
• Extensible: Plugin architecture for custom persona types

• Tool Discovery: Automatic discovery of available personas and workflows
• Specification Access: Get detailed persona specifications on demand
• Workflow Execution: Execute multi-step workflows through MCP
• Resource Access: Access personas and workflows as MCP resources

• AI Assistant: Natural language interface for creating personas
• Visual Editors: Intuitive UI for editing specifications
• Conversation History: Persistent conversations with context management
• Template Library: Example personas and workflows to learn from

This is an active development project. For contribution guidelines and development setup, see the technical documentation in /docs.

[Add your license here]

For issues, questions, or contributions, please refer to the documentation in /docs or open an issue in the repository.