UteamUP CMMS

@uteamup/mcp-server

UteamUP 的 MCP 服务客户端——支持 Claude Desktop/Code 集成，并自动进行 OAuth 2.0 身份验证

链接

• 📦 npm 包 - 使用 npx -y @uteamup/mcp-server 安装
• 📖 文档 - 完整的 MCP 集成指南
• 🐛 问题反馈 - 报告错误并申请新功能
• 💬 支持 - 获取帮助

这是什么？

此软件包可让 Claude Desktop 和 Claude Code 等 AI 助手通过模型上下文协议（MCP）连接到您的 UteamUP CMMS 系统。它会自动处理 OAuth 2.0 身份验证，因此您可以通过自然对话管理工单、资产、库存等。

Claude、Grok、Grok Bot、ChatGPT 和 MiniMax Code 的只读访问权限

使用生产环境 HTTPS 端点：

环境	MCP 服务 URL
生产环境	https://api.uteamup.com/mcp/read-only

使用您的 UteamUP 账户登录（推荐）。 租户管理员（Tenant.Update） 首先在公司的 API Keys 选项卡中启用 Allow members to connect AI assistants。 然后，每位成员连接自己的助手；无需 API 密钥或密钥。授权页面仅会显示成员作为所有者 或持有许可证且订阅有效的公司；如果不再符合条件，链接将失效（401 invalid_token）：

• Grok： 打开 连接器，选择 New Connector → Custom， 然后输入端点。Grok 会自行注册（RFC 7591），并将您带到 UteamUP 授权页面， 您可在此选择公司并允许访问。Business/Enterprise 工作区需要管理员配置连接器。
• Grok Bot： 在 Bot 的 Setup → Plugins 卡片中添加 Custom MCP server, Remote HTTPS 并填写端点；每位队友首次使用时都需要登录。
• ChatGPT： 添加自定义 MCP 服务并填写端点，然后选择 OAuth；ChatGPT 会自行注册， 您可在同一个授权页面批准访问。
• Claude： 添加自定义连接器并填写端点，选择 Sign in now 和 Register automatically，然后在 UteamUP 授权页面批准访问。
• MiniMax Code： 安装 uteamup 插件（参见安装），或在 Settings → MCP Servers 下使用 Remote / streamable-http 传输方式添加端点。 MiniMax Code 会发现受保护资源元数据，自行注册（RFC 7591），并在首次使用时打开 UteamUP 授权页面。

助手使用成员在所选公司中的自身权限，且仅使用下方的只读工具。访问令牌有效期为 60 分钟， 每次使用时都会轮换刷新令牌。成员可在 Profile → Accounts 下断开连接；管理员可在 API Keys 选项卡中查看并撤销所有链接，也可使用 uteamup_assistant_connection_list / uteamup_assistant_connection_revoke MCP 工具进行操作。关闭公司设置会立即停止所有链接。 租户 API 密钥（服务集成）。 API Keys → Set up UPMate Integration 向导 仍提供 Private read-only pilot for ChatGPT and Grok：选择一个授权仅包含 View/Read 的活动角色，并为每个助手分别创建一个启用 MCP 的密钥。在 ChatGPT 中，使用预设的客户端凭据配置 OAuth（将 API 密钥设为 Client ID， 其密钥设为 Client Secret）。Grok 仅支持登录，因此请使用上方适用于 Grok 的选项。 租户管理员仍可使用常规密钥配额、过期时间、IP 限制、速率限制、轮换和撤销控制。

仅会公布现有的资产列表、资产搜索、按 GUID 查询资产、工单列表和工单搜索工具。 在发现和调用之前，系统会检查当前的 UPMate 功能设置、角色权限和租户范围。猜测的写入／管理员工具调用会在执行前被拒绝。如果密钥持久化的角色新增了写入权限或通配符权限，或者密钥已撤销、过期或轮换，只读端点也会拒绝该密钥。 这些读取操作不会调用 UteamUP AI 提供商，也不会消耗 UteamUP AI 点数。

Node 代理可使用同一端点，并设置 UTEAMUP_MCP_PATH=/mcp/read-only。 其默认的 /mcp 传输方式保留现有行为和基于角色的授权。 CLI 继续使用现有的 API 密钥创建、角色选择和撤销命令； 无需单独的凭据存储或工具实现。

参考资料：OpenAI 自定义 MCP 服务 和 Grok 连接器。

