luci-efe/huly-mcp-tracker

Huly MCP Tracker

MCP Server for Huly Cloud Tracker integration with Claude Desktop. This server enables Claude Desktop to interact directly with your Huly Cloud workspace to manage issues in the Tracker system.

🎯 Features

• Create Issues: Create new issues with title, description, priority, and assignment
• List Projects: Get all projects in your Huly workspace
• Search Issues: Find issues by text, project, assignee, status, or priority
• List People: Get workspace members for issue assignment
• Get Issue Details: Retrieve complete information about specific issues

📋 Prerequisites

• Node.js 18+ installed
• Huly Cloud account with workspace access
• Claude Desktop application

🚀 Installation

1. Clone or download this project

   git clone <repository-url>
   cd huly-mcp-tracker
   

2. Install dependencies

   npm install
   

3. Configure environment variables

   cp .env.example .env
   

   Edit .env with your Huly credentials:

   HULY_EMAIL=your-email@company.com
   HULY_PASSWORD=your-secure-password
   HULY_WORKSPACE=tendencia-6861a6a5-bdb12ebb9a-153978
   

4. Build the project

   npm run build
   

⚙️ Claude Desktop Configuration

Add the following configuration to your Claude Desktop config file:

Location:

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

Configuration:

{
  "mcpServers": {
    "huly-tracker": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/absolute/path/to/huly-mcp-tracker",
      "env": {
        "HULY_EMAIL": "your-email@company.com",
        "HULY_PASSWORD": "your-secure-password",
        "HULY_WORKSPACE": "tendencia-6861a6a5-bdb12ebb9a-153978"
      }
    }
  }
}

Important: Replace /absolute/path/to/huly-mcp-tracker with the actual absolute path to your project directory.

🔧 Usage Examples

After configuring Claude Desktop, restart the application and you can use natural language commands:

Create Issues

• "Create a high priority issue called 'Fix login bug' in the Frontend project"
• "Create an issue 'Update API documentation' assigned to Juan Pérez"

List Projects

• "List all projects in our Huly workspace"
• "Show me all projects including archived ones"

Search Issues

• "Find all issues containing 'API' in the title"
• "Search for issues in the Frontend project with high priority"
• "Show me all issues assigned to María García"

List People

• "Who is available for task assignment in our workspace?"
• "List all team members"

Get Issue Details

• "Show me details for issue issue-1"
• "Get complete information about the login bug issue"

🛠️ Available Tools

*Required parameters

🔄 Development

# Development mode with auto-restart
npm run watch

# Build TypeScript
npm run build

# Run production server
npm start

# Clean build files
npm run clean

# Test build
npm test

⚠️ Important Notes

Implementation Modes

This project supports two modes:

🧪 Mock Mode (Default)

• Uses sample data for development and testing
• No external dependencies required
• Perfect for Claude Desktop integration testing

🚀 Real Huly Mode

• Connects to actual Huly Cloud workspace
• Requires GitHub Packages authentication
• Full integration with your Huly data

Setting up Real Huly Integration

Step 1: GitHub Personal Access Token

1. Go to https://github.com/settings/tokens
2. Generate new token (classic) with permissions:
   • read:packages - Download packages from GitHub Packages
   • repo - Repository access (if needed)
3. Copy the token immediately

Step 2: Configure npm authentication

# Set your GitHub token
export GITHUB_TOKEN=your_github_token_here

# Or add to your shell profile permanently
echo 'export GITHUB_TOKEN=your_github_token_here' >> ~/.bashrc

Step 3: Install Huly dependencies

# Run the installation script
./install-huly-deps.sh

Step 4: Switch to real client

# Switch to real Huly client
./switch-to-real-client.sh

# Rebuild the project
npm run build

Step 5: Configure real connection

Update your Claude Desktop config with real Huly credentials:

{
  "mcpServers": {
    "huly-tracker": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/absolute/path/to/huly-mcp-tracker", 
      "env": {
        "HULY_EMAIL": "your-real-email@company.com",
        "HULY_PASSWORD": "your-real-password",
        "HULY_WORKSPACE": "your-real-workspace-id"
      }
    }
  }
}

Switching Between Modes

# Switch to real Huly client
./switch-to-real-client.sh

# Switch back to mock client for development
./switch-to-mock-client.sh

Security

• Never commit your .env file with real credentials
• Use environment variables in production
• Keep your Huly credentials secure

🐛 Troubleshooting

Claude Desktop Not Recognizing MCP Server

1. Check that the cwd path is absolute and correct
2. Verify that dist/index.js exists (run npm run build)
3. Restart Claude Desktop completely
4. Check Claude Desktop's developer console for errors

Environment Variable Issues

1. Ensure .env file exists and has correct values
2. Verify environment variables are set in Claude Desktop config
3. Check that HULY_WORKSPACE matches your actual workspace ID

Build Errors

1. Ensure Node.js 18+ is installed
2. Delete node_modules and run npm install again
3. Run npm run clean then npm run build

📚 Project Structure

huly-mcp-tracker/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── huly-client.ts        # Huly WebSocket client
│   ├── tools/                # MCP tool implementations
│   │   ├── create-issue.ts
│   │   ├── list-projects.ts
│   │   ├── search-issues.ts
│   │   ├── list-people.ts
│   │   └── get-issue.ts
│   ├── types/
│   │   └── huly-types.ts     # TypeScript interfaces
│   └── config/
│       └── env.ts            # Environment configuration
├── dist/                     # Compiled JavaScript
├── .env.example              # Environment template
└── README.md

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📞 Support

For issues and questions:

• Check the troubleshooting section above
• Review Claude Desktop MCP documentation
• Check Huly platform documentation

Note: This is a development version with mock data. For production use with real Huly data, additional setup with GitHub Packages authentication is required.