BoondManager MCP Server

BoondManager MCP 服务

来自 Silamir 的开源项目。

一键安装：

LM Studio、Goose 和 Gemini CLI 需通过各自专用流程（原生 deeplink 或命令）安装——请参阅安装一节。GitHub 不会将非 HTTP 协议链接（lmstudio://、goose://）呈现为可点击链接，因此此处没有提供一键安装按钮。

BoondManager API 的 MCP（Model Context Protocol）服务，可让 Claude（Desktop、Cowork、Code）在您的 BoondManager 实例中搜索、查看、创建和修改记录。

238 个工具，覆盖 BoondManager API 的 42 个领域。请参阅 TOOLS.md，查看自动生成的目录（工具 + 提示词 + 资源）。

结构化输出。 除了可读文本，search、create、update 和 delete 工具还会返回符合 MCP outputSchema 的 structuredContent：search → { total?, count, items[] }（紧凑摘要，不包含完整的 JSON:API 资源），create/update → { id?, type? }，delete → { id, deleted, reason? }。利用结构化输出的 MCP 客户端可以获得可靠的实体引用，以便串联调用。get 工具仍然只返回文本（其文本本身已是可处理的 JSON）。

目录

• 涵盖的领域
• 预编排提示词
• 安装：Claude Desktop、Claude Code、Cursor、VS Code
• 配置和身份验证
• 传输方式（stdio、HTTP + OAuth2、Docker）
• 使用示例
• 故障排除

涵盖的领域

CRM 与商务

领域	工具	操作
候选人	10	CRUD + 信息、技术数据、行政信息、操作、定位
资源	20	CRUD + 信息、技术数据（+ 更新）、行政信息、福利、操作、定位、项目、工时报告、费用报告、缺勤报告、工时表、参考信息（创建/更新/删除）
联系人	11	CRUD + 信息、操作、商机、项目、订单、发票
公司	14	CRUD + 信息、联系人、操作、商机、项目、订单、发票、采购、供应商发票
商机	10	CRUD + 信息、操作、定位、项目、模拟

项目管理

领域	工具	操作
项目	12	CRUD + 信息、操作、模拟、交付分组、订单、采购、生产率
定位	4	搜索、获取、创建、删除
交付 / CRA	2	搜索、获取
采购 / 分包	4	搜索、获取、创建、删除

开票与财务

领域	工具	操作
客户发票	5	完整 CRUD
供应商发票	2	搜索、获取
采购订单	5	完整 CRUD
付款	2	搜索、获取
费用报销单	5	完整 CRUD
产品	5	完整 CRUD

人力资源与工时

领域	工具	操作
缺勤	5	完整 CRUD
缺勤计划	1	搜索（全局视图）
工时表	3	搜索、获取、资源工时表
合同	2	获取、创建
福利	2	搜索、获取

活动跟踪

领域	工具	操作
操作	5	搜索、获取、创建、更新、删除
验证	2	搜索、获取
待办列表	2	搜索、获取

报表

领域	工具	操作
公司报表	1	搜索
项目报表	1	搜索
资源报表	1	搜索
汇总报表	1	搜索
生产计划报表	1	搜索

管理与配置

领域	工具	操作
用户账户	2	search、get
机构	2	search、get
业务单元	2	search、get
部门	2	search、get
角色	2	search、get
日历	2	search、get
标记 / 标签	2	search、get
Webhooks	2	search、get
审计日志	2	search、get
通知	2	search、get
讨论串	2	search、get
文档 / CV	4	get（下载）、create（通过 URL、本地文件、中继槽位或 base64 上传，并解析 CV）、upload_slot（SharePoint 中继）、delete
应用程序	2	字典、当前用户

各实体的标签页详情

主要实体均为每个标签页提供专用工具，便于精准访问：

实体	可用标签页
候选人	information、technical-data、administrative、actions、positionings
资源	information、technical-data、administrative、advantages、actions、positionings、projects、times-reports、expenses-reports、absences-reports
联系人	information、actions、opportunities、projects、orders、invoices
公司	information、contacts、actions、opportunities、projects、orders、invoices、purchases、provider-invoices
商机	information、actions、positionings、projects、simulation
项目	information、actions、simulation、deliveries-groupments、orders、purchases、productivity

MCP 资源（字典）

服务器将 Boond 参考字典作为 MCP 资源公开（支持显示资源的客户端：Claude Desktop、MCP Inspector 等）。这使模型无需额外调用工具，即可将整数 state 或 typeOf 转换为标签。

URI	内容
boond://application/current-user	当前用户的个人资料（id、机构、权限）
boond://dictionary/states/{entity}	各实体的状态：resources、candidates、contacts、companies、opportunities、projects、invoices、orders、positionings、deliveries、payments、purchases、provider-invoices、products、quotations、probations
boond://dictionary/typeOf/{entity}	各实体的类型：resources、contacts、projects、contracts、deliveries、purchases、activities
boond://dictionary/actions/{entity}	按关联实体划分的操作类型：candidates、contacts、resources、opportunities、projects、invoices、orders（boond_actions_create 的 typeOf）
boond://dictionary/{sources,origins}	候选人来源、商机来源
boond://dictionary/{paymentMethods,paymentTerms,taxRates,contractEndReasons}	记账时使用的财务 / 人力资源参数
boond://application/current-user/rights	用户的级别、机构 / 部门 / 业务单元、应用及各实体权限（current-user 的精简视图）
boond://dictionary/countries	国家列表
boond://dictionary/currencies	货币列表
boond://dictionary/languages	语言列表

对于此精选列表之外的字典，仍可使用工具 boond_application_dictionary。

预编排提示词

除工具外，服务器还公开 MCP 提示词（预先配置的模板），可按正确顺序编排适用于常见工作流的工具调用。在支持提示词的客户端（Claude Desktop、Cowork、Claude Code、MCP Inspector 等）中，这些提示词会以斜杠命令或菜单的形式显示。

跨工作流

