mcp-bamboohr 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CLAUDE.md +309 -0
- package/LICENSE +21 -0
- package/README.md +143 -0
- package/build/__tests__/bambooClient.debug.test.d.ts +2 -0
- package/build/__tests__/bambooClient.debug.test.d.ts.map +1 -0
- package/build/__tests__/bambooClient.debug.test.js +128 -0
- package/build/__tests__/bambooClient.debug.test.js.map +1 -0
- package/build/__tests__/bambooClient.test.d.ts +2 -0
- package/build/__tests__/bambooClient.test.d.ts.map +1 -0
- package/build/__tests__/bambooClient.test.js +188 -0
- package/build/__tests__/bambooClient.test.js.map +1 -0
- package/build/__tests__/config.test.d.ts +1 -0
- package/build/__tests__/config.test.d.ts.map +1 -0
- package/build/__tests__/config.test.js +87 -0
- package/build/__tests__/config.test.js.map +1 -0
- package/build/__tests__/setup.d.ts +2 -0
- package/build/__tests__/setup.d.ts.map +1 -0
- package/build/__tests__/setup.js +16 -0
- package/build/__tests__/setup.js.map +1 -0
- package/build/__tests__/tools/employees.test.d.ts +2 -0
- package/build/__tests__/tools/employees.test.d.ts.map +1 -0
- package/build/__tests__/tools/employees.test.js +282 -0
- package/build/__tests__/tools/employees.test.js.map +1 -0
- package/build/__tests__/tools/meta.test.d.ts +2 -0
- package/build/__tests__/tools/meta.test.d.ts.map +1 -0
- package/build/__tests__/tools/meta.test.js +141 -0
- package/build/__tests__/tools/meta.test.js.map +1 -0
- package/build/__tests__/tools/timeOff.test.d.ts +2 -0
- package/build/__tests__/tools/timeOff.test.d.ts.map +1 -0
- package/build/__tests__/tools/timeOff.test.js +224 -0
- package/build/__tests__/tools/timeOff.test.js.map +1 -0
- package/build/bambooClient.d.ts +13 -0
- package/build/bambooClient.d.ts.map +1 -0
- package/build/bambooClient.js +111 -0
- package/build/bambooClient.js.map +1 -0
- package/build/config.d.ts +8 -0
- package/build/config.d.ts.map +1 -0
- package/build/config.js +22 -0
- package/build/config.js.map +1 -0
- package/build/index.d.ts +2 -0
- package/build/index.d.ts.map +1 -0
- package/build/index.js +69 -0
- package/build/index.js.map +1 -0
- package/build/tools/employees.d.ts +122 -0
- package/build/tools/employees.d.ts.map +1 -0
- package/build/tools/employees.js +150 -0
- package/build/tools/employees.js.map +1 -0
- package/build/tools/meta.d.ts +87 -0
- package/build/tools/meta.d.ts.map +1 -0
- package/build/tools/meta.js +126 -0
- package/build/tools/meta.js.map +1 -0
- package/build/tools/timeOff.d.ts +122 -0
- package/build/tools/timeOff.d.ts.map +1 -0
- package/build/tools/timeOff.js +155 -0
- package/build/tools/timeOff.js.map +1 -0
- package/build/types.d.ts +170 -0
- package/build/types.d.ts.map +1 -0
- package/build/types.js +3 -0
- package/build/types.js.map +1 -0
- package/coverage/base.css +224 -0
- package/coverage/block-navigation.js +87 -0
- package/coverage/favicon.png +0 -0
- package/coverage/index.html +131 -0
- package/coverage/lcov-report/base.css +224 -0
- package/coverage/lcov-report/block-navigation.js +87 -0
- package/coverage/lcov-report/favicon.png +0 -0
- package/coverage/lcov-report/index.html +131 -0
- package/coverage/lcov-report/prettify.css +1 -0
- package/coverage/lcov-report/prettify.js +2 -0
- package/coverage/lcov-report/sort-arrow-sprite.png +0 -0
- package/coverage/lcov-report/sorter.js +210 -0
- package/coverage/lcov.info +322 -0
- package/coverage/prettify.css +1 -0
- package/coverage/prettify.js +2 -0
- package/coverage/sort-arrow-sprite.png +0 -0
- package/coverage/sorter.js +210 -0
- package/package.json +83 -0
package/CLAUDE.md
ADDED
|
@@ -0,0 +1,309 @@
|
|
|
1
|
+
# BambooHR MCP Server
|
|
2
|
+
|
|
3
|
+
A Model Context Protocol (MCP) server that provides AI assistants with access to BambooHR's API. This server exposes 10 essential BambooHR operations as MCP tools, enabling seamless integration of HR data into AI workflows.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
The server provides access to these BambooHR capabilities:
|
|
8
|
+
|
|
9
|
+
### Employee Management
|
|
10
|
+
- **Get Employee Data**: Retrieve detailed employee information with customizable field selection
|
|
11
|
+
- **Get Employee Photo**: Download employee photos in various sizes
|
|
12
|
+
- **Get Employee Directory**: Access the company-wide employee directory
|
|
13
|
+
- **Get Employee Goals**: Retrieve performance goals and objectives
|
|
14
|
+
|
|
15
|
+
### Time Off Management
|
|
16
|
+
- **Estimate Time Off Balance**: Calculate future time off balances for employees
|
|
17
|
+
- **Get Time Off Requests**: Retrieve and filter time off requests
|
|
18
|
+
- **Get Who's Out**: View upcoming time off and holidays
|
|
19
|
+
|
|
20
|
+
### Company Resources
|
|
21
|
+
- **List Company Files**: Browse available company files and categories
|
|
22
|
+
- **Get Company File**: Download specific company documents
|
|
23
|
+
- **Get Meta Fields**: Discover available data fields
|
|
24
|
+
|
|
25
|
+
## Installation
|
|
26
|
+
|
|
27
|
+
### NPM Installation (Recommended)
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm install -g mcp-bamboohr
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
### From Source
|
|
34
|
+
|
|
35
|
+
1. Clone the repository
|
|
36
|
+
2. Install dependencies: `npm install`
|
|
37
|
+
3. Build: `npm run build`
|
|
38
|
+
4. Run: `npm start`
|
|
39
|
+
|
|
40
|
+
## Setup
|
|
41
|
+
|
|
42
|
+
### 1. Get BambooHR API Credentials
|
|
43
|
+
|
|
44
|
+
1. Log into your BambooHR account as an administrator
|
|
45
|
+
2. Go to Settings → API Keys
|
|
46
|
+
3. Generate a new API key
|
|
47
|
+
4. Note your company subdomain (the part before `.bamboohr.com` in your BambooHR URL)
|
|
48
|
+
|
|
49
|
+
### 2. Configure Claude Desktop
|
|
50
|
+
|
|
51
|
+
Add the server to your Claude Desktop configuration with your credentials:
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"mcpServers": {
|
|
56
|
+
"bamboohr": {
|
|
57
|
+
"command": "npx",
|
|
58
|
+
"args": ["mcp-bamboohr"],
|
|
59
|
+
"env": {
|
|
60
|
+
"BAMBOO_API_TOKEN": "your_actual_api_token",
|
|
61
|
+
"BAMBOO_COMPANY_DOMAIN": "your_company_subdomain"
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Usage
|
|
69
|
+
|
|
70
|
+
### MCP Client Configuration
|
|
71
|
+
|
|
72
|
+
Add this server to your MCP client configuration:
|
|
73
|
+
|
|
74
|
+
**For Claude Desktop (recommended):**
|
|
75
|
+
```json
|
|
76
|
+
{
|
|
77
|
+
"mcpServers": {
|
|
78
|
+
"bamboohr": {
|
|
79
|
+
"command": "npx",
|
|
80
|
+
"args": ["mcp-bamboohr"],
|
|
81
|
+
"env": {
|
|
82
|
+
"BAMBOO_API_TOKEN": "your_api_key",
|
|
83
|
+
"BAMBOO_COMPANY_DOMAIN": "your_company"
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
**For local development:**
|
|
91
|
+
```json
|
|
92
|
+
{
|
|
93
|
+
"mcpServers": {
|
|
94
|
+
"bamboohr": {
|
|
95
|
+
"command": "node",
|
|
96
|
+
"args": ["build/index.js"],
|
|
97
|
+
"cwd": "/path/to/mcp-bamboohr",
|
|
98
|
+
"env": {
|
|
99
|
+
"BAMBOO_API_TOKEN": "your_api_key",
|
|
100
|
+
"BAMBOO_COMPANY_DOMAIN": "your_company"
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Available Tools
|
|
108
|
+
|
|
109
|
+
#### Employee Tools
|
|
110
|
+
|
|
111
|
+
**`get-employee`**
|
|
112
|
+
```
|
|
113
|
+
Get employee data by ID with customizable field selection
|
|
114
|
+
Parameters:
|
|
115
|
+
- id: Employee ID (use "0" for current user)
|
|
116
|
+
- fields: Comma-separated field names (e.g., "firstName,lastName,email,jobTitle")
|
|
117
|
+
- onlyCurrent: Boolean, return only current values (default: true)
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
**`get-employee-photo`**
|
|
121
|
+
```
|
|
122
|
+
Download employee photos
|
|
123
|
+
Parameters:
|
|
124
|
+
- employeeId: The employee ID
|
|
125
|
+
- size: Photo size (original, large, medium, small, xs, tiny)
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
**`get-employee-directory`**
|
|
129
|
+
```
|
|
130
|
+
Get the company employee directory
|
|
131
|
+
Parameters: None
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
**`get-employee-goals`**
|
|
135
|
+
```
|
|
136
|
+
Retrieve employee performance goals
|
|
137
|
+
Parameters:
|
|
138
|
+
- employeeId: The employee ID
|
|
139
|
+
- filter: Goal status filter (open, closed, all)
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
#### Time Off Tools
|
|
143
|
+
|
|
144
|
+
**`estimate-time-off-balance`**
|
|
145
|
+
```
|
|
146
|
+
Calculate future time off balances
|
|
147
|
+
Parameters:
|
|
148
|
+
- employeeId: The employee ID
|
|
149
|
+
- date: Future date in YYYY-MM-DD format (optional)
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
**`get-time-off-requests`**
|
|
153
|
+
```
|
|
154
|
+
Retrieve time off requests with filtering options
|
|
155
|
+
Parameters (all optional):
|
|
156
|
+
- id: Specific request ID
|
|
157
|
+
- action: Access level (view, approve)
|
|
158
|
+
- employeeId: Filter by employee
|
|
159
|
+
- start/end: Date range (YYYY-MM-DD)
|
|
160
|
+
- status: Request status
|
|
161
|
+
- type: Time off type ID
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
**`get-whos-out`**
|
|
165
|
+
```
|
|
166
|
+
View who's out for a date range
|
|
167
|
+
Parameters:
|
|
168
|
+
- start: Start date (YYYY-MM-DD, defaults to today)
|
|
169
|
+
- end: End date (YYYY-MM-DD, defaults to 14 days from start)
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
#### Company/Meta Tools
|
|
173
|
+
|
|
174
|
+
**`list-company-files`**
|
|
175
|
+
```
|
|
176
|
+
List all company files and categories
|
|
177
|
+
Parameters: None
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
**`get-company-file`**
|
|
181
|
+
```
|
|
182
|
+
Download a specific company file
|
|
183
|
+
Parameters:
|
|
184
|
+
- fileId: The file ID to retrieve
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
**`get-meta-fields`**
|
|
188
|
+
```
|
|
189
|
+
Get all available fields in your BambooHR account
|
|
190
|
+
Parameters: None
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
## Example Usage
|
|
195
|
+
|
|
196
|
+
```javascript
|
|
197
|
+
// Get employee information
|
|
198
|
+
await callTool("get-employee", {
|
|
199
|
+
id: "123",
|
|
200
|
+
fields: "firstName,lastName,email,jobTitle,department,hireDate"
|
|
201
|
+
});
|
|
202
|
+
|
|
203
|
+
// Check who's out this week
|
|
204
|
+
await callTool("get-whos-out", {
|
|
205
|
+
start: "2024-01-15",
|
|
206
|
+
end: "2024-01-21"
|
|
207
|
+
});
|
|
208
|
+
|
|
209
|
+
// Get time off requests for approval
|
|
210
|
+
await callTool("get-time-off-requests", {
|
|
211
|
+
action: "approve",
|
|
212
|
+
status: "requested"
|
|
213
|
+
});
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
## Security Considerations
|
|
217
|
+
|
|
218
|
+
- **API Token Security**: Store your API token securely and never commit it to version control
|
|
219
|
+
- **Environment Variables**: Use the `.env` file for configuration, which is excluded from git
|
|
220
|
+
- **Access Permissions**: The server respects BambooHR's permission system - users can only access data they have rights to see
|
|
221
|
+
- **Rate Limiting**: The server includes built-in request timeout and error handling
|
|
222
|
+
|
|
223
|
+
## Error Handling
|
|
224
|
+
|
|
225
|
+
The server provides detailed error messages for common issues:
|
|
226
|
+
|
|
227
|
+
- **401 Unauthorized**: Invalid API token
|
|
228
|
+
- **403 Forbidden**: Insufficient permissions
|
|
229
|
+
- **404 Not Found**: Resource doesn't exist
|
|
230
|
+
- **429 Rate Limited**: Too many requests
|
|
231
|
+
- **Network Errors**: Connection timeouts or failures
|
|
232
|
+
|
|
233
|
+
## Testing
|
|
234
|
+
|
|
235
|
+
Run the comprehensive test suite:
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
# Run all tests
|
|
239
|
+
npm test
|
|
240
|
+
|
|
241
|
+
# Run tests in watch mode
|
|
242
|
+
npm run test:watch
|
|
243
|
+
|
|
244
|
+
# Generate coverage report
|
|
245
|
+
npm run test:coverage
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
## Development
|
|
249
|
+
|
|
250
|
+
### Project Structure
|
|
251
|
+
|
|
252
|
+
```
|
|
253
|
+
src/
|
|
254
|
+
├── index.ts # MCP server setup and tool registration
|
|
255
|
+
├── config.ts # Environment configuration
|
|
256
|
+
├── bambooClient.ts # BambooHR API client with authentication
|
|
257
|
+
├── types.ts # TypeScript type definitions
|
|
258
|
+
├── tools/ # Individual tool implementations
|
|
259
|
+
│ ├── employees.ts # Employee-related tools
|
|
260
|
+
│ ├── timeOff.ts # Time off management tools
|
|
261
|
+
│ └── meta.ts # Meta/company tools
|
|
262
|
+
└── __tests__/ # Test files
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
### Adding New Tools
|
|
266
|
+
|
|
267
|
+
1. Define the endpoint in the appropriate tool file
|
|
268
|
+
2. Create Zod schema for input validation
|
|
269
|
+
3. Implement the tool function with error handling
|
|
270
|
+
4. Register the tool in `index.ts`
|
|
271
|
+
5. Add comprehensive tests
|
|
272
|
+
|
|
273
|
+
## Troubleshooting
|
|
274
|
+
|
|
275
|
+
### Common Issues
|
|
276
|
+
|
|
277
|
+
**"Authentication failed"**
|
|
278
|
+
- Verify your API token is correct
|
|
279
|
+
- Ensure your company domain is the subdomain only (not the full URL)
|
|
280
|
+
|
|
281
|
+
**"Access forbidden"**
|
|
282
|
+
- Check that your BambooHR user has API access enabled
|
|
283
|
+
- Verify permissions for the specific resource you're accessing
|
|
284
|
+
|
|
285
|
+
**"Resource not found"**
|
|
286
|
+
- Confirm the employee ID, file ID, or other resource exists
|
|
287
|
+
- Check that you have permission to access the resource
|
|
288
|
+
|
|
289
|
+
**Network timeouts**
|
|
290
|
+
- The server includes a 30-second timeout for API calls
|
|
291
|
+
- Check your internet connection and BambooHR service status
|
|
292
|
+
|
|
293
|
+
### Debug Mode
|
|
294
|
+
|
|
295
|
+
Enable debug logging by setting `DEBUG=true` in your `.env` file. This will log all API requests and responses.
|
|
296
|
+
|
|
297
|
+
## API Reference
|
|
298
|
+
|
|
299
|
+
This server uses BambooHR's v1 REST API. For detailed API documentation, refer to:
|
|
300
|
+
https://documentation.bamboohr.com/reference
|
|
301
|
+
|
|
302
|
+
## Support
|
|
303
|
+
|
|
304
|
+
- Review the test files for usage examples
|
|
305
|
+
- Ensure your BambooHR plan includes API access
|
|
306
|
+
|
|
307
|
+
## License
|
|
308
|
+
|
|
309
|
+
MIT License - see LICENSE file for details.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Evrim Alacan
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# BambooHR MCP Server
|
|
2
|
+
|
|
3
|
+
[](https://badge.fury.io/js/mcp-bamboohr)
|
|
4
|
+
[](https://github.com/evrimalacan/mcp-bamboohr)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
|
|
7
|
+
A **Model Context Protocol (MCP)** server that seamlessly connects AI assistants to BambooHR's API. Access employee data, time off information, company files, and more through natural language queries in Claude and other AI assistants.
|
|
8
|
+
|
|
9
|
+
## 🚀 Quick Start
|
|
10
|
+
|
|
11
|
+
### Get Your BambooHR Credentials
|
|
12
|
+
|
|
13
|
+
1. Log into your BambooHR account
|
|
14
|
+
2. Click your name in the lower left-hand corner of any page
|
|
15
|
+
3. Select **API Keys** from the user context menu (if you have sufficient permissions)
|
|
16
|
+
4. Generate a new API key
|
|
17
|
+
5. Note your company subdomain (the part before `.bamboohr.com`)
|
|
18
|
+
|
|
19
|
+
### Configuration
|
|
20
|
+
|
|
21
|
+
Add the server to your Claude Desktop configuration:
|
|
22
|
+
|
|
23
|
+
```json
|
|
24
|
+
{
|
|
25
|
+
"mcpServers": {
|
|
26
|
+
"bamboohr": {
|
|
27
|
+
"command": "npx",
|
|
28
|
+
"args": ["mcp-bamboohr"],
|
|
29
|
+
"type": "stdio",
|
|
30
|
+
"env": {
|
|
31
|
+
"BAMBOO_API_TOKEN": "your_actual_api_token",
|
|
32
|
+
"BAMBOO_COMPANY_DOMAIN": "your_company_subdomain"
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
## ✨ Features
|
|
41
|
+
|
|
42
|
+
- 🧑💼 **Employee Management** - Get employee data, photos, directory, and performance goals
|
|
43
|
+
- 🏖️ **Time Off Management** - Check balances, requests, and who's out
|
|
44
|
+
- 📁 **Company Resources** - Access files, documents, and metadata
|
|
45
|
+
- 🔒 **Token Authentication** - Uses BambooHR's API with token authentication
|
|
46
|
+
- 🎯 **Type Safety** - Full TypeScript support with type definitions
|
|
47
|
+
- ✅ **100% Test Coverage** - 71 tests covering all code
|
|
48
|
+
- 🛡️ **Error Handling** - Proper error handling and timeouts
|
|
49
|
+
- 📚 **Documentation** - Setup guides and examples
|
|
50
|
+
|
|
51
|
+
## 🛠️ Available Tools
|
|
52
|
+
|
|
53
|
+
The server provides **10 MCP tools** covering essential BambooHR operations:
|
|
54
|
+
|
|
55
|
+
### Employee Management
|
|
56
|
+
- `get-employee` - Retrieve detailed employee information with customizable fields
|
|
57
|
+
- `get-employee-photo` - Download employee photos in various sizes
|
|
58
|
+
- `get-employee-directory` - Access the complete company directory
|
|
59
|
+
- `get-employee-goals` - View performance goals and objectives
|
|
60
|
+
|
|
61
|
+
### Time Off Management
|
|
62
|
+
- `estimate-time-off-balance` - Calculate future time off balances
|
|
63
|
+
- `get-time-off-requests` - Retrieve and filter time off requests
|
|
64
|
+
- `get-whos-out` - View upcoming time off and holidays
|
|
65
|
+
|
|
66
|
+
### Company Resources
|
|
67
|
+
- `list-company-files` - Browse available company files and categories
|
|
68
|
+
- `get-company-file` - Download specific company documents
|
|
69
|
+
- `get-meta-fields` - Discover all available BambooHR data fields
|
|
70
|
+
|
|
71
|
+
## 💡 Example Queries
|
|
72
|
+
|
|
73
|
+
- *"Show me John Smith's employee information"*
|
|
74
|
+
- *"Who's out of office next week?"*
|
|
75
|
+
- *"What are the pending time off requests that need approval?"*
|
|
76
|
+
- *"Download the employee handbook from company files"*
|
|
77
|
+
- *"What are Sarah's current performance goals?"*
|
|
78
|
+
- *"How much vacation time will I have by year-end?"*
|
|
79
|
+
|
|
80
|
+
## 🏗️ Development
|
|
81
|
+
|
|
82
|
+
### From Source
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
# Clone and setup
|
|
86
|
+
git clone https://github.com/evrimalacan/mcp-bamboohr.git
|
|
87
|
+
cd mcp-bamboohr
|
|
88
|
+
npm install
|
|
89
|
+
|
|
90
|
+
# Build
|
|
91
|
+
npm run build
|
|
92
|
+
|
|
93
|
+
# Run tests (71 comprehensive tests with 100% coverage)
|
|
94
|
+
npm test
|
|
95
|
+
|
|
96
|
+
# Development mode
|
|
97
|
+
npm run dev
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## 🐛 Troubleshooting
|
|
101
|
+
|
|
102
|
+
### Common Issues
|
|
103
|
+
|
|
104
|
+
**"Authentication failed"**
|
|
105
|
+
- Verify your API token is correct
|
|
106
|
+
- Ensure company domain is just the subdomain (not full URL)
|
|
107
|
+
|
|
108
|
+
**"Access forbidden"**
|
|
109
|
+
- Check your BambooHR user has API access enabled
|
|
110
|
+
- Verify permissions for the specific resource
|
|
111
|
+
|
|
112
|
+
**"Resource not found"**
|
|
113
|
+
- Confirm the employee ID or resource exists
|
|
114
|
+
- Check you have permission to access the resource
|
|
115
|
+
|
|
116
|
+
## 📚 Documentation
|
|
117
|
+
|
|
118
|
+
- **[Complete Usage Guide](CLAUDE.md)** - Detailed setup, configuration, and usage
|
|
119
|
+
- **[BambooHR API Documentation](https://documentation.bamboohr.com/reference)** - Official API reference
|
|
120
|
+
|
|
121
|
+
## 🤝 Contributing
|
|
122
|
+
|
|
123
|
+
1. Fork the repository
|
|
124
|
+
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
|
|
125
|
+
3. Add tests for your changes
|
|
126
|
+
4. Ensure all tests pass (`npm test`)
|
|
127
|
+
5. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
128
|
+
6. Push to the branch (`git push origin feature/amazing-feature`)
|
|
129
|
+
7. Open a Pull Request
|
|
130
|
+
|
|
131
|
+
## 📄 License
|
|
132
|
+
|
|
133
|
+
MIT License - see [LICENSE](LICENSE) file for details.
|
|
134
|
+
|
|
135
|
+
## 🌟 Support
|
|
136
|
+
|
|
137
|
+
- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/evrimalacan/mcp-bamboohr/issues)
|
|
138
|
+
- 💡 **Feature Requests**: [GitHub Discussions](https://github.com/evrimalacan/mcp-bamboohr/discussions)
|
|
139
|
+
- 📖 **Documentation**: See [CLAUDE.md](CLAUDE.md) for comprehensive guide
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
**Made with tons of ❤️**
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bambooClient.debug.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/bambooClient.debug.test.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
// Mock config for debug mode
|
|
2
|
+
jest.mock('../config', () => ({
|
|
3
|
+
bambooConfig: {
|
|
4
|
+
apiToken: 'test-token',
|
|
5
|
+
companyDomain: 'test-company',
|
|
6
|
+
baseUrl: 'https://test-company.bamboohr.com/api/v1',
|
|
7
|
+
debug: true // Enable debug mode
|
|
8
|
+
}
|
|
9
|
+
}));
|
|
10
|
+
// Mock console methods to test debug logging
|
|
11
|
+
const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
|
|
12
|
+
const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
|
|
13
|
+
// Mock axios
|
|
14
|
+
jest.mock('axios', () => ({
|
|
15
|
+
create: jest.fn(() => ({
|
|
16
|
+
get: jest.fn(),
|
|
17
|
+
post: jest.fn(),
|
|
18
|
+
put: jest.fn(),
|
|
19
|
+
delete: jest.fn(),
|
|
20
|
+
interceptors: {
|
|
21
|
+
request: { use: jest.fn() },
|
|
22
|
+
response: { use: jest.fn() }
|
|
23
|
+
}
|
|
24
|
+
}))
|
|
25
|
+
}));
|
|
26
|
+
import { BambooHRClient } from '../bambooClient';
|
|
27
|
+
describe('BambooClient Debug Mode', () => {
|
|
28
|
+
let client;
|
|
29
|
+
let mockAxiosInstance;
|
|
30
|
+
beforeEach(() => {
|
|
31
|
+
const axios = require('axios');
|
|
32
|
+
mockAxiosInstance = {
|
|
33
|
+
get: jest.fn(),
|
|
34
|
+
post: jest.fn(),
|
|
35
|
+
put: jest.fn(),
|
|
36
|
+
delete: jest.fn(),
|
|
37
|
+
interceptors: {
|
|
38
|
+
request: { use: jest.fn() },
|
|
39
|
+
response: { use: jest.fn() }
|
|
40
|
+
}
|
|
41
|
+
};
|
|
42
|
+
axios.create.mockReturnValue(mockAxiosInstance);
|
|
43
|
+
// Clear console spies before creating new client
|
|
44
|
+
consoleLogSpy.mockClear();
|
|
45
|
+
consoleErrorSpy.mockClear();
|
|
46
|
+
client = new BambooHRClient();
|
|
47
|
+
});
|
|
48
|
+
afterAll(() => {
|
|
49
|
+
consoleLogSpy.mockRestore();
|
|
50
|
+
consoleErrorSpy.mockRestore();
|
|
51
|
+
});
|
|
52
|
+
describe('debug mode interceptors', () => {
|
|
53
|
+
it('should set up request interceptor in debug mode', () => {
|
|
54
|
+
expect(mockAxiosInstance.interceptors.request.use).toHaveBeenCalledWith(expect.any(Function));
|
|
55
|
+
});
|
|
56
|
+
it('should set up response interceptor in debug mode', () => {
|
|
57
|
+
expect(mockAxiosInstance.interceptors.response.use).toHaveBeenCalledWith(expect.any(Function), expect.any(Function));
|
|
58
|
+
});
|
|
59
|
+
it('should log request details in debug mode', () => {
|
|
60
|
+
// Get the request interceptor function
|
|
61
|
+
const requestInterceptor = mockAxiosInstance.interceptors.request.use.mock.calls[0][0];
|
|
62
|
+
const mockConfig = {
|
|
63
|
+
method: 'GET',
|
|
64
|
+
url: '/test-endpoint',
|
|
65
|
+
params: { test: 'value' }
|
|
66
|
+
};
|
|
67
|
+
requestInterceptor(mockConfig);
|
|
68
|
+
expect(consoleLogSpy).toHaveBeenCalledWith('[BambooHR] GET /test-endpoint');
|
|
69
|
+
expect(consoleLogSpy).toHaveBeenCalledWith('[BambooHR] Params:', { test: 'value' });
|
|
70
|
+
});
|
|
71
|
+
it('should log request without params', () => {
|
|
72
|
+
const requestInterceptor = mockAxiosInstance.interceptors.request.use.mock.calls[0][0];
|
|
73
|
+
const mockConfig = {
|
|
74
|
+
method: 'POST',
|
|
75
|
+
url: '/another-endpoint'
|
|
76
|
+
// No params
|
|
77
|
+
};
|
|
78
|
+
requestInterceptor(mockConfig);
|
|
79
|
+
expect(consoleLogSpy).toHaveBeenCalledWith('[BambooHR] POST /another-endpoint');
|
|
80
|
+
// Should not log params line when no params
|
|
81
|
+
expect(consoleLogSpy).not.toHaveBeenCalledWith(expect.stringContaining('Params:'));
|
|
82
|
+
});
|
|
83
|
+
it('should log successful response in debug mode', () => {
|
|
84
|
+
// Get the success handler from response interceptor
|
|
85
|
+
const responseInterceptor = mockAxiosInstance.interceptors.response.use.mock.calls[0][0];
|
|
86
|
+
const mockResponse = {
|
|
87
|
+
status: 200,
|
|
88
|
+
config: { url: '/test-endpoint' }
|
|
89
|
+
};
|
|
90
|
+
responseInterceptor(mockResponse);
|
|
91
|
+
expect(consoleLogSpy).toHaveBeenCalledWith('[BambooHR] Response 200 from /test-endpoint');
|
|
92
|
+
});
|
|
93
|
+
it('should log error response in debug mode', async () => {
|
|
94
|
+
// Get the error handler from response interceptor
|
|
95
|
+
const errorInterceptor = mockAxiosInstance.interceptors.response.use.mock.calls[0][1];
|
|
96
|
+
const mockError = {
|
|
97
|
+
response: {
|
|
98
|
+
status: 404,
|
|
99
|
+
config: { url: '/not-found' }
|
|
100
|
+
},
|
|
101
|
+
message: undefined
|
|
102
|
+
};
|
|
103
|
+
// Should reject but we need to catch it
|
|
104
|
+
try {
|
|
105
|
+
await errorInterceptor(mockError);
|
|
106
|
+
}
|
|
107
|
+
catch (e) {
|
|
108
|
+
// Expected to throw
|
|
109
|
+
}
|
|
110
|
+
expect(consoleErrorSpy).toHaveBeenCalledWith('[BambooHR] Error 404 from undefined:', undefined);
|
|
111
|
+
});
|
|
112
|
+
it('should log network error in debug mode', async () => {
|
|
113
|
+
const errorInterceptor = mockAxiosInstance.interceptors.response.use.mock.calls[0][1];
|
|
114
|
+
const mockError = {
|
|
115
|
+
message: 'Network Error'
|
|
116
|
+
// No response object for network errors
|
|
117
|
+
};
|
|
118
|
+
try {
|
|
119
|
+
await errorInterceptor(mockError);
|
|
120
|
+
}
|
|
121
|
+
catch (e) {
|
|
122
|
+
// Expected to throw
|
|
123
|
+
}
|
|
124
|
+
expect(consoleErrorSpy).toHaveBeenCalledWith('[BambooHR] Error undefined from undefined:', 'Network Error');
|
|
125
|
+
});
|
|
126
|
+
});
|
|
127
|
+
});
|
|
128
|
+
//# sourceMappingURL=bambooClient.debug.test.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bambooClient.debug.test.js","sourceRoot":"","sources":["../../src/__tests__/bambooClient.debug.test.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bambooClient.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/bambooClient.test.ts"],"names":[],"mappings":""}
|