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=

# 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`

{ "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=""


然后重新加载您的个人资料：

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` -健康检查

**使用流程：**

1. 建立SSE连接： `GET /mcp` → 接收 `sessionId`
1. 发送消息： `POST /mcp?sessionId=xxx` 使用JSON-RPC
1. 通过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

Boond MCP

快速接入

详细介绍