提示词	用途
synthese_equipe	团队概况：谁负责什么、谁不在、谁有空（默认：我的团队）。
pipeline_commercial	某个时间段内即将成交的商机：按状态分布、加权营收、前 10 名。
factures_a_relancer	已逾期的未付款发票，按公司分组。
candidats_pour_opportunite	根据商机推荐匹配的在职候选人（工具、专业领域、出差意愿、空闲情况）。
fiche_consultant	查看某个资源的 360 度概况：信息 + 技术能力 + 岗位安排 + 缺勤情况 + 最近的 CRA。
recap_hebdo	每周回顾：有变动的销售管道、缺勤团队成员、活跃项目、待办事项。
traiter_note_de_frais	根据附带的凭证照片/PDF 提取费用，并在汇总和明确确认后，在 Boond 中创建费用条目。

资源、技能与简历

提示词	用途
staffing_disponible	在指定时间段内可用的内部顾问（可选按自由技能和范围筛选），按可用时间从近到远排序，并优先列出前 3 名。
fin_de_mission	预警 N 天内结束的任务（默认 60 天）。对 <= 15 天且未找到接替人员的任务标记为紧急。
cartographie_competences	某个范围（团队 / 分支机构）的技能图谱：前 N 项、稀缺技能（单点故障）、饱和技能，以及相对于开放商机的技能缺口。
cvs_a_mettre_a_jour	审查简历 / 技术档案的新鲜度（可配置过时阈值）。优先关注即将进入市场的资源。
recherche_profil_competences	按自由技能组合进行多来源搜索（内部资源 + 候选人），无需指定商机。按匹配度 /10 排序。

如何调用提示词

MCP 提示词是用户消息模板：由你自行调用，随后 LLM 会执行其中包含的运行手册。无需了解 BoondManager 筛选条件——所有内容都已内置在服务端。

Claude Desktop / Cowork / MCP Inspector：在输入栏中输入 /，从列表中选择提示词，在显示的表单中填写参数，然后确认。

Claude Code：操作相同，输入 / 后选择；系统会直接询问参数。

备用方式（没有专用提示词 UI 的客户端）：在普通请求中按名称提及提示词，客户端会通过 MCP 协议获取其定义。例如："运行 staffing_disponible 运行手册，时间为 2026 年 6 月 1 日至 9 月 1 日，技能为 Java Spring AWS"。

资源 / 技能 / 简历提示词的调用示例：

/staffing_disponible
  start_date  = 2026-06-01
  end_date    = 2026-09-01
  competences = Java Spring AWS Kubernetes
  manager_id  = (vide -> mon equipe)

/fin_de_mission
  horizon_jours = 30

/cartographie_competences
  agency_id = 7
  top_n     = 15

/cvs_a_mettre_a_jour
  seuil_mois = 6

/recherche_profil_competences
  competences        = .NET Azure DevOps
  experience_min     = 5 ans
  dispo_avant        = 2026-07-15
  inclure_candidats  = oui

修改 Claude 配置（claude_desktop_config.json 等）后，请重启客户端：MCP 提示词列表不会热重载。

前提条件

• Node.js >= 22
• 拥有 BoondManager 账户并已开通 API 访问权限
• 在 BoondManager 配置中启用“Allow API Rest calls using BasicAuth authentication”选项（如果使用 BasicAuth）

安装

Claude Desktop（一键安装）

从 GitHub 最新发布版本下载 .mcpb 文件，然后在 Claude Desktop 中选择：文件 > 安装扩展…，并选中该文件。安装时会要求输入凭据，并以加密方式存储（macOS Keychain / Windows Credential Manager）。

Claude Code（插件，推荐）

体验与一键式 Desktop 一样便捷：通过配置表单设置，无需自行配置环境变量。

/plugin marketplace add silamir/boondmanager-mcp-server
/plugin install boondmanager-mcp@boondmanager

Claude Code 随后会显示包含 14 项选项的表单（凭据、基础 URL、访问限制）。表单中的所有选项均为可选，但必须填写一种身份验证方式：User Token + Client Token + Client Key 三项组合（自动生成 JWT，推荐），预先生成的 Token JWT，或 Utilisateur + Mot de passe 组合（BasicAuth）。留空的字段将使用默认值。

如果服务器没有立即出现在 /mcp 中，只需运行 /reload-plugins，无需重启 Claude Code。

实用信息：

• 密钥的存储位置：5 个敏感字段（User Token、Client Token、Client Key、Token JWT、Mot de passe）会存储在 macOS Keychain 中（如果不可用，则存储在 ~/.claude/.credentials.json 中），不会存储在 settings.json 中。非敏感选项（URL、限制）以明文形式存储在 ~/.claude/settings.json 的 pluginConfigs 中。
• 工具命名：客户端中的工具名称带有 mcp__boondmanager__ 前缀，例如 mcp__boondmanager__boond_candidates_search。权限允许列表中必须使用此名称。
• 版本：插件会启动清单中固定的 npm 版本。要升级到新版本，请运行 /plugin marketplace update boondmanager，然后重新安装插件。
• 限制功能范围：表单中的 Restriction 字段映射到 BOOND_MCP_* 环境变量（业务配置文件、领域、操作、只读）。请参阅 docs/access-control.md。
• 删除操作：Claude Code 支持 MCP elicitation，因此每个 boond_*_delete 操作执行前都会要求确认（Confirmer les suppressions 选项默认启用）。

卸载命令：/plugin uninstall boondmanager-mcp@boondmanager。

Claude Code（手动，claude mcp add）

如果您想自行管理环境变量，或固定使用与插件不同的版本，建议采用此方式。

# Avec un token API (recommande)
claude mcp add --transport stdio --env BOOND_API_TOKEN=votre_token_jwt \
  boondmanager -- npx -y boondmanager-mcp-server

# Avec BasicAuth
claude mcp add --transport stdio \
  --env BOOND_USER=votre_login \
  --env BOOND_PASSWORD=votre_mot_de_passe \
  boondmanager -- npx -y boondmanager-mcp-server

Windows：在 npx 前添加 cmd /c：

claude mcp add --transport stdio --env BOOND_API_TOKEN=votre_token \
  boondmanager -- cmd /c npx -y boondmanager-mcp-server

