claudeus-plane-mcp

⚠️ PRIVATE REPOSITORY NOTICE ⚠️

This is a private repository for SimHop IT & Media AB team members only. While the code is available for viewing and use under the MIT license, we do not accept public contributions at this time. You are welcome to fork the repository and create your own version, as long as it's not identical or extremely similar to our package to avoid user confusion.

🤘 Claudeus Plane MCP 🎸

"Unleash the Power of AI in Your Plane Realm - Setting the Standard for MCP Excellence!" 🖤

🎯 Our Mission: Elevating Project Management with AI

In the rapidly evolving landscape of AI-powered project management, we're introducing Claudeus Plane MCP - a powerful bridge between Claude's AI capabilities and Plane's project management platform. Our mission is to:

• ✅ Provide seamless AI integration with Plane
• ✅ Enable automated project management workflows
• ✅ Enhance team collaboration through AI assistance
• ✅ Streamline task and resource management
• ✅ Set new standards for MCP development

Why Claudeus Plane MCP?

Built on the foundation of our successful Claudeus WordPress MCP, this server brings the same level of:

• 🎸 Technical Excellence: Complete TypeScript coverage with strict type checking
• 🎸 Quality Assurance: Comprehensive test suite (95%+ coverage)
• 🎸 Protocol Compliance: Full MCP 2024-11-05 specification implementation
• 🎸 Security: Enterprise-grade security practices
• 🎸 Reliability: Robust error handling and recovery
• 🎸 Documentation: Detailed guides and examples

🤘 Why We Chose Plane: The Technical Symphony

In the vast landscape of project management solutions, our choice of Plane wasn't just a decision - it was a technical revelation. Here's why Plane stands out as the perfect foundation for our AI-powered project management revolution:

🎸 Technical Excellence & Architecture

1. Open Source Power

   • Full source code transparency
   • AGPL v3.0 license ensuring freedom
   • Active community contributions
   • Self-hosting capabilities with Docker/Kubernetes

2. Modern Tech Stack

   • Built with cutting-edge technologies
   • Clean, modular architecture
   • Extensible plugin system
   • API-first design philosophy

3. Performance & Scalability

   • Lightning-fast response times
   • Efficient database operations
   • Smart caching mechanisms
   • Horizontal scaling support

🎯 Feature Flexibility

Unlike traditional solutions that force you into their workflow:

⚡ Development Velocity

Plane's architecture enables:

• Rapid Iteration: Quick feature development and deployment
• Easy Extension: Simple plugin development
• API Excellence: Complete REST API coverage
• Real-time Updates: WebSocket support for live changes

🔒 Security & Control

1. Data Sovereignty

   • Complete control over data location
   • No vendor lock-in
   • Custom security policies
   • Compliance flexibility

2. Authentication & Authorization

   • Granular permission system
   • Multiple auth methods
   • Role-based access control
   • API key management

💰 Cost-Effectiveness

🚀 Future-Ready Architecture

Plane's design aligns perfectly with modern development needs:

1. AI Integration Ready

   • Clean API design perfect for AI integration
   • Structured data model ideal for ML
   • Extensible architecture for AI features
   • Real-time capabilities for AI assistance

2. Modern Development

   • TypeScript/Python backend
   • React-based frontend
   • Docker containerization
   • Kubernetes orchestration

3. Community Power

   • Active development community
   • Regular updates and improvements
   • Open to contributions
   • Transparent roadmap

🎸 The Metal Factor

Just like heavy metal breaks free from conventional musical boundaries, Plane breaks free from traditional project management constraints:

• Freedom: Like writing your own riffs instead of playing covers
• Power: Full control over your project management destiny
• Innovation: Ability to create new workflows and features
• Community: Strong open-source spirit, just like the metal community

🤘 "In a world of corporate project management, Plane is like that underground metal band that changes the game - raw, powerful, and completely authentic!" - Amadeus

🔮 Partnership Potential

Plane's philosophy aligns perfectly with our vision:

1. Open Source Excellence

   • Both companies value transparency
   • Shared commitment to quality
   • Community-driven development

2. Innovation Focus

   • AI-first thinking
   • Modern architecture
   • Continuous evolution

3. Technical Synergy

   • API-driven development
   • Modern tech stack
   • Performance focus

This is why Plane isn't just our choice - it's our technical soulmate in the project management realm. Together with our AI integration through Claudeus Plane MCP, we're creating a symphony of efficiency that rocks the project management world! 🤘

