huuthangntk-claude-vision-mcp-server

Claude Deep Think MCP 服务

一个强大的模型上下文协议（MCP）服务，使用 Anthropic 的 Claude Sonnet 4.5 提供主动式深度分析思考。此工具旨在新信息出现时、编写代码之前调用。

⚡ 核心理念：先思考，再编码

新信息出现时，请先使用此工具，再编写任何代码：

• 🐛 错误消息或堆栈跟踪
• 📝 用户需求或功能请求
• 💬 代码审查反馈
• 🚀 性能问题
• 🔒 安全警报
• 📚 待集成的 API 文档
• 🗄️ 数据库问题
• 💭 UX/UI 反馈
• 🔄 依赖项中的破坏性变更
• 🏗️ 架构决策

工作流：新信息 → 思考工具 → 审阅洞见 → 编写更好的代码

🌟 功能

深度思考与分析（claude_think）

在代码实现之前提供智能洞见、建议和战略指导。适用于：

• ✅ 在采取行动前深入了解上下文
• ✅ 提前识别潜在陷阱
• ✅ 从一开始就建议最佳实践
• ✅ 提供替代方案
• ✅ 提取关键信息，提高实现效率
• ✅ 战略决策
• ✅ 问题解决与架构规划

结果：更少的错误、更高的代码质量、更快的开发！

📋 前提条件

• Node.js 18+ 或 Bun
• Anthropic Claude API 密钥（在此获取）
• 兼容 MCP 的客户端（Cursor IDE、Claude Desktop 等）

🚀 快速开始

1. 安装

cd claude-vision-mcp
bun install
# or
npm install

2. 配置

连接到 MCP 服务时配置 API 密钥（参见下文的 Docker 或 Cursor 设置）。

3. 构建

bun run build
# or
npm run build

🐳 Docker 设置（推荐）

快速开始

cd claude-vision-mcp

# Create .env file with your API key
echo "ANTHROPIC_API_KEY=your-key-here" > .env
echo "CLAUDE_MODEL=claude-sonnet-4-20250514" >> .env

# Start container
docker-compose up -d

# Check status
docker ps | grep claude-vision

Docker Desktop 启动时，容器会自动重启。

Docker 配置

服务运行于 http://localhost:8080/mcp，并使用以下环境变量：

• ANTHROPIC_API_KEY - 你的 Claude API 密钥（必需）
• CLAUDE_MODEL - 要使用的模型（默认：claude-sonnet-4-20250514）

🔧 在 Cursor IDE 中使用

Docker 连接（推荐）

添加到你的 ~/.cursor/mcp.json 或 .cursor/mcp.json：

{
  "mcpServers": {
    "Claude Deep Think": {
      "url": "http://localhost:8080/mcp?apiKey=YOUR_API_KEY&model=claude-sonnet-4-5-20250929"
    }
  }
}

启用主动思考

将此仓库中的 .cursorrules 文件复制到项目根目录。这会让 Cursor AI 在编写代码前自动使用思考工具。

# From your project directory
cp claude-vision-mcp/.cursorrules .cursorrules

工具使用模式

新信息出现时，始终使用此模式：

Use the claude_think tool to analyze: [NEW INFORMATION]

Context: [Current situation, tech stack, constraints]

示例：

错误消息：

Use the claude_think tool to analyze:

Error: "TypeError: Cannot read property 'map' of undefined"

Context: React component rendering users from useState hook

新功能：

Use the claude_think tool:

Requirement: Add dark mode toggle to header

Context: Next.js 14, need to check if ThemeContext exists

性能问题：

Use the claude_think tool:

Issue: Homepage renders 50+ times, parent causing all children to re-render

Context: useState for theme in Header, passed via props to 20+ children

📚 示例

示例 1：分析技术决策

Use the claude_think tool to analyze:

"I'm building a real-time chat application. Should I use WebSockets, SSE, or HTTP polling?"

Context: Need to support 100K concurrent users, prioritize ease of implementation

预期输出：全面比较优缺点并给出建议

示例 2：架构规划

Use the claude_think tool to evaluate:

"What's the best way to structure a multi-tenant SaaS application?"

Context: PostgreSQL database, Node.js backend, 50-100 tenants expected

示例 3：最佳实践

Use the claude_think tool:

"Review this approach to handling user sessions in a Next.js app"

Context: Using JWT tokens, storing in localStorage, concerned about security

🛠️ 开发

项目结构

claude-vision-mcp/
├── src/
│   └── index.ts              # Main MCP server implementation
├── .smithery/
│   └── index.cjs            # Built server (generated)
├── package.json              # Dependencies and scripts
├── tsconfig.json            # TypeScript configuration
├── smithery.yaml            # Smithery deployment config
├── Dockerfile               # Docker container definition
├── docker-compose.yml       # Docker Compose configuration
└── README.md               # This file

可用脚本

• bun run build / npm run build - 编译 TypeScript
• bun run dev / npm run dev - 支持热重载的开发服务

🔒 安全最佳实践

1. 切勿提交 API 密钥 - 始终使用环境变量
2. 使用 .gitignore - 确保忽略 .env 文件
3. 定期轮换密钥 - 定期更新 API 密钥
4. 审查工具调用 - 在 Cursor 中保持启用手动批准
5. 使用开发环境 - 使用非生产数据进行测试

📦 Docker 管理

# Start container
docker-compose up -d

# View logs
docker logs claude-vision-mcp-server -f

# Restart container
docker-compose restart

# Stop container
docker-compose down

# Rebuild and restart
docker-compose up -d --build

🐛 故障排除

问题：Cursor 中无法连接服务

解决方案：

1. 确认 Docker 容器正在运行：docker ps | grep claude-vision
2. 检查容器日志：docker logs claude-vision-mcp-server
3. 完全重启 Cursor IDE
4. 确认 URL 中的 API 密钥正确

问题：API 密钥错误

解决方案：

1. 确保密钥以 sk-ant- 开头
2. 在此处测试密钥：https://console.anthropic.com/
3. 检查容器中的环境变量
4. 确认 URL 参数格式

问题：容器无法启动

解决方案：

# Check logs
docker logs claude-vision-mcp-server

# Verify .env file
cat .env

# Rebuild from scratch
docker-compose down -v
docker-compose up -d --build

💡 性能

使用 Bun 运行时：

• ⚡ 包安装速度提升 4 倍
• ⚡ 脚本执行速度提升 3～4 倍
• 📦 Docker 镜像更小
• 🚀 冷启动更快

📖 完整指南

• PROACTIVE_THINKING_WORKFLOW.md - 完整的工作流指南，包含前后对比示例
• THINK_TOOL_EXAMPLES.md - 10 个实际应用示例
• .cursorrules - Cursor IDE 自动执行“编码前先思考”模式的规则

💡 为什么要使用此工作流？

不使用 Think 工具时：

1. User reports error
2. AI writes quick fix
3. Fix creates new bug
4. Multiple iterations needed
⏱️ Total: 30 minutes, 3 iterations

使用 Claude_Think 工具时：

1. User reports error
2. AI analyzes with claude_think tool (20s)
3. AI writes comprehensive fix
4. Works correctly first time
⏱️ Total: 5 minutes, 1 iteration

结果：速度提升 6 倍，质量更高，Bug 更少！🎉

📄 许可证

MIT

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

📞 支持

如有问题或疑问：

• 在 GitHub 上提交 issue
• 查看 MCP 文档
• 阅读此代码库中的工作流指南

🙏 致谢

• 使用 Anthropic Claude API 构建
• 由 Model Context Protocol 提供支持
• 使用 Bun 容器化