要让服务器在您的所有项目中都可用，请添加 --scope user：

claude mcp add --transport stdio --scope user \
  --env BOOND_API_TOKEN=votre_token_jwt \
  boondmanager -- npx -y boondmanager-mcp-server

Claude Code - 团队共享配置

在项目根目录中添加 .mcp.json 文件（并提交到 git）：

{
  "mcpServers": {
    "boondmanager": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "boondmanager-mcp-server"],
      "env": {
        "BOOND_API_TOKEN": "${BOOND_API_TOKEN}"
      }
    }
  }
}

团队成员只需在自己的计算机上设置环境变量 BOOND_API_TOKEN。.mcp.json 文件支持 ${VAR} 和 ${VAR:-default} 环境变量语法。

Claude Code Enterprise（受管部署）

管理员可以通过 managed-mcp.json 文件为所有用户部署 MCP 服务：

OS	路径
macOS	/Library/Application Support/ClaudeCode/managed-mcp.json
Linux / WSL	/etc/claude-code/managed-mcp.json
Windows	C:\Program Files\ClaudeCode\managed-mcp.json

{
  "mcpServers": {
    "boondmanager": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "boondmanager-mcp-server"],
      "env": {
        "BOOND_API_TOKEN": "${BOOND_API_TOKEN}",
        "BOOND_BASE_URL": "https://votre-instance.boondmanager.com/api"
      }
    }
  }
}

此文件会独占管理 MCP 服务：用户无法在此配置之外添加或修改服务。

若要限制允许使用的服务，同时允许用户添加服务，请改用 managed-settings.json：

{
  "allowedMcpServers": [
    { "serverName": "boondmanager" }
  ]
}

Claude Desktop / Cowork（手动配置）

在 Claude 配置文件中添加：

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

{
  "mcpServers": {
    "boondmanager": {
      "command": "npx",
      "args": ["-y", "boondmanager-mcp-server"],
      "env": {
        "BOOND_API_TOKEN": "votre_token_jwt"
      }
    }
  }
}

通过 npm

npx boondmanager-mcp-server

或进行全局安装：

npm install -g boondmanager-mcp-server
boondmanager-mcp-server

从源代码安装

git clone https://github.com/silamir/boondmanager-mcp-server.git
cd boondmanager-mcp-server
npm install
npm run build

Smithery

该服务也可通过 Smithery 使用。配置位于仓库根目录下的 smithery.yaml 中：Smithery 提供了包含身份验证字段的 UI（自动 JWT / 预构建 JWT / BasicAuth），并通过 npx 安装该服务。

LobeChat / LobeHub

该服务已列入 LobeHub MCP 市场。在 LobeChat（可自托管或使用云端版）中，通过 设置 > 插件 > MCP > 添加添加 MCP，并填写：

{
  "name": "boondmanager",
  "command": "npx",
  "args": ["-y", "boondmanager-mcp-server"],
  "env": {
    "BOOND_USER_TOKEN": "<votre_user_token>",
    "BOOND_CLIENT_TOKEN": "<votre_client_token>",
    "BOOND_CLIENT_KEY": "<votre_client_key>"
  }
}

也可以使用 HTTP 传输（参见传输一节），以网关模式进行共享部署。

Cursor

点击 README 顶部的 Add to Cursor 徽章（或在 设置 > MCP > 添加新的 MCP 服务中手动添加该服务）。然后在 ~/.cursor/mcp.json 中为该服务添加 env 块，填写身份验证信息：

{
  "mcpServers": {
    "boondmanager": {
      "command": "npx",
      "args": ["-y", "boondmanager-mcp-server"],
      "env": {
        "BOOND_API_TOKEN": "votre_token_jwt"
      }
    }
  }
}

VS Code（GitHub Copilot / MCP Agent）

点击 README 顶部的 Install in VS Code 徽章，或将该服务添加到 .vscode/mcp.json（按项目配置）或用户的 settings.json 中：

{
  "servers": {
    "boondmanager": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "boondmanager-mcp-server"],
      "env": {
        "BOOND_API_TOKEN": "${input:boond_api_token}"
      }
    }
  }
}

LM Studio

在 LM Studio 中：Program > Install > Edit mcp.json，然后添加：

{
  "mcpServers": {
    "boondmanager": {
      "command": "npx",
      "args": ["-y", "boondmanager-mcp-server"],
      "env": {
        "BOOND_API_TOKEN": "votre_token_jwt"
      }
    }
  }
}

Goose

在 设置 > 扩展 > 添加中添加一个 STDIO 类型的扩展，命令为 npx -y boondmanager-mcp-server，并设置环境变量 BOOND_API_TOKEN。使用 CLI：

goose session --with-extension "npx -y boondmanager-mcp-server"

Gemini CLI

仓库内含 Gemini CLI 扩展清单（gemini-extension.json）。直接从 GitHub 安装该扩展：

gemini extensions install https://github.com/silamir/boondmanager-mcp-server

然后在环境中设置身份验证信息（Gemini 会在启动时插值 ${VAR}）：

export BOOND_API_TOKEN="votre_token_jwt"
# ou le trio JWT auto :
export BOOND_USER_TOKEN="..." BOOND_CLIENT_TOKEN="..." BOOND_CLIENT_KEY="..."

配置

日志

该服务使用 pino 输出结构化 JSON 日志（适用于聚合器和可观测性工具）。

变量	默认值	描述
LOG_LEVEL	info	日志级别：trace、debug、info、warn、error、fatal
LOG_FORMAT	(自动)	json 表示纯 JSON，否则在开发环境中使用 pino-pretty

在生产环境（NODE_ENV=production）中，默认以 JSON 格式记录日志。在开发环境中，默认启用 pretty（彩色）格式，除非设置了 LOG_FORMAT=json。每个 HTTP 请求都会获得一个 corrId（8 位十六进制数），用于在日志中追踪请求。

无论使用何种传输方式，日志始终写入 stderr：在 stdio 模式下，stdout 专用于 JSON-RPC 数据流，任何其他输出都会破坏客户端连接。Claude Desktop 会在其日志查看器（Developer → Logs）中捕获 stderr，因此访问策略、可用更新和字典相关警告都会显示在这里。