🚀 Core Features

🎯 Project Management

• Create and manage projects with AI assistance
• Automated project setup and configuration
• Smart project templates and workflows

📋 Task Management

• AI-powered task creation and assignment
• Automated task prioritization
• Smart task dependencies management

👥 Team Collaboration

• Intelligent resource allocation
• Automated team notifications
• Smart workload balancing

💬 Communication

• AI-enhanced comment management
• Smart notification systems
• Automated status updates

📖 Quick Start Guide

Prerequisites

# Required Software
Node.js ≥ 22.0.0
TypeScript ≥ 5.0.0
PNPM
Plane instance with API access

Installation

# Clone the repository
git clone https://github.com/deus-h/claudeus-plane-mcp

# Install dependencies
pnpm install

# Build the project
pnpm build

# Configure Claude Desktop
cp claude_desktop_config.json.example claude_desktop_config.json
# Edit claude_desktop_config.json with your settings

Configuration

# Copy example configs
cp .env.example .env
cp plane-instances.json.example plane-instances.json

# Edit .env and plane-instances.json with your settings

Configuring plane-instances.json

The plane-instances.json file is used to configure your Plane instances for integration. Below is an example structure:

{
  "instance-alias": {
    "baseUrl": "https://your-plane-instance.com/api/v1",
    "defaultWorkspace": "your-workspace-slug",
    "otherWorkspaces": ["workspace2", "workspace3"],
    "apiKey": "your-plane-api-key"
  }
}

Configuration Fields

• baseUrl: The base URL of your Plane API (required)
• defaultWorkspace: The default workspace slug (required)
• otherWorkspaces: Array of additional workspace slugs (optional)
• apiKey: Your Plane API key (required)

🛠️ Development

Project Structure

src/
├── api/              # Plane API integration
│   ├── client/       # API client implementation
│   ├── endpoints/    # Endpoint definitions
│   └── types/        # API type definitions
│
├── mcp/              # MCP protocol implementation
│   ├── server.ts     # Core MCP server
│   ├── transport/    # Transport handlers
│   ├── tools.ts      # Tool definitions
│   └── types/        # MCP type definitions
│
├── tools/            # Tool implementations
│   ├── projects/     # Project management
│   ├── tasks/        # Task operations
│   ├── users/        # User management
│   └── comments/     # Comment handling
│
└── prompts/          # AI prompt templates
    ├── projects/     # Project-related prompts
    ├── tasks/        # Task-related prompts
    └── analysis/     # Analysis prompts

Available Scripts

# Development
pnpm dev         # Start development server
pnpm watch       # Watch for changes
pnpm inspector   # Launch MCP Inspector

# Testing
pnpm test              # Run tests
pnpm test:watch        # Watch tests
pnpm test:coverage     # Generate coverage

# Building
pnpm build       # Build for production
pnpm clean       # Clean build files

🔒 Security

Authentication

• API Key-based authentication
• Secure token management
• Request validation

Data Protection

• Encrypted communication
• Secure configuration storage
• Input sanitization

🤝 Contributing

This is a private repository maintained by the SimHop IT & Media AB development team. While we don't accept public contributions, team members can contribute following our development standards:

1. Create feature branches (feature/AmazingFeature)
2. Maintain test coverage above 95%
3. Follow our TypeScript and documentation standards
4. Submit PRs for review

📄 License

MIT License - Copyright (c) 2024 SimHop IT & Media AB

🎸 The Team Behind the Magic

SimHop IT & Media AB - Where Innovation Meets Metal 🤘

Based in Sweden, SimHop IT & Media AB brings together technical excellence and creative innovation. Our team includes:

Amadeus Samiel H. (CTO/Lead Solutions Architect)

• MSc in Computer Science
• 20+ years of technical excellence
• The virtuoso behind Claudeus MCP servers

Simon Malki (CEO)

• 20+ years of business leadership
• Strategic planning expert
• The visionary driving SimHop's success

Made with 🤘❤️ by

🛠 MCP Tools Reference

Tool Categories and Danger Levels

Danger Level Legend

• 🟢 Safe: Read-only operations, no data modification
• 🟡 Moderate: Creates or modifies content, but can be reverted
• 🔴 High: Destructive operations or system-wide changes

🎯 Technical Deep Dive

Architecture Overview 🏗️

Each component in our technical architecture is designed for maximum efficiency and reliability:

Core Components 🤘

Technical Implementation 🎸

Security Measures 🛡️

Performance Tuning 🚀

Error Categories & Handling 🎸

Design Principles Power Chord 🤘

🎸 Pro Tip: Like a well-tuned guitar, each component is precisely calibrated for maximum shredding capability! ❤️

⚡ Performance Metrics

Time Savings

Cost Efficiency

🎸 Claude Desktop Integration

Configuration Location

The Claude Desktop configuration file can be found at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

⚠️ IMPORTANT: If you already have other MCP servers configured in Claude Desktop, DO NOT directly copy our example file as it will overwrite your existing configuration! Instead:

1. For existing Claude Desktop users:

   • Open your existing config through Claude Desktop:
     • Click on the Claude menu
     • Select "Settings..."
     • Click on "Developer" in the lefthand bar
     • Click on "Edit Config"
   • OR open your config file directly in a text editor
   • Add our Claudeus Plane MCP server configuration to your existing mcpServers object

2. For new Claude Desktop users: You can copy our example config file:

   # For macOS
   cp claude_desktop_config.json.example ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # For Windows (in PowerShell)
   Copy-Item claude_desktop_config.json.example $env:APPDATA\Claude\claude_desktop_config.json
   

Configuration Examples

NPX Setup

{
  "mcpServers": {
    "claudeus-plane-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claudeus-plane-mcp"
      ],
      "env": {
        "PLANE_INSTANCES_PATH": "/absolute/path/to/your/plane-instances.json"
      }
    }
  }
}

Docker Setup 🐳

{
  "mcpServers": {
    "claudeus-plane-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network=host",
        "--mount", "type=bind,src=/absolute/path/to/your/plane-instances.json,dst=/app/plane-instances.json",
        "--mount", "type=bind,src=/absolute/path/to/your/.env,dst=/app/.env",
        "mcp/plane",
        "--config", "/app/plane-instances.json"
      ]
    }
  }
}

🎸 Pro Tip: Make sure to replace /absolute/path/to/your/plane-instances.json with the actual path to your configuration file!

After Configuration

1. Restart Claude Desktop completely
2. Look for the hammer 🔨 icon in the bottom right corner of the input box
3. Click it to see available Plane management tools
4. Start shredding! 🤘

Troubleshooting

If the server isn't showing up in Claude:

1. Verify your claude_desktop_config.json syntax
2. Ensure file paths are absolute and valid
3. Check Claude's logs at:
   • macOS: ~/Library/Logs/Claude
   • Windows: %APPDATA%\Claude\logs

⚠️ Issues and Considerations

Current Limitations and Workarounds

1. Claude Desktop Response Limits

• Issue: Claude Desktop's maximum response length can be reached during complex operations
• Impact: Operations may be interrupted, requiring user intervention
• Workaround:
  • Configure Claude Desktop to break tasks into smaller batches
  • In Claude Desktop Settings > Advanced:
    • Set "Maximum Response Length" to a lower value
    • Enable "Auto-split Responses"
  • Use the Inspector UI for large-scale operations

2. Rate Limiting Considerations

• Issue: Plane API has rate limits
• Impact: Bulk operations might be throttled
• Mitigation:
  • Use batch processing features
  • Implement appropriate delays between requests
  • Monitor API response headers for rate limit info

3. Memory Management

• Issue: Large operations can consume significant memory
• Impact: Potential performance degradation
• Best Practices:
  • Monitor system resources during large operations
  • Use pagination for large datasets
  • Implement cleanup routines

Future Improvements

We're actively working on:

1. Improved response handling in Claude Desktop
2. Advanced rate limiting management
3. Memory optimization techniques
4. Enhanced error recovery mechanisms

🎸 Pro Tip: Check our GitHub Discussions for workarounds and best practices!

🎸 Support and Community ❤️

• GitHub Discussions: Share ideas, report issues, and join the conversation
• Documentation: Full technical docs
• Examples: Sample implementations

🎸 Pro Tip: Use GitHub Discussions to share your experience, report issues, or suggest improvements!

---

The Project Manager's Anthem

by Amadeus & Claude

---

In Plane's vast space,
Tasks flow with grace,
AI's embrace,
Sets perfect pace.

Through Claude's might,
Projects take flight,
In code's delight,
All syncs just right.

A manager's dream,
Where AI and team,
Work upstream,
Like metal's gleam.

---

Made with 🤘❤️ by