主要功能：

• ✅ 自动进行 OAuth 2.0 + PKCE 身份验证
• ✅ 缓存令牌并自动刷新
• ✅ 适用于 Claude Desktop、Claude Code 及任何兼容 MCP 的客户端
• ✅ 无需配置——只需提供 API 凭据
• ✅ 全面的错误消息
• ✅ 解析服务器发送事件（SSE）响应
• ✅ 正确处理 JSON-RPC 2.0 通知
• ✅ **新增：**使用 Pino 进行结构化日志记录（JSON／文本格式）
• ✅ **新增：**使用 Zod 验证配置
• ✅ **新增：**性能监控和指标
• ✅ **新增：**采用指数退避的重试逻辑
• ✅ **新增：**CLI 实用工具（--help、--version、--validate-config、--test-auth）
• ✅ 全面的测试套件

**发布状态：**Beta。上方的 npm 徽章显示已发布的版本； 发布详情请参阅 CHANGELOG.md。

对话示例：

You: Show me all high-priority work orders in Building A
AI: I found 5 high-priority work orders in Building A...

You: Assign them all to John Doe
AI: Done! All 5 work orders are now assigned to John Doe.

---

安装

无需安装！使用 npx 直接运行：

npx -y @uteamup/mcp-server

或全局安装：

npm install -g @uteamup/mcp-server

作为插件安装

• Claude Code：

  claude plugin marketplace add UteamUP/uteamup-mcp
  claude plugin install uteamup@uteamup
  

• Grok Build：

  grok plugin install https://github.com/UteamUP/uteamup-mcp.git --trust
  

• Gemini CLI：

  gemini extensions install https://github.com/UteamUP/uteamup-mcp
  

• MiniMax Code：

  git clone https://github.com/UteamUP/uteamup-mcp.git
  cp -R uteamup-mcp/plugins/minimax ~/.minimax/plugins/uteamup
  

  MiniMax Code 没有插件市场。它会按文件夹发现本地插件、自动重新扫描，并默认启用新发现的插件。该插件包含只读 MCP 服务和一个 cmms 技能，用于指导 Agent 何时以及如何使用这些工具。

  若要跳过插件，可在 Settings → MCP Servers 下直接添加服务，并选择 Remote / streamable-http 传输方式，使用以下 URL（不会存储凭据）： https://api.uteamup.com/mcp/read-only

---

快速入门

1. 获取 API 凭据

1. 登录 UteamUP
2. 前往 Tenant Settings → API Keys
3. 点击 "Set up AI Integration" 或 "Create API Key"
4. 启用 "MCP Enabled" 开关
5. 点击 Create API Key
6. 复制并保存 API 密钥和 Secret（之后将无法再次查看！）

2. 配置 Claude Desktop

在 Claude Desktop 中，打开 Settings → Developer → Edit Config。 配置文件位于：

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

添加以下配置：

{
  "mcpServers": {
    "uteamup": {
      "command": "npx",
      "args": ["-y", "@uteamup/mcp-server"],
      "env": {
        "UTEAMUP_API_KEY": "your-32-character-api-key",
        "UTEAMUP_SECRET": "your-64-character-secret"
      }
    }
  }
}

所有 UteamUP MCP 连接都使用 https://api.uteamup.com。验证集成时，请使用演示工作区中的受限密钥。

3. 重启 Claude Desktop

保存配置后，重启 Claude Desktop。UteamUP 工具将自动启用。

4. 测试连接

在 Claude 中尝试：

What UteamUP tools do you have access to?

或

Show me all open work orders

就这样！🎉

---

配置

环境变量

必需

变量	描述
UTEAMUP_API_KEY	支持 MCP 的 API 密钥（32 个字符）
UTEAMUP_SECRET	API 密钥密钥（64 个或更多字符）

可选

变量	描述	默认值
UTEAMUP_API_BASE_URL	API 端点 URL	https://api.uteamup.com
UTEAMUP_LOG_LEVEL	日志级别：TRACE、DEBUG、INFO、WARN、ERROR	INFO
UTEAMUP_LOG_FORMAT	日志格式：text、json	text
UTEAMUP_DEBUG	旧版调试模式（1 或 true）	false
UTEAMUP_REQUEST_TIMEOUT	请求超时时间（毫秒）	30000
UTEAMUP_MAX_RETRIES	网络错误的最大重试次数	3
UTEAMUP_MAX_REQUEST_BYTES	单个 JSON-RPC 请求的最大字节数	1048576
UTEAMUP_MAX_RESPONSE_BYTES	单个后端响应缓冲的最大字节数	10485760
UTEAMUP_TOKEN_CACHE_DIR	持久化令牌缓存目录	-
UTEAMUP_TOKEN_REFRESH_MARGIN	令牌刷新提前时间（秒）	300