身份验证

选项 1：JWT API Token（推荐）

export BOOND_API_TOKEN="votre_token_jwt"

选项 2：BasicAuth

export BOOND_USER="votre_login"
export BOOND_PASSWORD="votre_mot_de_passe"

带静态身份验证的 HTTP 传输（BOOND_HTTP_STATIC_AUTH）

默认情况下，HTTP 传输（MCP_TRANSPORT=http）是一种 OAuth2 受保护资源：每个 MCP 请求都携带其对应用户的 BoondManager 令牌（参见 docs/oauth.md）。BOOND_HTTP_STATIC_AUTH=true 会将此模式替换为上述环境凭据，并由所有请求共享，适用于可自托管的单租户部署、CI 流水线或无需 OAuth 流程的内部网关。

在此模式下，MCP 客户端不再经过任何身份验证：任何能够访问该端口的人都将拥有操作员的 BoondManager 权限（根据访问策略，可读写）。因此：

变量	作用
MCP_HTTP_API_KEY	客户端必须提供的共享密钥，格式为 Authorization: Bearer <clé> 或 X-Api-Key: <clé>。使用恒定时间比较；缺失或错误 → 401。只要服务器未监听 loopback（0.0.0.0、Docker 镜像），此项就必须设置，否则服务器将拒绝启动。
MCP_HTTP_INSECURE_STATIC_AUTH	设置为 1，以明确允许在非 loopback 地址上无密钥启动（以私有网络作为安全边界）。名称已经说明了其作用。

export MCP_TRANSPORT=http
export MCP_HTTP_HOST=0.0.0.0
export BOOND_HTTP_STATIC_AUTH=true
export MCP_HTTP_API_KEY="$(openssl rand -hex 32)"
export BOOND_USER_TOKEN=… BOOND_CLIENT_TOKEN=… BOOND_CLIENT_KEY=…
npx boondmanager-mcp-server
# côté client : Authorization: Bearer <MCP_HTTP_API_KEY>

/healthz 仍可在无需密钥的情况下访问。在 OAuth 模式（默认）下，MCP_HTTP_API_KEY 会被忽略，并显示警告：此处的 Bearer 是 BoondManager 令牌。

自定义 URL（适用于专用实例）

export BOOND_BASE_URL="https://votre-instance.boondmanager.com/api"

默认 URL 为 https://ui.boondmanager.com/api。

HTTP 超时

每个 BoondManager API 请求默认在 30 秒后超时。对于响应较慢的租户或大型报告，可通过以下方式调高超时时间：

export BOOND_HTTP_TIMEOUT_MS=60000   # 60 s

如果请求超时，服务器会返回一条明确提及 BOOND_HTTP_TIMEOUT_MS 的错误，而不会无限期阻塞。

瞬时故障时重试

HTTP 客户端会使用指数退避 + 抖动，自动重试瞬时错误：

• GET：遇到 5xx、429、网络错误（ECONNRESET 等）和超时错误时重试（GET 操作为幂等操作）。
• POST / PUT / PATCH / DELETE：仅在遇到 429 时重试，以避免在服务器端重复写入。5xx 和网络错误会立即向上抛出。
• Retry-After 标头（以秒或 HTTP-date 表示）会被遵循，且延迟上限为 BOOND_HTTP_RETRY_MAX_MS。

变量	默认值	描述
BOOND_HTTP_MAX_RETRIES	2	最多额外重试次数（总计尝试 3 次）。0 表示完全禁用重试。
BOOND_HTTP_RETRY_BASE_MS	200	指数退避的基础延迟（base * 2^attempt，并加入抖动）。
BOOND_HTTP_RETRY_MAX_MS	5000	两次尝试之间的最大延迟。

速率限制（rate limiting）

为避免工具循环失控，向 API 发送过多请求（并连续触发 429），客户端会在本地应用 token bucket。默认值：持续速率 10 req/s，突发容量 20——正常交互使用时不会造成影响。重试也会消耗令牌。

变量	默认值	描述
BOOND_HTTP_RATE_LIMIT_RPS	10	持续速率（请求/秒）。0 表示完全禁用。
BOOND_HTTP_RATE_LIMIT_BURST	20	bucket 容量 = 可立即处理的最大突发请求数。

在 HTTP OAuth 传输中，bucket 按用户划分（身份根据 Bearer 推导）：一个用户的突发请求不会拖慢其他用户。在 stdio 和静态身份验证模式下，只有一个身份，因此也只有一个 bucket——限制按身份而非进程计算。

字典缓存

BoondManager API 只公开一个 endpoint /application/dictionary，用于返回所有标签（状态、类型、国家等）。服务会在内存中缓存这些数据，以避免每次将状态／类型解析为标签时都重新下载。

变量	默认值	说明
BOOND_DICTIONARY_TTL_MS	3600000（1 小时）	字典缓存的有效期，单位为毫秒。非数字或 ≤ 0 的值会回退为默认值。

上传本地文档

boond_documents_create 支持三种来源，每次调用只能选择一种：

来源	传输方式	启用方式	限制
fileUrl	所有方式	始终启用	—（BoondManager 会下载该 URL）
filePath	仅 stdio	BOOND_MCP_UPLOAD_DIRS	BOOND_MCP_UPLOAD_MAX_BYTES（20 MB）
fileContent（base64）+ fileName	所有方式	始终启用	2 MB

变量	默认值	说明
BOOND_MCP_UPLOAD_DIRS	(无)	允许上传文件所在的目录（绝对路径，CSV）。未设置时，filePath 会被禁用。
BOOND_MCP_UPLOAD_MAX_BYTES	20971520	本地文件的最大大小，单位为字节。

export BOOND_MCP_UPLOAD_DIRS="$HOME/Documents/Boond,$HOME/Downloads"

安全措施：必须使用绝对路径；解析符号链接后会验证路径是否仍在允许范围内（拒绝 .. 和指向范围外的符号链接）；只允许常规文件；根据文件头字节而非扩展名确定类型（PDF、DOCX/XLSX/PPTX、ODT/ODS、DOC/XLS/PPT、RTF、PNG、JPEG、GIF、WebP）。仅允许指定专用目录：其中任何符合条件的文件都可能按模型的要求发送至 BoondManager。

