Humaans

@mindstone/mcp-server-humaans

面向 Model Context Protocol 主机的 Humaans 人力资源平台 MCP 服务。通过标准化的 MCP 接口查询员工档案、职位、休假申请、公司信息和办公地点。

状态

• 版本： 0.3.1 · npm
• 认证： API 密钥（HUMAANS_API_KEY）
• 工具： 16（人员、职位、休假、公司、团队）
• 接口： cloud-api
• 机器可读： STATUS.json

要求

• Node.js 20+
• npm

一键安装

点击按钮后，主机将提示你填写：HUMAANS_API_KEY。

{
  "mcpServers": {
    "Humaans": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-humaans"
      ],
      "env": {
        "HUMAANS_API_KEY": ""
      }
    }
  }
}

快速开始

安装与构建

cd <path-to-repo>/connectors/humaans
npm install
npm run build

npx（发布后使用）

npx -y @mindstone/mcp-server-humaans

本地

node dist/index.js

配置

环境变量

• HUMAANS_API_KEY — Humaans API 访问令牌（在应用设置中获取）
• MCP_HOST_BRIDGE_STATE — 主机桥接状态文件的可选路径，用于凭据管理
• MINDSTONE_REBEL_BRIDGE_STATE — MCP_HOST_BRIDGE_STATE 的向后兼容别名

主机配置示例

Claude Desktop / Cursor

{
  "mcpServers": {
    "Humaans": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-humaans"],
      "env": {
        "HUMAANS_API_KEY": "your-api-key"
      }
    }
  }
}

本地开发（无需发布 npm 包）

{
  "mcpServers": {
    "Humaans": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/humaans/dist/index.js"],
      "env": {
        "HUMAANS_API_KEY": "your-api-key"
      }
    }
  }
}

工具（16）

配置

• configure_humaans_api_key — 配置 Humaans API 访问令牌

人员

• get_humaans_me — 获取当前已认证用户的档案
• list_humaans_people — 列出员工
• get_humaans_person — 根据 ID 获取完整的员工档案
• list_humaans_teams — 列出团队名称和成员数量（根据人员目录推导；Humaans 没有专门的团队端点）

职位

• list_humaans_job_roles — 列出员工的职位历史
• get_humaans_job_role — 根据 ID 获取指定职位

休假

• list_humaans_time_away — 列出休假记录（带薪休假、病假等）
• create_humaans_time_away — 创建休假申请
• list_humaans_time_away_types — 列出可用的休假类型
• list_humaans_time_away_allocations — 列出休假额度分配（适用于每个人的政策）
• cancel_humaans_time_away — 取消（永久删除）休假记录
• approve_humaans_time_away — 批准待处理的休假申请（经理操作）
• decline_humaans_time_away — 拒绝待处理的休假申请（经理操作）

公司

• list_humaans_locations — 列出公司地点／办公室
• get_humaans_company — 获取公司信息

数据处理

• 人员列表响应采用字段白名单；人员详情响应会移除敏感字段（税号、个人电子邮件/电话、家庭住址、生日、个人照片）。
• 在 Humaans 中填写的自由文本字段（请假 note/reviewNote、职位角色 note/jobTitle/department、请假类型和政策名称、团队名称、人员资料中的自由文本，如姓名/bio/社交链接/职位、地点标签/城市、公司名称）会以 <untrusted-content> 封装，供模型将其视为数据而非指令。
• Humaans API 错误响应正文在传递给模型前会经过封装（非 JSON 正文还会进行长度限制）；Retry-After 在速率限制消息中只会作为解析后的整数传递，而格式错误的 2xx 正文会生成静态错误，而不会生成包含正文片段的解析器消息。

许可证

FSL-1.1-MIT —— 功能源代码许可证 1.1 版，附带未来生效的 MIT 许可证。本软件将于 2030-04-08 转为 MIT 许可证。