clickmongrel (Hellocory)

ClickMongrel-点击克劳德MCP服务器

  

一个模型上下文协议（MCP）服务器，将Claude的TodoWrite与ClickUp无缝集成，提供自动任务同步、提交跟踪、时间管理和全面的项目跟踪。

📚 查看完整文档

🚀 特性

核心功能

• 🔄 自动TodoWrite同步 -在Claude中创建的任务会自动同步到ClickUp
• 👨‍👩‍👧‍👦 亲子任务关系 -具有自动父级状态管理的子任务
• ⏱️ 时间跟踪 -任务完成时自动跟踪时间
• 📝 提交链接 -将已完成的任务链接到其提交
• 📎 附件支持 -将屏幕截图、演示和文件上传到任务
• 👤 自动分配 -自动分配给已配置用户的任务
• 📊 状态生命周期 -通过自定义ClickUp状态跟踪任务
• 🎯 目标管理 -跟踪项目目标和进度
• 📈 报告生成 -每日和每周开发报告

增强功能（新增）

• 智能时间追踪 -自动跟踪从任务开始到完成的时间
• 任务提交关系 -将任务链接到完成任务的提交
• 附件上传 -添加屏幕截图和演示以展示功能
• 父任务自动完成 -当所有子任务完成时，父任务自动完成

📋 先决条件

1. 点击账户 具有API访问权限
2. 克劳德代码 支持MCP
3. Node.js 18+和pnpm
4. 点击API键 -从ClickUp设置获取→ Apps → API代币

🛠️ 安装

选项1：来自GitHub（推荐）

# Clone the repository
git clone https://github.com/yourusername/clickmongrel.git
cd clickmongrel

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Test connection
CLICKUP_API_KEY="your_api_key" node dist/cli.js test

选项2:NPM全局安装（即将推出）

npm install -g @clickmongrel/mcp-server

⚙️ 设置

快速设置（AI友好）

当使用Claude和ClickMongrel时，只需说：

• “安装程序单击\[您的工作区名称\]”
• “在\[工作区\]的\[空间名称\]中设置clickmongrel”

手动设置

# Basic setup - uses default "Agentic Development" space
node dist/quick-setup.js --workspace "Your Workspace Name"

# Setup with specific space
node dist/quick-setup.js --workspace "Your Workspace" --space-name "Custom Space"

# Setup with space ID (faster)
node dist/quick-setup.js --workspace "Your Workspace" --space-id "90139256288"

🔌 MCP集成

添加到克劳德代码

# Add the MCP server (NEVER put API key in config files!)
claude mcp add clickmongrel \
  --env CLICKUP_API_KEY="your_api_key_here" \
  -- node /absolute/path/to/clickmongrel/dist/index.js

# Verify it's connected
claude mcp list

# In Claude Code, check status
/mcp

可用的MCP工具

📁 项目结构

your-project/
└── .claude/
    └── clickup/
        ├── config.json           # Workspace & list IDs (NO API KEYS!)
        ├── STATUS_SETUP_GUIDE.md # Instructions for ClickUp setup
        ├── templates/            # Commit message templates
        ├── reports/              # Generated reports
        └── cache/                # Temporary cache

⚠️ 关键：点击状态配置

在ClickUp中配置自定义状态之前，系统将无法工作！

所需任务状态

1. 转到ClickUp→ 您的共享空间→ 任务列表
2. 点击⋮菜单→ “编辑状态”
3. 选择“自定义状态”
4. 添加以下精确状态：

- to do - future - in progress - fixing - completed

所需提交状态

1. 转到ClickUp→ 您的共享空间→ 承诺清单
2. 点击⋮菜单→ “编辑状态”
3. 添加以下精确状态：

- comitted - developing - prototyping - rejected - production/testing - production/final

🎯 使用示例

基本任务管理

// Claude TodoWrite automatically syncs
TodoWrite([
  { id: "task-1", content: "Setup database", status: "pending" },
  { id: "task-2", content: "Create API", status: "in_progress" }
])

父子任务

// Create tasks with subtasks
TodoWrite([
  { id: "feature", content: "User Authentication", status: "pending" },
  { id: "sub-1", content: "Login form", status: "pending", parent_id: "feature" },
  { id: "sub-2", content: "JWT tokens", status: "pending", parent_id: "feature" }
])
// Parent auto-updates to "in_progress" when subtask starts
// Parent auto-completes when all subtasks complete

增强功能

// Time tracking (automatic)
// When task goes from in_progress → completed, time is tracked

// Add attachments
mcp.add_attachment({
  task_id: "task-1",
  file_path: "/path/to/screenshot.png",
  file_name: "Dashboard Screenshot"
})

// Tasks automatically link to commits that complete them

🔧 配置

环境变量

CLICKUP_API_KEY=pk_xxx          # Your ClickUp API key (REQUIRED)
CLICKUP_WORKSPACE_ID=xxx         # Optional: Default workspace
CLICKUP_SPACE_ID=xxx            # Optional: Default space
LOG_LEVEL=info                  # Logging level (debug|info|warn|error)

安全最佳实践

⚠️ 切勿将API密钥存储在：

• 配置文件(.json, .env)
• Git仓库
• 项目目录

✅ 始终通过以下方式传递API密钥：

• --env 添加MCP时标记
• 运行时的环境变量
• Claude Code的安全存储

📊 详细功能

时间跟踪

• 任务状态时自动启动→ in_progress
• 停止并记录状态时间→ completed
• 用实际花费的时间更新ClickUp

提交链接

• 每次提交都会在提交列表中创建一个任务
• 已完成的任务链接到其最终提交
• 完整的开发可追溯性

附件支持

• 上传屏幕截图、文档或任何文件
• Claude可以提示：“您想添加屏幕截图吗？”
• 直接附加到ClickUp任务的文件

父任务管理

• 父任务根据子任务自动更新
• 状态流： pending → in_progress → completed
• 所有子任务完成后自动完成

🐛 故障排除

“状态验证失败”

• 在ClickUp中配置自定义状态（请参阅上面的状态配置）
• 跑 clickmongrel check-statuses 验证

“没有可用的列表ID”

• 再次运行安装程序： node dist/quick-setup.js --workspace "Your Workspace"

“API密钥无效”

• 检查API密钥是否正确
• 确保它通过 --env 标志，不在配置文件中

任务未同步

1. 检查状态是否已配置
2. 验证是否设置了API密钥
3. 确保工作空间/空间正确
4. 检查日志： LOG_LEVEL=debug node dist/index.js

🤝 贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🔗 链接

• MCP文件
• 点击API文档

💡 Claude用户提示

1. 让Claude处理设置：告诉克劳德你的工作区名称
2. 使用自然语言：“为此功能创建目标”
3. TodoWrite集成：自动-只需正常使用TodoWrite
4. 请求附件：Claude可以提示截图
5. 检查进度：“显示同步状态”或“验证状态”

🚨 重要提示

• 这是一个PUBLIC项目-永远不要在代码中引用特定的工作区
• API密钥不得存储在项目文件中
• 始终对敏感数据使用环境变量
• 首次使用前配置ClickUp状态

______________________________________________________________________

专为使用Claude Code和ClickUp集成需求的开发人员而构建