对话附件上传中继（SharePoint）

拖入对话的附件位于客户端的代码执行环境（沙盒）中，而不在服务器主机上：filePath 无法读取它，模型也无法可靠地将其转录为 base64。中继会让文件绕过模型输出进行传输：

1. boond_documents_upload_slot({ fileName }) 在专用 SharePoint 库中创建一个中转文件夹和一个经过预身份验证的 Microsoft Graph 上传会话（15 分钟、单个文件、单次使用）；
2. 沙盒通过一次 PUT 请求上传文件（使用 curl，命令会提供）；
3. boond_documents_create({ parentType, parentId, uploadSlot }) 验证文件（大小、起始字节），通过 fileUrl 机制将其临时 Graph 读取 URL 传给 BoondManager，然后将文件永久删除（使用 permanentDelete，不进入回收站；如果租户拒绝，则改为普通删除）。过期的上传槽会在下次启动时清理。

Entra ID 凭据保留在服务器端；客户端只能看到限定为单个文件的 URL。

变量	默认值	描述
BOOND_MCP_UPLOAD_RELAY	（无）	设置为 sharepoint 以启用中继。未设置时，boond_documents_upload_slot 会被拒绝。
BOOND_MCP_SHAREPOINT_TENANT_ID	—	Entra ID 目录（租户）ID。
BOOND_MCP_SHAREPOINT_CLIENT_ID	—	Entra ID 应用注册的应用程序 ID。
BOOND_MCP_SHAREPOINT_CLIENT_SECRET	—	客户端密钥（过期前需续期）。
BOOND_MCP_SHAREPOINT_SITE	—	中转站点：https://<tenant>.sharepoint.com/sites/<site>。
BOOND_MCP_SHAREPOINT_LIBRARY	Documents	中转库名称。

以最小权限进行设置：

• 一个专用的 SharePoint 站点和库，仅向所有者开放，不纳入搜索和离线同步，也不应用 Purview 保留策略（否则已删除的文件仍会保留）；
• 创建一个 Entra ID 应用注册（单租户），授予 Microsoft Graph 应用权限 Sites.Selected 并取得管理员同意，然后仅在此站点上授予 write 角色：

Connect-MgGraph -Scopes "Sites.FullControl.All"
$site = Get-MgSite -SiteId "<tenant>.sharepoint.com:/sites/<site>"
New-MgSitePermission -SiteId $site.Id -BodyParameter @{
  roles = @("write")
  grantedToIdentities = @(@{ application = @{ id = "<client-id>"; displayName = "boond-mcp-relay" } })
}

• 在客户端，将 <tenant>.sharepoint.com 加入代码执行环境的网络白名单。

需接受的权衡：BoondManager 收到的读取 URL 在有效期较短的时间内（几分钟，由 Microsoft 设定）经过预身份验证；该 URL 无法预测，并且文件会在 BoondManager 获取后立即删除。

访问限制（配置文件 / 域 / 只读）

您可以完全通过环境变量限制 AI 可以看到和执行的操作：仅开放特定域（例如会计），和/或阻止写入与删除操作。

变量	效果
BOOND_MCP_PROFILE	预配置配置文件：recruiting、sales、finance、delivery、admin（CSV = 并集）。无需手动列出域的快捷方式。若定义了 BOOND_MCP_DOMAINS，则忽略此变量。
BOOND_MCP_DOMAINS	域白名单（CSV）。未设置 = 全部。示例：invoices,payments,application
BOOND_MCP_EXCLUDE_DOMAINS	域黑名单（CSV），在白名单之后应用。示例：candidates,resources
BOOND_MCP_OPERATIONS	允许的操作（CSV），可选 read,create,update,delete。未设置 = 全部。
BOOND_MCP_READ_ONLY	快捷方式：true 等同于 BOOND_MCP_OPERATIONS=read（完全只读）。

⚠️ 这不是一道坚固的安全边界。 此筛选器会对 AI 隐藏工具，但不会更改所用 BoondManager 账户的权限。若要实现真正的隔离，请先配置 BoondManager 账户/角色权限（只读、会计范围……）；此筛选器作为补充（节省令牌、防止意外操作）。

示例 — 管理范围内的所有内容，均为只读：

export BOOND_MCP_PROFILE=finance
export BOOND_MCP_READ_ONLY=true

完整指南、解析规则、各配置文件的内容（以及由此产生的工具数量）：docs/access-control.md。

图标（SEP-973）

工具、提示词和资源都带有按域划分的图标（内嵌 SVG，使用 data: URI，无需托管任何资源文件）。实测开销：约 40 KiB，即 tools/list 负载的约 14 %。不显示图标的部署环境（网关、文本客户端）可以将其移除：

变量	默认值	描述
BOOND_MCP_ICONS	已启用	0/false/no/off：不公布任何图标（工具、提示词、资源）。

自定义字典标签

如果您的 BoondManager 实例使用自定义字典标签（例如英文的操作类型或状态），您可以通过 BOOND_DICTIONARY_OVERRIDES 声明标签→ID 映射（内联 JSON 或 JSON 文件路径）：

export BOOND_DICTIONARY_OVERRIDES='{"action":{"contact":{"Call":61,"Email":63}},"state":{"candidate":{"Interviewed":2}}}'

服务器随后会将这些标签用于 boond_actions_create 的 typeOf 和创建/修改操作的 state 字段，自动将其解析为数字 ID，并使用可用标签补充工具描述。若未设置此变量，行为完全不变。

完整格式、支持的实体和限制：docs/dictionary-overrides.md。

传输方式

服务器支持两种 MCP 传输方式，可通过环境变量 MCP_TRANSPORT 选择。

传输方式	值	使用场景
stdio（默认）	stdio 或未定义	Claude Desktop、Claude Code、本地集成
Streamable HTTP	http（别名：streamable-http）	MCP 网关、远程部署、容器

Streamable HTTP（适用于 MCP 网关）