API 基础 URL

配置的基础 URL 必须是纯 HTTPS 源。系统会拒绝包含凭据、路径、查询参数、片段以及普通 HTTP 端点的 URL。

即使在本地运行 Node 代理，也始终使用 https://api.uteamup.com。完整的 MCP 端点是 /mcp；只读端点是 /mcp/read-only。

权限

AI 助手的权限由分配给 API 密钥的角色控制。若要更改 AI 可以执行的操作：

1. 在 UteamUP 中前往 租户设置 → API 密钥
2. 编辑 API 密钥
3. 更改角色（例如，管理员、主管、只读）
4. 更改立即生效，无需重新连接

提示： 为不同用途创建具有不同角色的独立 API 密钥（例如，一个用于只读查询，另一个用于完全访问）。

---

故障排除

常见问题

“缺少必需的环境变量”

原因： MCP 配置中未设置 UTEAMUP_API_KEY 或 UTEAMUP_SECRET。

解决方法：

1. 检查 Claude Desktop 配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）
2. 确认 env 部分同时包含 UTEAMUP_API_KEY 和 UTEAMUP_SECRET
3. 确保环境变量名称没有拼写错误
4. 修改后重启 Claude Desktop

---

“身份验证失败：API 密钥或密钥无效”

原因： 凭据错误，或 API 密钥已被撤销。

解决方法：

1. 在 UteamUP 中验证凭据：
   • 前往 租户设置 → API 密钥
   • 检查 API 密钥是否为有效状态（未过期或撤销）
2. 如果凭据丢失，请创建新的 API 密钥：
   • 点击 “创建 API 密钥”
   • 启用 “已启用 MCP”
   • 复制新凭据
3. 使用新凭据更新 MCP 配置
4. 重启 Claude Desktop

---

“MCP 访问被拒绝：您的 API 密钥未启用 MCP”

原因： 创建 API 密钥时未启用 MCP 支持。

解决方法：

1. 创建启用了 MCP 的新 API 密钥：
   • 前往 租户设置 → API 密钥
   • 点击 “设置 AI 集成” 或 “创建 API 密钥”
   • 重要： 确认 “已启用 MCP” 开关已打开
   • 点击 创建 API 密钥
2. 使用新凭据更新 MCP 配置
3. 重启 Claude Desktop

注意： 无法为现有 API 密钥启用 MCP。必须创建新密钥。

---

“ECONNREFUSED” 或“Connection refused”

原因： 无法连接到 API 服务。

解决方案：

1. 检查网络连接
2. 验证基础 URL：
   • 生产环境：https://api.uteamup.com（默认，无需环境变量）
3. 检查 UteamUP 是否宕机：
   • 联系 [email protected]

---

“UNABLE_TO_VERIFY_LEAF_SIGNATURE” 或证书错误

原因： 无法验证服务端的 TLS 证书。

解决方案：

1. 确认 API 基础 URL 为 https://api.uteamup.com
2. 检查设备的日期和受信任证书配置
3. 如果证书错误仍然存在，请联系 [email protected]

---

工具列表为空或不完整

原因： 凭据、角色或公司配置未授予所请求的工具权限。

解决方案：

1. 在 UteamUP 中，前往 Tenant Settings → API Keys
2. 确认密钥处于启用状态，并且已针对目标公司启用 MCP
3. 请公司管理员检查工作流所需的具体读取权限
4. 对于远程只读连接器，请使用受限的只读角色；不支持写入权限或通配符权限
5. 获得授权的权限变更后，重新连接客户端以刷新工具列表

---

调试

结构化日志

启用不同的日志级别和格式：

{
  "mcpServers": {
    "uteamup": {
      "command": "npx",
      "args": ["-y", "@uteamup/mcp-server"],
      "env": {
        "UTEAMUP_API_KEY": "your-key",
        "UTEAMUP_SECRET": "your-secret",
        "UTEAMUP_LOG_LEVEL": "DEBUG",
        "UTEAMUP_LOG_FORMAT": "json"
      }
    }
  }
}

