orchestry-mcp/README.md

Orchestry MCP Server for multi-session task management

# Orchestry 🎼

A powerful multi-session project task management system designed for orchestrating work across multiple LLM agents and human collaborators.

## 🎯 Purpose

Orchestry solves the challenge of managing complex projects that involve:
- Multiple LLM sessions working on the same project
- Human and AI collaboration with context preservation
- Task tracking across different work sessions
- Real-time synchronization between all participants

## 🚀 Quick Start

```bash
# Clone and setup
git clone https://github.com/yourusername/orchestry.git
cd orchestry

# Install dependencies
npm run install:all

# Start the application
./orchestry
```

The application will automatically open in your browser at `http://localhost:7530`.

## 🛠️ Features

- **Multi-Session Support**: Coordinate work across multiple LLM sessions and human users
- **Hierarchical Organization**: Projects → Workspaces → Goals → Tasks
- **Real-time Sync**: WebSocket-based live updates across all sessions
- **Kanban Board**: Visual task management with drag-and-drop
- **MCP Integration**: 13 tools for LLM agents to interact with the system
- **Session Tracking**: Track which session created or modified each element
- **Flexible Architecture**: Can run as MCP server, Web API, or both

## 📚 Usage Modes

### 1. Full Application Mode (Default)
```bash
./orchestry
```
Starts both the web UI and API server with automatic browser launch.

### 2. MCP Server Mode (for LLM Integration)
```bash
./orchestry mcp
```
Runs as an MCP server for Claude, GPT, or other LLM integration.

### 3. Custom Port Configuration
```bash
# Using environment variables
PORT=8080 PORT2=8081 ./orchestry

# Or using .env file
cp .env.example .env
# Edit .env with your preferred ports
./orchestry
```

## 🏗️ Architecture

```
orchestry/
├── server/          # TypeScript backend
│   ├── src/
│   │   ├── database.ts     # SQLite database layer
│   │   ├── tools/          # MCP tool definitions
│   │   └── unified-server.ts # Main server
├── web/             # React frontend
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── stores/         # Zustand state management
│   │   └── App.tsx
├── shared/          # Shared TypeScript types
└── orchestry        # Main launcher script
```

## 🔧 MCP Tools

Orchestry provides these tools for LLM integration:

- `create_project` - Create a new project
- `list_projects` - List all projects
- `create_workspace` - Create a workspace in a project
- `create_goal` - Create a goal in a workspace
- `create_task` - Create a task in a goal
- `update_task_status` - Update task status
- `create_session` - Create a new work session
- `get_active_sessions` - Get active sessions
- `link_document` - Attach documents to entities
- `get_kanban_board` - Get kanban board view
- `get_project_hierarchy` - Get full project structure
- `get_project_stats` - Get project statistics
- `search_tasks` - Search across all tasks

## 🔄 Development

```bash
# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Clean and rebuild
./stop.sh
npm run build
./orchestry
```

## 🤝 Multi-Session Workflow

1. **Create a Project**: Initialize a project that multiple sessions can work on
2. **Start Sessions**: Each LLM or human user creates their own session
3. **Collaborate**: All sessions can create and modify tasks in real-time
4. **Track Context**: Each session's contributions are tracked separately
5. **Synchronize**: Changes are instantly reflected across all active sessions

## 📝 Example LLM Integration

```javascript
// Using Orchestry with Claude/GPT via MCP
{
  "mcpServers": {
    "orchestry": {
      "command": "node",
      "args": ["./server/dist/index.js"],
      "env": {
        "RUN_MODE": "stdio"
      }
    }
  }
}
```

## 🎨 Tech Stack

- **Backend**: Node.js, Express, TypeScript, SQLite
- **Frontend**: React 18, Vite, TailwindCSS, Zustand
- **Real-time**: Socket.io
- **MCP**: @modelcontextprotocol/sdk
- **UI**: @dnd-kit for drag-and-drop

## 📄 License

MIT

## 🙏 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 🐛 Troubleshooting

### Port Already in Use
```bash
./stop.sh  # Kill any running instances
./orchestry
```

### Database Issues
```bash
rm server/orchestry.db*  # Reset database
./orchestry
```

### Build Errors
```bash
cd server && npm run build
cd ../web && npm run build
```

## 📞 Support

For issues and questions, please open an issue on GitHub.