Joe MCP

Joeapi MCP服务器

JoeAPI施工管理系统的模型上下文协议（MCP）服务器。向Claude和其他人工智能助手展示施工管理工具。

概述

此MCP服务器提供：

• 18个预构建工作流 用于常见的施工管理任务
• 60+个人工具 用于API直接访问（CRUD操作）
• 多运输支持：Smithery（云）和STDIO（本地）

建筑

mcp/
├── index.ts                           # Main MCP server (Smithery + STDIO)
├── local-server.ts                    # STDIO transport runner
├── claude-desktop-config.example.json # Claude Desktop config
├── README.md                          # This file
└── server.ts                          # Legacy (deprecated)

mcp-build/                             # Compiled JavaScript (production)
├── index.js                           # Compiled server
├── local-server.js                    # Compiled STDIO runner
└── *.d.ts                             # TypeScript definitions

部署选项

1.史密斯利（Cloud）- 现有的

您的MCP服务器已部署在Smithery上用于云访问。

访问权限： 通过Smithery市场 网址： https://smithery.ai/server/@your-username/joeapi 运输： 超文本传输协议 使用案例： 远程访问、团队协作

2.当地STDIO- 此设置

在您的计算机上本地运行MCP服务器进行开发/测试。

运输： STDIO（标准输入/输出） 使用案例： 本地开发，更快迭代，离线工作

______________________________________________________________________

本地STDIO设置

先决条件

1. JoeAPI在本地运行：

   npm run dev  # Start JoeAPI on http://localhost:8080

1. 构建MCP服务器：

   npm run mcp:build

1. 配置Claude桌面：

- 复制 mcp/claude-desktop-config.example.json - 更新 command 与您的安装相匹配的路径 - 添加到Claude桌面配置

选项A：开发模式（TypeScript）

为了使用自动重新编译进行快速开发：

npm run mcp:local

这运行 tsx mcp/local-server.ts -TypeScript直接执行（无需构建）。

选项B：生产模式（编译JavaScript）

用于生产用途：

# Build once
npm run mcp:build

# Run compiled version
npm run mcp:start

这运行 node mcp-build/local-server.js -更快的启动，生产就绪。

______________________________________________________________________

Claude桌面配置

步骤1：查找Claude配置目录

macOS：

~/Library/Application Support/Claude/

窗户：

%APPDATA%\Claude\

Linux：

~/.config/Claude/

第二步：编辑 claude_desktop_config.json

{
  "mcpServers": {
    "joeapi-local": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/joeapi/mcp-build/local-server.js"
      ],
      "env": {
        "JOEAPI_BASE_URL": "http://localhost:8080"
      },
      "disabled": false
    }
  }
}

重要提示：

• 使用 绝对路径 （不是相对的 ~/ 或 ./)
• 改变 /ABSOLUTE/PATH/TO/joeapi/ 走向你的实际道路
• 例子： /Users/joe/dev/joeapi/mcp-build/local-server.js

步骤3：重新启动克劳德桌面

关闭并重新打开Claude Desktop。MCP服务器将自动连接。

步骤4：验证连接

在Claude Desktop中，键入：

Can you use the find_workflow tool?

如果连接，Claude将可以访问所有JoeAPI工具。

______________________________________________________________________

可用工具

工作流发现（始终从这里开始！）

find_workflow -发现预构建的工作流程

• 集 autoExecute: false 查看全部18个工作流
• 集 autoExecute: true 使用工作流名称获取分步说明

18个预构建工作流

1. win_loss_rate -计算提案输赢统计
2. sales_pipeline -分析正在进行的提案
3. work_in_process_report -活动项目的WIP报告
4. job_costing_detail -详细的作业成本分析
5. project_profitability -项目利润分析
6. cost_variance_analysis -实际成本与估计成本差异
7. cash_flow_forecast -项目现金流预测
8. schedule_variance_analysis -进度延误和影响
9. client_portal_update -生成客户端进度更新
10. subcontractor_performance -分析分包商指标
11. material_tracking -跟踪材料成本和使用情况
12. labor_productivity -分析劳动效率
13. cost_per_square_foot -按交易计算$/平方英尺
14. change_order_tracking -跟踪变更单/修订
15. upgrade_pricing -定价客户端升级请求
16. update_schedule -延长/调整项目进度
17. plan_takeoff -根据建筑平面图估算
18. estimate_from_previous -根据过去的作业创建估算

60+个人工具（类别）

