Itcons.app

Itcons.app MCP 服务

用于将 AI 助手连接到 Itcons.app 的模型上下文协议服务。

Itcons.app 是一个业务运营平台，用于管理工作报告、工单、项目、客户、用户和相关运营资源。它旨在帮助团队围绕日报、任务分配、任务跟踪和服务执行，将现场与办公室工作流数字化。

此软件包可在两种模式下运行：

• 本地 stdio 模式，适用于 Codex、Claude Desktop 和其他本地 MCP 主机等客户端。
• 远程 HTTP 模式，适用于 ChatGPT Apps 等托管 MCP 客户端，或其他需要公开 HTTPS MCP 端点的客户端。

借助此 MCP 服务，助手可以查询 Itcons.app 数据、搜索工作报告和工单、列出状态、用户、资源、项目和客户等运营目录，并在已配置用户拥有相应权限时创建受支持的 Itcons.app 记录。

功能

• 使用 POST /api/login_check 进行身份验证。
• 使用 Bearer 身份验证调用 Itcons.app API。
• 从 ITCONS_DOMAIN 解析 API 基础 URL。
• 列出状态、用户、资源、客户、项目、工单类型和工作报告模板。
• 搜索工作报告和工单。
• 创建客户、项目、用户和工单。

此 MCP 服务有意不包含 Webhook。远程 HTTP 模式用于 MCP 客户端流量，而非接收 Itcons.app Webhook。

安装

从 npm 安装：

npm install -g @itcons-app/mcp

从此代码库安装：

npm install
npm run check

如果通过 Homebrew 安装了 Node，且 node/npm 不在 PATH 中，请使用：

/opt/homebrew/opt/node/bin/npm install
/opt/homebrew/opt/node/bin/npm run check

配置

本地 stdio 服务从环境变量读取 Itcons.app 凭据。

ITCONS_DOMAIN=demo
[email protected]
ITCONS_PASSWORD=change-me
ITCONS_TIMEZONE=Europe/Madrid

对于 https://demo.itcons.app，请设置：

ITCONS_DOMAIN=demo

也可以使用现有的 Bearer 令牌代替用户名/密码：

ITCONS_DOMAIN=demo
ITCONS_TOKEN=ey...

ITCONS_API_BASE_URL 是可选的。如果省略，服务将使用：

https://ITCONS_DOMAIN.itcons.app/api

MCP 客户端示例

使用全局安装的软件包进行配置的示例：

{
  "mcpServers": {
    "itcons-app": {
      "command": "itcons-app-mcp",
      "env": {
        "ITCONS_DOMAIN": "demo",
        "ITCONS_USERNAME": "[email protected]",
        "ITCONS_PASSWORD": "change-me",
        "ITCONS_TIMEZONE": "Europe/Madrid"
      }
    }
  }
}

远程 HTTP 服务

启动远程 MCP 服务：

PORT=3000 \
HOST=127.0.0.1 \
ITCONS_MCP_PUBLIC_URL=https://mcp.example.com \
ITCONS_OAUTH_CLIENT_ID=itcons-app-chatgpt \
ITCONS_OAUTH_CLIENT_SECRET=change-me \
npm run start:http

远程服务提供以下端点：

• MCP Streamable HTTP 端点：https://mcp.example.com/mcp
• 仅报告的 MCP 端点，适用于公开的 ChatGPT 应用：https://mcp.example.com/reports-mcp
• 兼容 SSE 的端点：https://mcp.example.com/sse
• OAuth 授权 URL：https://mcp.example.com/oauth/authorize
• OAuth 令牌 URL：https://mcp.example.com/oauth/token
• OAuth 动态客户端注册 URL：https://mcp.example.com/oauth/register
• 健康检查：https://mcp.example.com/health

在 ChatGPT 的“Create app”页面中，请使用公开的 MCP URL：

https://mcp.example.com/mcp

如需专注于工作报告的精简公开应用，请使用：

https://mcp.example.com/reports-mcp

如果客户端明确要求提供 SSE URL，请使用：

https://mcp.example.com/sse

用户连接应用时，OAuth 登录页面会要求输入其 Itcons.app 电子邮件和密码。如果配置了 ITCONS_DOMAIN_LOOKUP_URL，页面会尝试根据电子邮件检测 Itcons.app 域名；否则，用户可以手动输入域名。服务会使用 Itcons.app 验证这些凭据，并在内存中存储会话令牌，以供后续 MCP 调用使用。

使用本地代码副本进行配置的示例：

{
  "mcpServers": {
    "itcons-app": {
      "command": "node",
      "args": [
        "/absolute/path/to/itcons-app-mcp/src/index.js"
      ],
      "env": {
        "ITCONS_DOMAIN": "demo",
        "ITCONS_USERNAME": "[email protected]",
        "ITCONS_PASSWORD": "change-me",
        "ITCONS_TIMEZONE": "Europe/Madrid"
      }
    }
  }
}

工具

只读工具：

