JobNimbus MCP Server

JobNimbus MCP 服务

本项目提供一个 Model Context Protocol（MCP） 服务，可通过 Cursor 和 Claude 等兼容的 AI 助手与 JobNimbus API 交互。

它允许 AI Agent 通过标准化工具访问和操作 JobNimbus 数据（联系人、工作、任务、产品、工作流、发票），并使用你的 JobNimbus API 密钥安全地进行访问。

此服务已发布到 npm，可通过 npx 轻松运行。

设置说明

请根据你使用的 AI 助手，按照以下说明进行设置。

为 Cursor 编辑器设置

1. 先决条件：

   • 已安装 Cursor 编辑器。
   • 已安装 Node.js 和 npm（npx 的运行要求）。
   • 你的 JobNimbus API 密钥。

2. 配置 Cursor：

   • 如果主目录中不存在 ~/.cursor 目录，请创建该目录。

   • 在此目录中创建名为 mcp.json 的文件（~/.cursor/mcp.json）。

   • 将以下配置复制到 ~/.cursor/mcp.json：

     {
       "mcpServers": {
         "jobnimbus-local-server": {
           "description": "JobNimbus MCP Server (requires API key)",
           "command": "npx",
           "args": ["jobnimbus-mcp-server"],
           "env": {
             "JOBNIMBUS_API_KEY": "your_api_key_here"
           }
         }
       }
     }
     

   • 重要： 将文件中的 "your_api_key_here" 替换为你的实际 JobNimbus API 密钥。

3. 重启 Cursor：

   • 完全退出并重新启动 Cursor 编辑器。

4. 验证：

   • Cursor 会在需要时自动使用 npx 运行服务。
   • 你应该能在 Cursor 的 MCP 设置中可用工具列表下，或在 Agent 推荐工具时，看到 jobnimbus-local-server。
   • 现在，你可以让 Cursor 使用 JobNimbus 工具执行操作（例如，“使用 jobnimbus_list_contacts 列出我的 JobNimbus 联系人”）。

为 Claude 桌面应用设置

1. 先决条件：

   • 已安装 Claude 桌面应用。
   • 已安装 Node.js 和 npm（npx 的运行要求）。
   • 你的 JobNimbus API 密钥。

2. 配置 Claude：

   • 找到 Claude 配置文件：

     • Mac：~/Library/Application Support/Claude/claude_desktop_config.json
     • Windows：%APPDATA%\Claude\claude_desktop_config.json

   • 如果文件不存在，请创建该文件。如果文件已存在，请谨慎合并 mcpServers 部分。

   • 添加以下配置：

     {
       "mcpServers": {
         "jobnimbus-local-server": {
           "description": "JobNimbus MCP Server (requires API key)",
           "command": "npx",
           "args": ["jobnimbus-mcp-server"],
           "env": {
             "JOBNIMBUS_API_KEY": "your_api_key_here"
           }
         }
       }
     }
     

   • 重要： 将文件中的 "your_api_key_here" 替换为你的实际 JobNimbus API 密钥。

3. 重启 Claude 应用：

   • 完全退出并重新启动 Claude 桌面应用。

4. 验证：

   • Claude 现在应该能够发现并使用此服务提供的 JobNimbus 工具。

工作原理（适用于两种助手）：

• 配置会指示助手使用 npx 运行 jobnimbus-mcp-server。
• 如果服务包尚未缓存，npx 会自动从 npm 下载最新版本。
• 助手会将 env 部分中的 API 密钥注入服务进程。

手动运行（高级 / 其他客户端）

如果你需要手动运行服务以进行调试，或与其他支持 stdio 的潜在 MCP 客户端搭配使用，请按以下步骤操作：

1. 设置 API 密钥环境变量：

   export JOBNIMBUS_API_KEY=your_actual_api_key_here
   

2. 运行服务：

   npx jobnimbus-mcp-server
   

   服务将通过 stdin/stdout 监听 MCP 通信。

已实现的工具

此服务实现了与 JobNimbus API 端点对应的 MCP 工具：

联系人

• jobnimbus_list_contacts：获取联系人列表，可选筛选条件
• jobnimbus_get_contact：按 ID 获取指定联系人
• jobnimbus_create_contact：创建联系人
• jobnimbus_update_contact：更新现有联系人

工作

• jobnimbus_list_jobs：获取工作列表，可选筛选条件
• jobnimbus_get_job：按 ID 获取指定工作
• jobnimbus_create_job：创建工作
• jobnimbus_update_job：更新现有工作

任务

• jobnimbus_list_tasks：获取任务列表，可选筛选条件
• jobnimbus_get_task：按 ID 获取指定任务
• jobnimbus_create_task：创建任务
• jobnimbus_update_task：更新现有任务

产品

• jobnimbus_list_products：获取产品列表，可选筛选条件
• jobnimbus_get_product：按 ID 获取指定产品
• jobnimbus_create_product：创建产品
• jobnimbus_update_product：更新现有产品

工作流

• jobnimbus_get_all_workflows：获取所有工作流及其状态
• jobnimbus_create_workflow：创建工作流
• jobnimbus_create_workflow_status：创建工作流状态

发票

• jobnimbus_list_invoices：获取发票列表，可选筛选条件
• jobnimbus_get_invoice：按 ID 获取指定发票
• jobnimbus_create_invoice：创建发票
• jobnimbus_update_invoice：更新现有发票
• jobnimbus_send_invoice：通过电子邮件发送发票
• jobnimbus_record_invoice_payment：记录发票付款

开发

如果你想为服务做贡献或修改服务：

1. 克隆仓库：git clone <repository_url>
2. 安装依赖项：cd jobnimbus-mcp-server && npm install
3. 在 src/ 目录中进行更改。
4. 构建：npm run build
5. 在本地测试（需要 .env 文件或已导出的 API 密钥）：
   • 直接运行：npm start
   • 自动重新加载运行：npm run dev
   • 链接以进行全局测试：npm link（完成后请记得运行 npm unlink -g jobnimbus-mcp-server）

许可证

MIT