使用说明
BoondManager MCP服务器
模型上下文协议（MCP）服务器，提供与BoondManager API的无缝集成，使Claude等人工智能助手能够在BoondManager实例中搜索、检索、创建和更新记录。
特性
- API全面覆盖：8个业务领域的121个工具
- 完整的CRUD操作：搜索、读取、创建和更新记录
- 类型安全：使用TypeScript和Zod验证构建
- Claude桌面集成：使用Claude for Desktop轻松设置
- 错误处理：全面的错误处理和有用的消息
文档
- docs/SETUP.md -详细的安装和配置指南
- docs/AI_SKILLS.md -如何为您的AI助手安装Boond MCP技能
- docs/AI_GUIDE.md -完整的AI助理入职指南（MCP配置、技能、验证）
- docs/DISTRIBUTION.md -向团队分发服务器的指南
- docs/AGENTS.md -开发工作流程和最佳实践
- docs/API_STABILITY.md文件 -API稳定性和版本控制保证
- docs/LTS_POLICY.md -长期支持（LTS）政策
先决条件
- Node.js 18+或 包子
- 具有API访问权限的BoondManager帐户
- 您的BoondManager API代币
安装
🤖 AI助理
如果您是给定此仓库URL的AI助手，阅读 docs/AI_GUIDE.md --它具备全面运行所需的一切：
- 配置MCP服务器（远程HTTP或本地stdio）
- 从安装技能
docs/skills/boond-mcp.md - 使用3个测试提示验证安装
- 安全检查表
快速技能安装：
mkdir -p ~/.opencode/skills && cp docs/skills/boond-mcp.md ~/.opencode/skills/boond-mcp.md
看 docs/AI_SKILLS.md 因为这项技能教给了我们什么。
npm（推荐）
# Install globally
npm install -g @imarinmed/boond-mcp
# Note: Package will be available on npm registry shortly.
码头工人
docker run --rm -p 3000:3000 \
-e BOOND_API_TOKEN=your_token \
-e MCP_API_KEY=your_mcp_api_key_here \
boond-mcp:1.0.0
默认情况下，容器以HTTP模式运行MCP服务器：
GET /health-健康检查POST /mcp/http-无状态JSON-RPC端点GET /mcp-SSE端点
手册（来源）
# Clone the repository
git clone https://github.com/imarinmed/boond-mcp.git
cd boond-mcp
# Install dependencies
bun install
# Build the project
bun run build
# Set up environment variables
cp .env.example .env
# Edit .env and add your BOOND_API_TOKEN
配置
环境变量
创建一个 .env 项目根目录中的文件：
# Boond API authentication (choose one mode)
# 1) Legacy token mode:
BOOND_API_TOKEN=your_api_token_here
# 2) X-Jwt-Client mode:
# BOOND_CLIENT_TOKEN=your_client_token_here
# BOOND_CLIENT_KEY=your_client_key_here
# BOOND_USER_TOKEN=your_user_token_here
# BOOND_JWT_MODE=normal
MCP_API_KEY=<set_a_secure_client_key>
# 3) Transport mode (optional - defaults to stdio)
# TRANSPORT_TYPE=http # Enable HTTP/SSE server mode
# PORT=3000 # HTTP server port (default: 3000)
### 📛 Server Key: `boond-mcp`
> **Why `boond-mcp` and not `boondmanager`?**
>
> - **BoondManager** — the vendor SaaS product (API at `ui.boondmanager.com`)
> - **`boond-mcp`** — this MCP server's canonical identifier (package name, CLI binary, and `mcpServers` key)
> - **`boondmanager`** — legacy alias seen in configs created before v1.2; both work, but **new configs should use `boond-mcp`**
>
> If you see `"boondmanager"` in an existing config, rename the key to `"boond-mcp"` for consistency.
### Claude Desktop Setup
Add the following to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"boond-mcp": {
"command": "node",
"args": ["/absolute/path/to/boond-mcp/build/index.js"],
"env": {
"BOOND_API_TOKEN": "your_api_token_here",
"MCP_API_KEY": "your_mcp_client_api_key_here"
}
}
}
}
备注：确保使用构建的index.js文件的绝对路径。
开放代码设置
对于 开放代码 或支持到远程MCP服务器的HTTP/SSE连接的其他MCP客户端：
环境变量
添加到您的shell配置文件(~/.zshrc, ~/.bashrc，或 ~/.bash_profile):
export BOOND_MCP_URL="https://your-mcp-server-url.com/mcp"
export BOOND_MCP_API_KEY="<your-api-key>"
然后重新加载您的个人资料：
source ~/.zshrc # or ~/.bashrc
配置文件
或者，创建/编辑 ~/.opencode/config.json:
{
"mcpServers": {
"boond-mcp": {
"url": "https://your-mcp-server-url.com/mcp",
"headers": {
"x-api-key": "your_mcp_api_key_here"
}
}
}
}
备注：当使用HTTP模式时，MCP服务器内部处理Boond API身份验证。你只需要 x-api-key 用于与MCP服务器本身进行身份验证的标头。
运输方式
BoondManager MCP服务器支持三种传输模式：
1.标准模式（默认）
最佳：Claude Desktop，本地MCP客户端
# No TRANSPORT_TYPE needed (defaults to stdio)
BOOND_API_TOKEN=your_token node build/index.js
服务器通过stdin/stdout进行通信，非常适合桌面应用程序。
2.带SSE的HTTP模式（有状态）
最佳：远程MCP服务器，实时更新
TRANSPORT_TYPE=http PORT=3000 MCP_API_KEY=secret node build/index.js
终点：
GET /mcp-SSE连接端点（需要会话管理）POST /mcp?sessionId=xxx-发送JSON-RPC消息GET /health-健康检查
使用流程：
- 建立SSE连接：
GET /mcp→ 接收sessionId - 发送消息：
POST /mcp?sessionId=xxx使用JSON-RPC - 通过SSE流接收响应
注： SSE需要保持持久连接。会话在连接关闭时过期。
3.HTTP模式无状态（新增！）
最佳：OpenCode，简单的HTTP客户端，测试
TRANSPORT_TYPE=http PORT=3000 MCP_API_KEY=secret node build/index.js
端点：
POST /mcp/http-无状态JSON-RPC端点
例子：
curl -X POST http://localhost:3000/mcp/http \
-H "Content-Type: application/json" \
-H "x-api-key: secret" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "boond_candidates_search",
"arguments": {"limit": 5}
}
}'
优点：
- ✅ 无需会话管理
- ✅ 简单的请求/响应模式
- ✅ 适用于任何HTTP客户端
- ✅ 与OpenCode远程MCP兼容
选择交通工具
| 传输 | 会话 | 复杂性 | 最适合 |
|---|---|---|---|
| 标准 | N/A | 低 | 克劳德桌面，本地工具 |
| 上海证券交易所 | 必需 | 中等 | 实时应用程序，长期连接 |
| HTTP无状态 | 无 | 低 | 快速脚本、测试、OpenCode |
可用工具（共121个）
可用工具（共121个）
人力资源领域（16个工具）
管理候选人、联系人、资源和合同。
候选人
boond_candidates_search-使用可选筛选器搜索候选人- 参数：
query,page,limit,status
- 参数：
boond_candidates_get-通过ID获取候选人- 参数：
id
- 参数：
boond_candidates_create-创建新候选人- 参数：
firstName,lastName,email,phone,address,city,country
- 参数：
boond_candidates_update-更新现有候选人- 参数：
id，加上要更新的任何字段
- 参数：
联系人
boond_contacts_search-搜索联系人- 参数：
query,page,limit,companyId
- 参数：
boond_contacts_get-通过ID获取联系人- 参数：
id
- 参数：
boond_contacts_create-创建新联系人- 参数：
firstName,lastName,email,companyId,phone,title
- 参数：
boond_contacts_update-更新现有联系人- 参数：
id，加上要更新的任何字段
- 参数：
资源
boond_resources_search-搜索资源- 参数：
query,page,limit,status
- 参数：
boond_resources_get-按ID获取资源- 参数：
id
- 参数：
boond_resources_create-创建新资源- 参数：
firstName,lastName,email,type,startDate
- 参数：
boond_resources_update-更新现有资源- 参数：
id，加上要更新的任何字段
- 参数：
合同
boond_contracts_search-搜索合同- 参数：
query,page,limit,status
- 参数：
boond_contracts_get-通过ID获取合同- 参数：
id
- 参数：
boond_contracts_create-创建新合同- 参数：
resourceId,startDate,endDate,type,salary
- 参数：
boond_contracts_update-更新现有合同- 参数：
id，加上要更新的任何字段
- 参数：
CRM领域（15个工具）
管理公司、机会和报价。
公司
boond_companies_search-搜索公司- 参数：
query,page,limit,type
- 参数：
boond_companies_get-通过ID获取公司- 参数：
id
- 参数：
boond_companies_create-创建新公司- 参数：
name,type,address,city,country,phone,email
- 参数：
boond_companies_update-更新现有公司- 参数：
id，加上要更新的任何字段
- 参数：
机会
boond_opportunities_search-寻找机会- 参数：
query,page,limit,status,companyId
- 参数：
boond_opportunities_get-通过ID获得机会- 参数：
id
- 参数：
boond_opportunities_create-创造新机会- 参数：
title,companyId,value,currency,probability,expectedCloseDate
- 参数：
boond_opportunities_update-更新现有商机- 参数：
id，加上要更新的任何字段
- 参数：
引文
boond_quotations_search-搜索报价- 参数：
query,page,limit,status,opportunityId
- 参数：
boond_quotations_get-按ID获取报价- 参数：
id
- 参数：
boond_quotations_create-创建新报价- 参数：
opportunityId,title,total,currency,validUntil
- 参数：
boond_quotations_update-更新现有报价- 参数：
id，加上要更新的任何字段
- 参数：
boond_quotations_send-向客户发送报价- 参数：
id,email,message
- 参数：
金融领域（16种工具）
管理发票、采购、订单和银行业务。
发票
boond_invoices_search-搜索发票- 参数：
query,page,limit,status,dateFrom,dateTo
- 参数：
boond_invoices_get-按ID获取发票- 参数：
id
- 参数：
boond_invoices_create-创建新发票- 参数：
companyId,projectId,amount,currency,dueDate
- 参数：
boond_invoices_update-更新现有发票- 参数：
id，加上要更新的任何字段
- 参数：
采购
boond_purchases_search-搜索购买- 参数：
query,page,limit,status,dateFrom,dateTo
- 参数：
boond_purchases_get-按ID购买- 参数：
id
- 参数：
boond_purchases_create-创建新购买- 参数：
supplierId,amount,currency,description,date
- 参数：
boond_purchases_update-更新现有购买- 参数：
id，加上要更新的任何字段
- 参数：
订单
boond_orders_search-搜索订单- 参数：
query,page,limit,status,dateFrom,dateTo
- 参数：
boond_orders_get-按ID获取订单- 参数：
id
- 参数：
boond_orders_create-创建新订单- 参数：
companyId,projectId,amount,currency,description
- 参数：
boond_orders_update-更新现有订单- 参数：
id，加上要更新的任何字段
- 参数：
银行业
boond_banking_accounts_search-搜索银行账户- 参数：
query,page,limit
- 参数：
boond_banking_accounts_get-通过ID获取银行账户- 参数：
id
- 参数：
boond_banking_transactions_search-搜索银行交易- 参数：
accountId,dateFrom,dateTo,page,limit
- 参数：
项目领域（13个工具）
管理项目、交付和行动。
项目
boond_projects_search-搜索项目- 参数：
query,page,limit,status,companyId
- 参数：
boond_projects_get-按ID获取项目- 参数：
id
- 参数：
交付
boond_deliveries_search-搜索配送- 参数：
query,page,limit,projectId,status
- 参数：
boond_deliveries_get-通过ID获取配送- 参数：
id
- 参数：
boond_deliveries_create-创建新交付- 参数：
projectId,name,description,dueDate
- 参数：
boond_deliveries_update-更新现有交付- 参数：
id，加上要更新的任何字段
- 参数：
boond_deliveries_send-发送交货通知- 参数：
id,email,message
- 参数：
行动
boond_actions_search-搜索操作- 参数：
query,page,limit,projectId,status,assignedTo
- 参数：
boond_actions_get-按ID获取操作- 参数：
id
- 参数：
boond_actions_create-创建新操作- 参数：
projectId,name,description,assignedTo,dueDate,priority
- 参数：
boond_actions_update-更新现有操作- 参数：
id，加上要更新的任何字段
- 参数：
boond_actions_delete-删除操作- 参数：
id
- 参数：
时域（16种工具）
管理时间报告、缺勤和费用。
时间报告
boond_timereports_search-搜索时间报告- 参数：
resourceId,startDate,endDate,status,page,limit
- 参数：
boond_timereports_get-按ID获取时间报告- 参数：
id
- 参数：
boond_timereports_create-创建新的时间报告- 参数：
resourceId,date,hours,projectId,description
- 参数：
缺勤
boond_absences_search-搜索缺席情况- 参数：
resourceId,startDate,endDate,type,status,page,limit
- 参数：
boond_absences_get-通过ID获取缺勤信息- 参数：
id
- 参数：
boond_absences_create-创建新的缺勤- 参数：
resourceId,startDate,endDate,type,reason
- 参数：
boond_absences_update-更新现有缺勤情况- 参数：
id，加上要更新的任何字段
- 参数：
开支
boond_expenses_search-搜索费用报告- 参数：
resourceId,startDate,endDate,status,page,limit
- 参数：
boond_expenses_get-按ID获取费用报告- 参数：
id
- 参数：
boond_expenses_create-创建新的支出报告- 参数：
resourceId,date,amount,currency,category,description
- 参数：
boond_expenses_update-更新现有的支出报告- 参数：
id，加上要更新的任何字段
- 参数：
boond_expenses_certify-证明费用报告- 参数：
id
- 参数：
boond_expenses_reject-拒绝费用报告- 参数：
id,reason
- 参数：
管理域（12个工具）
管理机构、业务部门和账户。
机构
boond_agencies_search-搜索代理商- 参数：
query,page,limit
- 参数：
boond_agencies_get-通过ID获取代理- 参数：
id
- 参数：
boond_agencies_create-创建新机构- 参数：
name,address,city,country,phone,email
- 参数：
boond_agencies_update-更新现有机构- 参数：
id，加上要更新的任何字段
- 参数：
业务单元
boond_businessunits_search-搜索业务部门- 参数：
query,page,limit
- 参数：
boond_businessunits_get-按ID获取业务部门- 参数：
id
- 参数：
boond_businessunits_create-创建新的业务部门- 参数：
name,code,description,managerId
- 参数：
boond_businessunits_update-更新现有业务部门- 参数：
id，加上要更新的任何字段
- 参数：
账户
boond_accounts_search-搜索帐户- 参数：
query,page,limit
- 参数：
boond_accounts_get-通过ID获取帐户- 参数：
id
- 参数：
boond_accounts_create-创建新帐户- 参数：
name,type,number,currency,balance
- 参数：
boond_accounts_update-更新现有帐户- 参数：
id，加上要更新的任何字段
- 参数：
文档域（4个工具）
管理文件和档案。
boond_documents_search-搜索文档- 参数：
query,page,limit,folderId
- 参数：
boond_documents_get-按ID获取文档- 参数：
id
- 参数：
boond_documents_update-更新文档元数据- 参数：
id,name,folderId
- 参数：
boond_documents_download-获取文档下载URL- 参数：
id
- 参数：
系统域（10个工具）
管理应用程序、设置和警报。
应用
boond_apps_search-搜索应用程序- 参数：
query,page,limit,type
- 参数：
boond_apps_get-按ID获取应用程序- 参数：
id
- 参数：
boond_apps_install-安装应用程序- 参数：
id
- 参数：
boond_apps_uninstall-卸载应用程序- 参数：
id
- 参数：
设置
boond_settings_search-搜索设置- 参数：
query,page,limit,category
- 参数：
boond_settings_get-按ID获取设置- 参数：
id
- 参数：
boond_settings_update-更新设置- 参数：
id,value,category
- 参数：
警报
boond_alerts_search-搜索警报- 参数：
query,page,limit,status,severity
- 参数：
boond_alerts_get-按ID获取警报- 参数：
id
- 参数：
boond_alerts_update-更新警报（解决）- 参数：
id,status,resolution
- 参数：
使用示例
使用克劳德桌面
配置后，您可以要求Claude：
人力资源管理：
"Find candidates with React experience in Paris"
"Create a new contact for John Doe at Acme Corp"
"Get resource details for employee ID 12345"
"Update contract end date for resource 67890"
CRM运营：
"Search for all client companies"
"Create a new opportunity worth €50,000 for Company XYZ"
"Send quotation ID 12345 to the client"
"Get all active opportunities for Q1"
财务管理：
"Search for unpaid invoices from last month"
"Create a new purchase order for €5,000"
"Get banking transaction history for account 12345"
"Update invoice status to paid for ID 67890"
项目管理：
"Show me all active projects"
"Create a new delivery milestone for Project ABC"
"Assign action item to John for Project XYZ"
"Get project details including all deliveries"
时间和费用：
"Create a time report for resource 123 on project 456 for 8 hours today"
"Search time reports for resource 123 from January 1st to January 31st"
"Submit expense report for €150 in travel costs"
"Certify expense report ID 789"
管理：
"Search for all agencies"
"Create a new business unit called 'Sales Team'"
"Get account balance for account ID 12345"
"Update agency address for Paris office"
文件管理：
"Search for documents in folder 'Contracts'"
"Get download URL for document ID 12345"
"Update document name to 'Updated Contract v2'"
系统配置：
"Search for email notification settings"
"Install the Gmail integration app"
"Get all active alerts"
"Resolve alert ID 12345"
直接MCP协议
您还可以使用MCP协议直接与服务器交互：
# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node build/index.js
# Search candidates
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"boond_candidates_search","arguments":{"query":"developer","limit":5}}}' | node build/index.js
# Get company by ID
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"boond_companies_get","arguments":{"id":"12345"}}}' | node build/index.js
# Create time report
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"boond_timereports_create","arguments":{"resourceId":"123","date":"2024-01-15","hours":8,"projectId":"456","description":"Worked on feature X"}}}' | node build/index.js
发展
# Build the project
bun run build
# Watch mode for development
bun run dev
# Run the server
bun start
# Type check
bunx tsc --noEmit
# Count registered tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | BOOND_API_TOKEN=test bun run src/index.ts 2>/dev/null | jq '.result.tools | length'
项目结构
boond-mcp/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── api/
│ │ ├── client.ts # BoondManager API client
│ │ └── index.ts # API exports
│ ├── tools/
│ │ ├── index.ts # Main tool exports
│ │ ├── hr/ # HR domain tools
│ │ │ ├── candidates.ts
│ │ │ ├── contacts.ts
│ │ │ ├── resources.ts
│ │ │ ├── contracts.ts
│ │ │ └── index.ts
│ │ ├── crm/ # CRM domain tools
│ │ │ ├── companies.ts
│ │ │ ├── opportunities.ts
│ │ │ ├── quotations.ts
│ │ │ └── index.ts
│ │ ├── finance/ # Finance domain tools
│ │ │ ├── invoices.ts
│ │ │ ├── purchases.ts
│ │ │ ├── orders.ts
│ │ │ ├── banking.ts
│ │ │ └── index.ts
│ │ ├── projects/ # Projects domain tools
│ │ │ ├── projects.ts
│ │ │ ├── deliveries.ts
│ │ │ ├── actions.ts
│ │ │ └── index.ts
│ │ ├── time/ # Time domain tools
│ │ │ ├── timeReports.ts
│ │ │ ├── absences.ts
│ │ │ ├── expenses.ts
│ │ │ └── index.ts
│ │ ├── admin/ # Admin domain tools
│ │ │ ├── agencies.ts
│ │ │ ├── businessUnits.ts
│ │ │ ├── accounts.ts
│ │ │ └── index.ts
│ │ ├── documents/ # Documents domain tools
│ │ │ ├── documents.ts
│ │ │ └── index.ts
│ │ └── system/ # System domain tools
│ │ ├── apps.ts
│ │ ├── settings.ts
│ │ ├── alerts.ts
│ │ └── index.ts
│ └── types/
│ ├── boond.ts # BoondManager API types
│ ├── mcp.ts # MCP-specific types
│ ├── schemas.ts # Zod validation schemas
│ └── index.ts # Type exports
├── build/ # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
故障排除
“未设置BOUND_API_TOKEN环境变量”
确保您已设置 BOOND_API_TOKEN 环境变量在您的 .env 文件或Claude Desktop配置中。
“身份验证失败”或401错误
- 验证您的API令牌是否正确
- 检查令牌是否具有必要的权限
- 确保您的BoondManager实例URL正确（默认值：https://ui.boondmanager.com)
“找不到资源”或404错误
- 验证您使用的ID是否存在于BoondManager实例中
- 检查您是否有访问该资源的权限
“验证错误”或422个错误
- 检查是否提供了所有必需的参数
- 验证参数类型（例如，日期应采用ISO格式）
- 确保枚举值与允许的选项匹配
服务器无法启动
- 确保你已经跑过了
bun run build编译TypeScript - 检查是否安装了所有依赖项(
bun install) - 验证Node.js版本是否为18或更高
- 检查一下
BOOND_API_TOKEN已设置
未找到工具
如果出现“未找到工具”错误：
- 验证工具名称是否正确（检查拼写）
- 确保添加新工具后已重建服务器
- 检查工具是否在中正确注册
src/index.ts
API 参考
此MCP服务器包装BoondManager API。有关API的详细文档，请访问： https://doc.boondmanager.com/api-externe/
许可证
麻省理工学院
贡献
欢迎投稿！请随时提交拉取请求。
更新日志
v1.0.0（2026-02-08）
- 稳定的生产发布
- 完成了8个领域的121个工具
- 添加了Docker支持和安装指南
- 全面的安全审计和稳定性保证
- 通过以下方式改进了CLI诊断
boond-mcp doctor
v0.2.0（2026-02-03）
- 从12个工具扩展到94个工具
- 新增8个基于域的工具组织
- 新领域：人力资源、客户关系管理、财务、项目、时间、行政、文档、系统
- 跨所有域的完整CRUD操作
- 全面的文件
v0.1.0（2026-01-15）
- 初始版本包含12个工具
- 候选人、公司、项目、时间报告的基本CRUD