自 v1.4.0 起，服务器可以通过 HTTP（MCP Streamable HTTP 传输方式）公开，以便接入 MCP 网关或作为服务部署。协商使用的协议修订版本与已安装的 SDK 一致（2025-11-25）。

BoondManager 身份验证：受 OAuth2 保护的资源。 HTTP 服务器不持有任何密钥（既无 client_secret，也无 refresh token 或用户存储）。每个 MCP 请求都必须携带 Authorization: Bearer <boond_access_token>；服务器会将令牌原样传递给 BoondManager。负责与 BoondManager 执行 OAuth 流程并管理 refresh 的是 MCP 客户端（Claude Desktop、Claude Code、网关……）。完整步骤：docs/oauth.md。

export MCP_TRANSPORT=http
export MCP_HTTP_HOST=0.0.0.0        # defaut: 127.0.0.1
export MCP_HTTP_PORT=3000           # defaut: 3000
export MCP_HTTP_PATH=/mcp           # defaut: /mcp
# Optionnel: requis uniquement derriere un reverse proxy, pour que
# la discovery annonce la bonne URL publique.
export MCP_HTTP_PUBLIC_URL=https://mcp.votre-domaine.com/mcp

npx boondmanager-mcp-server
# 🚀 BoondManager MCP Server running (streamable HTTP transport)
# 📡 Endpoint: http://0.0.0.0:3000/mcp
# 🔑 Mode: stateless
# 🔐 Boond auth: OAuth2 (per-request Bearer from MCP client)

HTTP 环境变量

变量	默认值	描述
MCP_TRANSPORT	stdio	使用 http 启用 HTTP 传输
MCP_HTTP_HOST	127.0.0.1	监听接口（使用 0.0.0.0 可对外开放）
MCP_HTTP_PORT	3000	TCP 端口
MCP_HTTP_PATH	/mcp	MCP 端点的 HTTP 路径
MCP_HTTP_STATEFUL	false	使用 true 启用有状态模式（会话 Mcp-Session-Id）
MCP_HTTP_JSON_RESPONSE	false	使用 true 强制返回 JSON 响应（不使用 SSE）
MCP_HTTP_PUBLIC_URL	(推导)	在 OAuth2 发现文档（resource）和 WWW-Authenticate challenge 中公布的公共 URL。通过反向代理部署时必需。
MCP_HTTP_SESSION_TTL_MS	1800000（30 分钟）	在有状态模式下，会话因不活动而关闭前的时长。
MCP_HTTP_SESSION_SWEEP_INTERVAL_MS	300000（5 分钟）	扫描不活动会话的频率。
MCP_HTTP_ALLOWED_HOSTS	(自动)	Host 标头的允许列表（防 DNS 重绑定，CVE-2025-66414）。使用 * 可明确禁用。
MCP_HTTP_ALLOWED_ORIGINS	(自动)	浏览器客户端的 Origin 标头（scheme + host + port）允许列表；列表之外的 Origin 会收到 403（2025-11-25 规范要求）。服务器监听 loopback 时的默认值 = 所有 loopback 来源，不限端口（localhost / 127.0.0.1 / [::1] 上的 http/https），以及 MCP_HTTP_PUBLIC_URL（若已定义）对应的来源 — MCP Inspector（:6274）或开发服务器（:5173）无需配置即可运行，远程来源始终会收到 403。否则禁用验证。显式列表则会进行精确匹配（包括端口）。不带 Origin 的请求始终会被接受（curl、网关、非浏览器 MCP 客户端），发现文档 /.well-known/oauth-protected-resource 也不受限制。使用 * 可明确禁用；空值不表示禁用。
MCP_HTTP_VALIDATE_TOKEN	false	OAuth 模式：处理请求之前，向 BoondManager 验证每个 Bearer（GET /application/current-user，按 token 缓存，缓存时长由 MCP_HTTP_TOKEN_VALIDATION_TTL_MS 决定，默认 60 秒）。过期或已撤销的 token 会收到 401 + WWW-Authenticate: … error="invalid_token"，符合规范的 MCP 客户端会据此重新授权 — 不启用此选项时，401 只会出现在工具调用结果中，因此没有客户端会重新发起 OAuth。BoondManager 无法连接 → 放行请求（fail open）。

OAuth2 环境变量 — 发现（均为可选）

变量	默认值	描述
BOOND_OAUTH_AUTHORIZATION_SERVER	https://ui.boondmanager.com	BoondManager 授权服务器的 Issuer，在 authorization_servers 中公布
BOOND_OAUTH_SCOPES	(空)	在 scopes_supported 中公布的 Scopes（用空格或逗号分隔）。为空 = 客户端直接与 Boond 协商。

无状态（默认）：每个 HTTP POST 请求彼此独立，非常适合复用多个 MCP 服务的网关。服务器端不会保留任何会话。

有状态：服务器在初始化时生成 Mcp-Session-Id，客户端必须在每个后续请求中将其发回。适用于可从 SSE 流式传输和服务器通知中获益的原生 MCP 客户端。

示例：发现 + 401 challenge

# Public, pas d'auth -> documente OU envoyer le user pour autoriser
curl -s http://localhost:3000/.well-known/oauth-protected-resource | jq .
# {
#   "resource": "http://0.0.0.0:3000/mcp",
#   "authorization_servers": ["https://ui.boondmanager.com"],
#   "bearer_methods_supported": ["header"]
# }

# Appel MCP sans token -> 401 + WWW-Authenticate qui pointe vers la discovery
curl -s -o /dev/null -w "%{http_code}\n%header{www-authenticate}\n" \
  -X POST http://localhost:3000/mcp -d '{}'
# 401
# Bearer realm="http://0.0.0.0:3000/mcp", resource_metadata="http://0.0.0.0:3000/.well-known/oauth-protected-resource/mcp"

示例：通过 HTTP 使用 Claude Code

使用符合 MCP Authorization 2025-06-18 规范的 MCP 客户端时，OAuth 发现会自动进行：