• 客户 -客户端的CRUD操作
• 联系人 -管理客户联系人
• 分包商 -分包商管理
• 提案 -创建和跟踪提案
• 建议线路 -提案中的行项目
• 估计 -项目估算
• 项目管理 -活动项目数据
• 项目时间表 -项目时间表
• 项目进度任务 -个人任务
• 行动项目 -通过以下方式跟踪行动项：

- 评论 - 主管人员 - 成本变化 - 计划更改

• 交易 -QuickBooks交易数据
• 工作平衡 -当前工作平衡
• 成本差异 -成本差异分析
• 发票 -发票管理
• 时间表修订 -计划变更跟踪
• 项目详细信息 -全面的项目数据
• Proposal管道 -管道分析
• 估计愿景 -估计变更历史
• CostRevisions -成本修订跟踪
• 存款 -押金/预付费管理
• 建议模板定价 -标准定价模板

______________________________________________________________________

环境变量

必需

JOEAPI_BASE_URL=http://localhost:8080  # Local JoeAPI server

可选（如果JoeAPI需要身份验证）

JOEAPI_API_KEY=your_api_key           # API key for JoeAPI
JOEAPI_USER_ID=1                      # Dev user ID

将这些设置为：

1. Claude桌面配置 （推荐）：

   "env": {
     "JOEAPI_BASE_URL": "http://localhost:8080"
   }

1. 外壳环境 （备选）：

   export JOEAPI_BASE_URL=http://localhost:8080

______________________________________________________________________

故障排除

MCP服务器未连接

1.检查JoeAPI是否正在运行：

curl http://localhost:8080/health
# Should return: {"status":"healthy",...}

2.检查MCP服务器版本：

npm run mcp:build
# Should complete without errors

3.检查克劳德桌面日志：

macOS：

tail -f ~/Library/Logs/Claude/mcp*.log

窗户：

Get-Content $env:APPDATA\Claude\logs\mcp*.log -Wait

4.手动测试MCP服务器：

npm run mcp:local
# Should output: "JoeAPI MCP Server running locally"
# Press Ctrl+C to stop

工具未出现在Claude中

1.验证配置路径是否为绝对路径：

"args": ["/Users/joe/dev/joeapi/mcp-build/local-server.js"]

不是： ["~/dev/joeapi/mcp-build/local-server.js"] ❌

2.检查禁用标志：

"disabled": false  // Should be false

3.重新启动克劳德桌面：

• 完全关闭（macOS上的Cmd+Q）
• 重新开放

4.检查MCP日志中的错误

JoeAPI连接错误

错误： JoeAPI error (401)

• JoeAPI需要身份验证
• 将API密钥或开发用户ID添加到配置

错误： JoeAPI error (404)

• 未找到终结点
• 检查JoeAPI版本是否与MCP服务器匹配

错误： ECONNREFUSED

• JoeAPI未运行
• 从以下内容开始： npm run dev

______________________________________________________________________

发展

添加新工具

1. 编辑 mcp/index.ts:

   {
     name: 'my_new_tool',
     description: 'Description of tool',
     inputSchema: {
       type: 'object',
       properties: {
         param1: { type: 'string', description: '...' }
       },
       required: ['param1']
     }
   }

1. 在中添加处理程序 CallToolRequest:

   case 'my_new_tool': {
     const { param1 } = args as { param1: string };
     result = await callJoeAPI(baseUrl, `/api/v1/endpoint`);
     break;
   }

1. 重建：

   npm run mcp:build

1. 重新启动克劳德桌面

添加新工作流

1. 增添 prompts 数组in mcp/index.ts:

   {
     name: 'my_workflow',
     description: 'Brief description',
     arguments: [...],
     prompt: 'WORKFLOW: My Workflow\n\nPURPOSE: ...\n\nSTEPS:\n1. ...'
   }

1. 重建并重新启动

______________________________________________________________________

脚本参考

# Development
npm run mcp:local     # Run TypeScript directly (tsx)
npm run dev          # Run JoeAPI server

# Production
npm run mcp:build    # Compile TypeScript → JavaScript
npm run mcp:start    # Run compiled JavaScript

# Both
npm run verify-db    # Test database connection

______________________________________________________________________

比较：Smithery与当地STDIO

______________________________________________________________________

支持

• MCP SDK文档: https://modelcontextprotocol.io
• 克劳德桌面MCP指南: https://docs.claude.com/docs/mcp
• JoeAPI问题：查看GitHub仓库
• MCP服务器代码: mcp/index.ts