• itcons_check_connection
• itcons_list_workorder_types
• itcons_list_work_report_models
• itcons_list_projects
• itcons_list_clients
• itcons_list_statuses
• itcons_list_users
• itcons_list_resources
• itcons_search_workorders
• itcons_list_pending_workorders
• itcons_search_work_reports
• itcons_list_work_reports_by_date
• itcons_list_today_work_reports

创建工具：

• itcons_create_workorder
• itcons_create_user
• itcons_create_project
• itcons_create_client

由 /reports-mcp 提供的仅报告配置工具：

• itcons_check_connection
• itcons_list_work_report_models
• itcons_search_work_reports
• itcons_list_work_reports_by_date
• itcons_list_today_work_reports

工具注解：

• 只读工具设置 readOnlyHint: true、destructiveHint: false 和 openWorldHint: false，因为它们仅读取私有 Itcons.app 数据。
• 创建工具设置 readOnlyHint: false、destructiveHint: false 和 openWorldHint: false，因为它们只在私有 Itcons.app 工作区内创建记录，不会发布到公共互联网平台。

环境变量

变量	必需	说明
ITCONS_DOMAIN	是	安装子域名。对于 https://demo.itcons.app，请使用 demo。
ITCONS_USERNAME	是，除非设置了 ITCONS_TOKEN	Itcons.app 用户名或电子邮件地址。
ITCONS_PASSWORD	是，除非设置了 ITCONS_TOKEN	Itcons.app 密码。
ITCONS_TOKEN	否	现有的 Bearer 令牌。设置后会跳过登录。
ITCONS_API_BASE_URL	否	备用 API 基础 URL。
ITCONS_TIMEZONE	否	itcons_list_today_work_reports 使用的时区。默认为 Europe/Madrid。
PORT	否	HTTP 服务端口。默认为 3000。
HOST	否	HTTP 服务绑定的主机。默认为 127.0.0.1。
ITCONS_MCP_PUBLIC_URL	远程模式下必需	公共 HTTPS 来源，例如 https://mcp.example.com。
ITCONS_MCP_PATH	否	远程 MCP 端点路径。默认为 /mcp。
ITCONS_MCP_SSE_PATH	否	兼容 SSE 的端点路径。默认为 /sse。
ITCONS_MCP_ALLOWED_HOSTS	远程模式下建议设置	以逗号分隔的允许访问的 Host 标头，例如 mcp.example.com。
ITCONS_OAUTH_CLIENT_ID	否	远程服务预期的 OAuth 客户端 ID。默认为 itcons-app-chatgpt。
ITCONS_OAUTH_CLIENT_SECRET	远程模式下建议设置	远程服务预期的 OAuth 客户端密钥。
ITCONS_OAUTH_CLIENTS_FILE	公共应用建议设置	用于持久化动态注册的 OAuth 客户端的 JSON 文件。
ITCONS_DOMAIN_LOOKUP_URL	否	用于根据电子邮件检测 Itcons.app 域名的端点。默认为 https://auto.itcons.app/webhook/my-domain。
ITCONS_HTTP_AUTH_DISABLED	否	仅在本地 HTTP 冒烟测试中设为 1。禁用远程 MCP Bearer 身份验证。

说明

• 工单的待处理状态为 4。
• itcons_search_workorders 获取 /workorders 并在本地应用筛选条件。
• itcons_list_work_reports_by_date 根据 /2.0/partes 返回的 date 字段进行筛选。
• itcons_create_workorder 发送 status: 4 和 isArchived: 0。
• itcons_create_user 向 /2.0/users 发送数组负载，以匹配当前 API。
• itcons_create_client 向 /clients 发送数组负载，并在适用时返回数组中的第一项。

开发

运行语法检查：

npm run check

运行本地 MCP 发现冒烟测试：

npm run smoke

运行本地 HTTP MCP 冒烟测试：

npm run smoke:http

针对 Itcons.app 运行实时只读 HTTP 冒烟测试：

ITCONS_DOMAIN=demo \
[email protected] \
ITCONS_PASSWORD=change-me \
npm run smoke:http:live

运行实时 OAuth 冒烟测试，模拟 ChatGPT 风格的连接：

ITCONS_DOMAIN=demo \
[email protected] \
ITCONS_PASSWORD=change-me \
npm run smoke:oauth:live

针对 Itcons.app 运行实时只读冒烟测试：

ITCONS_DOMAIN=demo \
[email protected] \
ITCONS_PASSWORD=change-me \
npm run smoke:live

发布公共 npm 包：

npm publish --access public

安全

请勿提交 .env 文件或真实凭据。该软件包在发布到 npm 时会排除 .env、node_modules 和调试日志。

创建工具会在 Itcons.app 中执行实际写入操作。请仅在 MCP 客户端获准进行更改的凭据和安装环境中使用这些工具。

内置的远程 OAuth 实现会将授权码和访问令牌存储在内存中。首次部署时请使用单个 Node.js 进程；如果要运行多个副本，请先将内存映射替换为 Redis 等持久化存储。