claude mcp add --transport http boondmanager https://mcp.votre-domaine.com/mcp
# Le client recoit le 401 + WWW-Authenticate, fetch la metadata, ouvre
# le navigateur pour autoriser l'App BoondManager, puis re-emet la requete
# avec le Bearer token recu.

示例：Docker（官方镜像）

每次发布时，都会在两个镜像仓库发布一个开箱即用的 Docker 镜像，支持多架构（linux/amd64 + linux/arm64）：

镜像仓库	镜像	页面
GitHub Container Registry	ghcr.io/silamir/boondmanager-mcp-server	github.com/silamir/boondmanager-mcp-server/pkgs/container/boondmanager-mcp-server
Docker Hub	docker.io/fauguste/boondmanager-mcp-server	hub.docker.com/r/fauguste/boondmanager-mcp-server

摘要相同，标签相同——请选择与您的工具链相匹配的镜像仓库。镜像默认通过 HTTP 传输，在端口 3000 和 0.0.0.0 接口上启动。无需挂载卷，也无需存储密钥——该服务在设计上是无状态的。

# Via GHCR (authentification GitHub si registre prive)
docker run -d --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -e MCP_HTTP_PUBLIC_URL=https://mcp.votre-domaine.com/mcp \
  --name boondmanager-mcp \
  ghcr.io/silamir/boondmanager-mcp-server:latest

# Ou via Docker Hub (anonyme)
docker run -d --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -e MCP_HTTP_PUBLIC_URL=https://mcp.votre-domaine.com/mcp \
  --name boondmanager-mcp \
  fauguste/boondmanager-mcp-server:latest

两个镜像仓库均提供以下标签：每个稳定版本对应 :latest、:X、:X.Y、:X.Y.Z（建议在生产环境中使用确切版本）。预发布版本（例如 :2.0.0-alpha）仅使用固定标签发布——:latest、:X 和 :X.Y 均不会更新。支持的环境变量请参见配置和传输方式。

示例：docker-compose

仓库内附有开箱即用的 docker-compose.yml：仅包含一个无状态服务，无需挂载卷，也无需在服务端存储密钥。

# Optionnel : surcharger MCP_HTTP_PUBLIC_URL si fronted par un reverse proxy
cp .env.example .env

docker compose up -d
docker compose logs -f mcp

安全性：HTTP 服务是无状态的，不会存储任何 BoondManager 密钥。每位用户都使用自己的 OAuth2 令牌（由其自己的 BoondManager 应用签发）对服务进行身份验证，所有操作都会在 Boond 审计日志中归属到该用户。若部署在反向代理之后：请终止 TLS（HTTPS），转发 Authorization 请求头，并将 MCP_HTTP_PUBLIC_URL 设置为公网 URL，以确保服务发现正常。

非 Claude 远程客户端（ChatGPT、OpenAI / Gemini Agents SDK）

MCP 是一种与模型无关的协议：任何兼容 MCP 的宿主都可以直接使用相同的 HTTP/OAuth2 端点，而不仅限于 Claude。无需特定于大模型的程序包或构建——只需将宿主指向您的 MCP_HTTP_PUBLIC_URL 即可。

宿主	如何连接服务
ChatGPT（连接器 / Developer mode）	添加一个指向 HTTP URL 的远程 MCP 连接器；系统会通过元数据 /.well-known/oauth-protected-resource 发现 OAuth2。
OpenAI Agents SDK	声明一个 HostedMCPTool / 远程 MCP 服务，并提供 HTTP URL 和 OAuth2 流程。
Google Gemini（Agents SDK / Vertex）	在 SDK 端注册远程 MCP 服务；本地使用时，Gemini CLI 扩展（见安装）可支持 stdio 传输。

其约定与 Claude Code 使用 HTTP 时相同（参见上文的 claude mcp add --transport http 示例）：唯一不同的是在客户端声明服务的方式。

使用示例

配置完成后，您可以向 Claude 提问：

CRM 与商务

• "搜索在巴黎具备 React 技能的候选人"
• "显示资源 #12345 的技术详情"
• "为 Acme Corp 创建新联系人 Jean Dupont"
• "列出所有进行中的商机"
• "商机 #20 的定位是什么？"

项目管理

• "为公司 #42 创建项目 Mission Alpha"
• "显示项目 #33 的计划"
• "项目 #55 有哪些采购订单？"
• "显示项目 #12 的生产力"

开票与财务

• "搜索待付款发票"
• "列出公司 #100 的供应商发票"
• "显示项目 #55 的采购"

人力资源与工时

• "显示资源 #100 在 2025 年 3 月的工时表"
• "列出本月计划的休假"
• "显示资源 #200 的费用报销单"
• "资源 #50 有哪些福利？"

活动跟踪

• "候选人 #789 最近有哪些活动？"
• "显示待处理的审批"
• "列出我的待办任务"

报告

• "显示全局汇总报告"
• "资源生产力报告是什么？"

管理

• "获取活动类型词典"
• "列出办事处和业务部门"
• "显示已配置的 Webhook"

架构

