内容
# JobNimbus MCP 客户端
**将 Claude Desktop 连接到远程 JobNimbus MCP 服务器，支持任意电脑访问**
本软件包提供了一个 MCP（模型上下文协议）客户端，用于将 Claude Desktop 连接到远程 JobNimbus MCP 服务器。无需本地安装或仓库克隆！
## ✨ 功能特点
- 🔒 **零存储安全**: API 密钥绝不会存储在服务器上
- 🌐 **多客户端支持**: 支持多个客户端同时连接
- ⚡ **无状态**: 每个请求都是独立的
- 🚦 **速率限制**: 自动保护每个客户端
- 🛠️ **可扩展**: 新增工具仅需约 10 分钟
- 🔄 **自动 CI/CD**: 通过 `git push` 部署
- 📊 **监控**: 健康检查和清理日志
## 🎯 架构设计
```
Claude Desktop (API 密钥) → Render.com 服务器 → JobNimbus API
↓ ↓
本地配置 临时验证
(不会离开) (不会存储)
```
**关键原则**: 服务器是一个无状态代理。API 密钥从客户端的每个请求中获取，并在使用后立即从内存中清除。
## 📦 快速安装
### 1. 克隆和安装
```bash
cd jobnimbus-mcp-remote
npm install
```
### 2. 配置本地环境
```bash
cp .env.example .env
```
### 3. 本地运行
```bash
npm run dev
```
访问: http://localhost:3000/health
### 4. 部署到 Render.com
参见: [docs/SETUP.md](docs/SETUP.md) 了解完整的部署指南。
## 🔧 可用工具（88 个 - 已优化）
### 核心 CRUD（27 个工具）
- **验证**: `validate_api_key` - 验证 API 密钥
- **任务（7）**: `get_jobs`, `search_jobs`, `search_jobs_enhanced`, `get_job`, `search_job_notes`, `get_job_tasks`
- **状态搜索（13）**: `search_jobs_by_status`, `get_leads`, `get_pending_approval`, `get_lost_jobs`, `get_in_progress`, `get_completed`, `get_paid_closed`, `get_estimating`, `get_signed_contracts`, `get_scheduled`, `get_appointments`, `get_invoiced`, `get_deposits`
- **联系人（3）**: `get_contacts`, `search_contacts`, `create_contact`
- **其他（3）**: `get_estimates`, `get_activities`, `create_activity`, `get_calendar_activities`, `get_timeline_data`
### 分析（35 个工具）
- **保险和零售（3）**: `analyze_insurance_pipeline`, `analyze_retail_pipeline`, `analyze_services_repair_pipeline`
- **财务（6）**: `get_sales_rep_performance`, `get_performance_metrics`, `get_automated_followup`, `get_revenue_report`, `get_margin_analysis`, `analyze_revenue_leakage`, `get_profitability_dashboard`
- **性能（2）**: `get_seasonal_trends`, `get_pipeline_forecasting`
- **区域（5）**: `get_job_summary`, `get_optimal_door_routes`, `get_territory_heat_maps`, `get_jobs_distribution`, `get_door_knocking_scripts_by_area`, `get_seasonal_door_timing`, `get_estimates_with_addresses`
- **生产力（9）**: `get_activities_analytics`, `get_task_management_analytics`, `get_user_productivity_analytics`, `get_lead_scoring_analytics`, `get_communication_analytics`, `get_conversion_funnel_analytics`, `get_resource_allocation_analytics`, `get_customer_satisfaction_analytics`, `get_time_tracking_analytics`
- **商业（8）**: `get_project_management_analytics`, `get_marketing_campaign_analytics`, `get_financial_forecasting_analytics`, `get_customer_segmentation_analytics`, `get_operational_efficiency_analytics`, `get_sales_velocity_analytics`, `get_competitive_analysis_analytics`
### 材料（11 个工具）
- **跟踪**: `get_estimate_materials`, `analyze_material_costs`, `get_material_usage_report`, `get_material_inventory_insights`
- **计算**: `calculate_roofing_materials`, `calculate_siding_materials`, `estimate_materials_from_job`, `calculate_waste_factors`, `optimize_material_orders`, `get_material_specifications`, `compare_material_alternatives`
### 附件和商业智能（6 个工具）
- **附件（4）**: `get_attachments`, `get_file_by_id`, `analyze_job_attachments`, `get_job_attachments_distribution`
- **商业（1）**: `search_insurance_jobs`
- **发票（1）**: `get_invoices`
### 系统（2 个工具）
- `get_tasks`, `get_users`
### 📦 已归档/实验性工具
14 个过时或功能不正常的工具已被移除以优化性能：
- 参见 `/src/tools/archived/` - 11 个工具，无操作价值
- 参见 `/src/tools/experimental/` - 7 个工具，端点未验证
**好处**: 约 40% 的令牌使用量减少，工具发现速度更快。
**添加更多**: 参见 [docs/ADDING_TOOLS.md](docs/ADDING_TOOLS.md)
## 💻 MCP 配置
### 选项 1: Claude 代码（推荐）
1. **配置环境变量**:
```bash
cp .env.mcp.example .env.mcp
# 编辑 .env.mcp 文件，填写您的 API 密钥
```
2. **加载变量** （PowerShell）:
```powershell
Get-Content .env.mcp | ForEach-Object {
if ($_ -match '^([^=]+)=(.+)$') {
[Environment]::SetEnvironmentVariable($matches[1], $matches[2], 'Process')
}
}
```
3. **验证**:
```
/mcp
```
参见完整指南: [MCP_SETUP.md](MCP_SETUP.md)
### 选项 2: Claude Desktop
位置: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"jobnimbus-stamford": {
"command": "node",
"args": ["C:/path/to/examples/mcp-client.js"],
"env": {
"MCP_SERVER_URL": "https://your-server.onrender.com",
"JOBNIMBUS_API_KEY": "your_api_key_stamford",
"JOBNIMBUS_INSTANCE": "stamford"
}
}
}
}
```
参见完整示例: [examples/claude-desktop-config.json](examples/claude-desktop-config.json)
## 📚 文档
- [📖 安装指南](docs/SETUP.md) - 安装和部署
- [🔌 MCP 设置](MCP_SETUP.md) - Claude Code 的 MCP 配置
- [🏗️ 架构设计](docs/ARCHITECTURE.md) - 完整的技术设计
- [🛠️ 添加工具](docs/ADDING_TOOLS.md) - 如何创建新工具
## 🔐 安全
### ✅ 服务器执行的操作:
- 从 `X-JobNimbus-Api-Key` 头部提取 API 密钥
- 验证 API 密钥格式
- 使用 API 密钥调用 JobNimbus
- 立即清除 API 密钥
### ❌ 服务器不执行的操作:
- 将 API 密钥存储在数据库中
- 将 API 密钥保存到文件中
- 记录 API 密钥
- 缓存 API 密钥
- 在客户端之间共享 API 密钥
### 安全验证
```bash
# 检查硬编码的 API 密钥（应返回空）
grep -r "api[_-]key.*=" src/
# 依赖项审计
npm audit
# CI 中的安全测试
npm run lint
```
## 🚀 部署
### 自动部署（推荐）
```bash
git add .
git commit -m "feat: new feature"
git push origin main
```
GitHub Actions 自动部署到 Render.com。
### 手动部署
```bash
npm run build
npm run start:prod
```
## 🧪 测试
### 健康检查
```bash
curl https://your-server.onrender.com/health
```
### 列出工具
```bash
curl -X POST https://your-server.onrender.com/mcp/tools/list \
-H "X-JobNimbus-Api-Key: your_api_key" \
-H "Content-Type: application/json"
```
### 执行工具
```bash
curl -X POST https://your-server.onrender.com/mcp/tools/call \
-H "X-JobNimbus-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"name":"get_jobs","arguments":{"size":10}}'
```
## 📊 监控
### 健康检查端点
- `GET /health` - 服务器状态
### 速率限制头部
```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1234567890
```
### 日志
所有日志都经过清理 - 不包含 API 密钥或敏感信息。
## 🛠️ 开发
### 项目结构
```
jobnimbus-mcp-remote/
├── src/
│ ├── server/ # Express 服务器
│ ├── middleware/ # 身份验证，速率限制
│ ├── tools/ # MCP 工具
│ ├── services/ # JobNimbus 客户端
│ ├── config/ # 配置
│ ├── types/ # TypeScript 类型
│ └── utils/ # 日志记录，错误处理
├── .github/workflows/ # CI/CD
├── docs/ # 文档
├── scripts/ # 实用脚本
└── examples/ # 使用示例
```
### 可用命令
```bash
npm run dev # 开发环境，热重载
npm run build # 编译 TypeScript
npm run start # 运行生产环境
npm run lint # 校验
npm run type-check # 类型检查
npm test # 测试
```
## 🤝 贡献
1. 分叉项目
2. 创建分支: `git checkout -b feature/new-feature`
3. 提交: `git commit -m 'feat: add new feature'`
4. 推送: `git push origin feature/new-feature`
5. 打开拉取请求
## 📄 许可证
MIT
## 🆘 支持
- **文档**: 参见 `docs/` 文件夹
- **问题**: GitHub 问题
- **日志**: Render.com 控制台
## ✅ 项目状态
- [x] 基础结构
- [x] 带有 MCP 的 Express 服务器
- [x] 安全中间件
- [x] JobNimbus API 客户端
- [x] 可扩展的工具系统
- [x] **88 个整合工具** ✅ (14 个归档/实验性)
- [x] GitHub Actions CI/CD
- [x] Render.com 配置
- [x] 完整的文档
- [x] Claude Desktop 客户端
- [x] 可扩展性工厂模式
- [x] Redis 缓存集成以优化性能
- [x] 工具整合（2025 年 1 月）
- [ ] 单元测试（下一步）
- [ ] 高级指标和监控（可选）
**使用 ❤️ 为 Claude Desktop 安全远程访问 JobNimbus 而创建**
