使用说明

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设置

先决条件

JoeAPI在本地运行：

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

构建MCP服务器：
```
npm run mcp:build
```
配置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个预构建工作流

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

将这些设置为：

Claude桌面配置 （推荐）：

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

外壳环境 （备选）：

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

发展

添加新工具

编辑 mcp/index.ts:

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

在中添加处理程序 CallToolRequest:

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

重建：
```
npm run mcp:build
```
重新启动克劳德桌面

添加新工作流

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

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

重建并重新启动

脚本参考

# 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

功能	Smithery（云）	本地STDIO
设置	已部署	需要本地设置
访问	远程，任何地方	仅限本地计算机
速度	网络延迟	即时（本地）
可用性	始终开启	需要运行JoeAPI
更新	自动部署	需要手动构建
协作	团队访问权限	单用户
最适合	生产、团队	开发、测试

支持

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