boondmanager-mcp-server/
├── src/
│   ├── index.ts              # Point d'entree MCP (selection du transport)
│   ├── server.ts             # Factory createMcpServer() + liste des domaines
│   ├── constants.ts          # Configuration, API paths, onglets
│   ├── types.ts              # Types TypeScript (JSON:API)
│   ├── transports/
│   │   └── http.ts           # Transport Streamable HTTP (gateway/remote)
│   ├── services/
│   │   └── boond-client.ts   # Client HTTP API BoondManager
│   ├── schemas/
│   │   └── index.ts          # Schemas Zod (validation des entrees)
│   └── tools/
│       ├── index.ts          # Barrel export de tous les domaines
│       ├── crud-factory.ts   # Factory generique CRUD (DRY)
│       ├── candidates.ts     # 10 outils (CRUD + 5 onglets)
│       ├── resources.ts      # 20 outils (CRUD + 10 onglets + references/timesheets)
│       ├── contacts.ts       # 11 outils (CRUD + 6 onglets)
│       ├── companies.ts      # 14 outils (CRUD + 9 onglets)
│       ├── opportunities.ts  # 10 outils (CRUD + 5 onglets)
│       ├── projects.ts       # 12 outils (CRUD + 7 onglets)
│       ├── actions.ts        # 5 outils
│       ├── timesheets.ts     # 3 outils
│       ├── invoices.ts       # 5 outils
│       ├── orders.ts         # 5 outils
│       ├── deliveries.ts     # 2 outils
│       ├── absences.ts       # 5 outils
│       ├── expenses.ts       # 5 outils
│       ├── products.ts       # 5 outils
│       ├── positionings.ts   # 4 outils
│       ├── payments.ts       # 2 outils
│       ├── advantages.ts     # 2 outils
│       ├── contracts.ts      # 2 outils
│       ├── purchases.ts      # 4 outils
│       ├── provider-invoices.ts # 2 outils
│       ├── accounts.ts       # 2 outils
│       ├── agencies.ts       # 2 outils
│       ├── business-units.ts # 2 outils
│       ├── poles.ts          # 2 outils
│       ├── roles.ts          # 2 outils
│       ├── calendars.ts      # 2 outils
│       ├── flags.ts          # 2 outils
│       ├── webhooks.ts       # 2 outils
│       ├── logs.ts           # 2 outils
│       ├── notifications.ts  # 2 outils
│       ├── threads.ts        # 2 outils
│       ├── todolists.ts      # 2 outils
│       ├── validations.ts    # 2 outils
│       ├── reporting.ts      # 5 outils
│       ├── planning-absences.ts # 1 outil
│       └── application.ts    # 2 outils
├── dist/                     # Build JavaScript
├── .github/                  # CI/CD, templates, Dependabot
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── eslint.config.js
└── README.md

故障排除

*_search 工具出现「JSON Schema declares an unsupported dialect (draft-07)」

症状。 搜索工具（boond_candidates_search、boond_resources_search、 boond_opportunities_search 等）始终失败，而详情工具 （boond_*_get）、词典和文本工作流均可正常运行。这种差异就是诊断依据：只有声明了 outputSchema 的约 59 个工具受到影响，因为宿主会编译这个 schema——在注册工具时，也就是任何调用发生之前。工具并非调用失败，而是变得无法使用。

原因。 版本 2.1.0 至 2.12.1 会在其 schema 上声明 "$schema": "http://json-schema.org/draft-07/schema#" （MCP SDK 会使用 target: 'draft-7' 将 Zod schema 转换为 draft-07，且该设置是硬编码的）。仅使用 2020-12 验证器进行验证的宿主会拒绝编译此类 schema。

修复方法：升级到 >= 2.12.2。 从此版本开始，服务不再声明任何方言（src/schema-dialect.ts）；测试套件会使用真实客户端，在 2020-12 和 draft-07 验证器下验证全部 185 个工具。

仅重启连接器并不足够：重启会重新运行已安装的二进制文件，不会更新它。请检查实际加载的版本，而不是目录中显示的版本：

# npm / npx : quelle version est resolue et depuis quel cache
npm view boondmanager-mcp-server version
npx --yes boondmanager-mcp-server@latest --version 2>/dev/null || true

# Le serveur annonce sa version dans la reponse `initialize` (champ serverInfo.version),
# lue depuis son propre package.json -- c'est la seule source fiable.

根据安装渠道：

渠道	更新
Claude Desktop 扩展（.mcpb）	下载最新发行版的 .mcpb 并重新安装——第三方扩展不会自动更新
Claude Code 插件	运行 /plugin marketplace update boondmanager，然后重新安装插件（启动时会固定使用 [email protected]）
claude mcp add / 手动配置	在 npx 命令中固定使用 boondmanager-mcp-server@latest（或 >= 2.12.2 的版本）
Docker / GHCR	运行 docker pull ghcr.io/silamir/boondmanager-mcp-server:latest

还请检查 Node 版本：服务要求 Node.js >= 22。仍在使用 Node 20 的电脑通常很久没有刷新过安装了。

安全性

• BoondManager 凭据（JWT 或 BasicAuth）绝不会通过 MCP 协议传输——它们仅在服务器端通过环境变量配置
• 在 stdio 模式下，服务器在本地运行，不会暴露任何网络端口
• 在 streamable HTTP 模式下，身份验证采用 OAuth2 受保护资源：每个 MCP 请求都携带自己的 Authorization: Bearer <token>（服务器不会存储任何密钥）。请通过反向代理终止 TLS（使用 HTTPS），转发 Authorization 标头，将 MCP_HTTP_PUBLIC_URL 设置为公共 URL，并通过 MCP_HTTP_ALLOWED_HOSTS 启用 DNS 重绑定防护。另请限制对网关的网络访问。参见 docs/oauth.md。
• 符合 ISO 27001 要求
• BoondManager API 托管在法国，并符合 GDPR
• BoondManager 身份验证：JWT（推荐）、BasicAuth，或根据组件自动构建 JWT

开发

# Mode watch pour le developpement
npm run dev

# Build
npm run build

# Lancer le serveur
npm start

# Tests
npm test               # 645 tests
npm run test:coverage  # Avec couverture

# Qualite
npm run lint
npm run typecheck

技术栈

• 运行时：Node.js >= 22 (ES2022)
• 语言：TypeScript 5.8+（严格模式）
• MCP SDK：@modelcontextprotocol/sdk 1.12+
• 验证：Zod 4
• 测试：Vitest 4 + V8 覆盖率
• Lint：ESLint 10 + typescript-eslint
• 传输方式：stdio（默认）+ Streamable HTTP（MCP 2025-11-25 规范）

资源

• BoondManager API 文档
• BoondManager Postman 集合
• MCP 规范
• pyboondmanager（Python 参考实现）
• 自动生成的工具目录（TOOLS.md）
• 分发与市场（docs/distribution.md）

许可证

Apache License 2.0 — 版权所有 (c) 2025-2026 Silamir。 最初由 Frédéric Auguste 创建。

详情请参见 LICENSE 和 NOTICE。

BoondManager 是 BoondManager SAS 的商标。本项目是一个独立且非官方的 BoondManager 公共 API 客户端，与 BoondManager SAS 无关联。