日志级别：

• TRACE：最详细，包含所有请求/响应正文（已脱敏）
• DEBUG：详细的调试信息
• INFO：常规信息消息（默认）
• WARN：警告消息
• ERROR：仅记录错误

日志格式：

• text：易于阅读的美化日志（开发环境）
• json：结构化 JSON 日志（生产环境）

敏感数据： 所有凭据、令牌和密钥都会在日志中自动脱敏。

注意： 日志写入 stderr，而非 stdout（stdout 专用于 JSON-RPC 消息）。

---

仍有问题？

1. 检查日志：

   • Claude Desktop：View → Developer → Developer Tools → Console
   • 查找 [MCP Proxy] 消息

2. 验证凭据格式：

   • API Key：恰好 32 个字符
   • Secret：至少 64 个字符
   • 不含多余空格或引号

3. 手动测试：

   export UTEAMUP_API_KEY="your-key"
   export UTEAMUP_SECRET="your-secret"
   export UTEAMUP_DEBUG="1"
   echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx @uteamup/mcp-server
   

4. 获取帮助：

   • 电子邮件：[email protected]
   • 文档：https://github.com/UteamUP/uteamup-mcp#readme
   • GitHub Issues：https://github.com/UteamUP/uteamup-mcp/issues

---

开发

本地开发环境设置

# Clone the repository
git clone https://github.com/UteamUP/uteamup-mcp.git
cd uteamup-mcp

# Install dependencies
npm install

# Run tests only at the final whole-goal gate (see MCPGuidelines.md)
UTEAMUP_FINAL_GOAL_GATE=1 npm test

# Test with debug logging
export UTEAMUP_LOG_LEVEL=DEBUG
export UTEAMUP_API_KEY="your-demo-workspace-key"
export UTEAMUP_SECRET="your-demo-workspace-secret"
export UTEAMUP_API_BASE_URL="https://api.uteamup.com"
node index.js

# CLI Utilities
node index.js --help                # Show help
node index.js --version             # Show version
node index.js --validate-config     # Validate environment variables
node index.js --test-auth           # Test OAuth authentication

# Test with a sample request
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node index.js

使用 Claude Desktop 在本地测试

# Create a local link
npm link

# Update Claude Desktop config to use local version
{
  "mcpServers": {
    "uteamup-local": {
      "command": "node",
      "args": ["/absolute/path/to/uteamup-mcp/index.js"],
      "env": {
        "UTEAMUP_API_KEY": "your-key",
        "UTEAMUP_SECRET": "your-secret",
        "UTEAMUP_DEBUG": "1"
      }
    }
  }
}

项目结构

uteamup-mcp/
├── index.js           # Main entry point (OAuth + MCP client)
├── package.json       # Package metadata
├── README.md          # This file
├── LICENSE            # MIT license
├── CHANGELOG.md       # Version history
├── .gitignore         # Git ignore rules
├── .npmignore         # Files to exclude from npm package
└── test/              # Test files (not published)
    ├── oauth.test.js
    └── integration.test.js

运行测试

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run only integration tests (requires credentials)
npm run test:integration

# Run with coverage
npm test -- --coverage

代码风格

本项目使用：

• ESLint 进行代码检查
• Prettier 进行格式化
• CommonJS 模块（而非 ESM），以实现最大兼容性

# Lint code
npm run lint

# Format code
npm run format

---

贡献

欢迎贡献！请按以下步骤操作：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行更改
4. 为新功能添加测试
5. 确保所有测试通过（npm test）
6. 提交更改（git commit -m 'Add amazing feature'）
7. 推送到分支（git push origin feature/amazing-feature）
8. 创建 Pull Request

提交消息格式

type(scope): subject

Types: feat, fix, docs, refactor, test, chore
Scope: oauth, client, docs, etc.

Example:
feat(oauth): add automatic token refresh on expiry
fix(client): handle network timeouts gracefully
docs(readme): update troubleshooting section

---

许可证

MIT © UteamUP

详情请参阅 LICENSE。

---

支持

• 文档： https://github.com/UteamUP/uteamup-mcp#readme
• 电子邮件： [email protected]
• 问题反馈： https://github.com/UteamUP/uteamup-mcp/issues

---

相关链接

• UteamUP 网站
• Model Context Protocol 规范
• Claude Desktop
• OAuth 2.0 PKCE