内容
# MCP Sling 服务器
MCP（模型上下文协议）服务器，用于 Sling API - 一个全面的调度和管理工作平台。
> **快速入门：** 如果您是新用户，请参阅 [QUICK_START.md](./QUICK_START.md) 以获取 5 分钟的设置指南！
## 功能
此 MCP 服务器提供了与 Sling API 所有主要端点交互的工具：
### 日历和调度
- **获取日历** - 检索用户的日历和班次数据
- **创建班次** - 为员工创建新的班次
- **获取时间表** - 查看时间表数据和实际工作小时数
- **更新时间表** - 修改时间表条目
### 用户管理
- **获取用户** - 列出组织中的所有用户
- **创建用户** - 添加新用户
- **更新用户** - 修改用户信息
### 组织管理
- **获取组织** - 查看组织详细信息
- **按 ID 获取组织** - 获取特定的组织信息
- **切换组织** - 在组织之间切换
- **获取群组** - 列出组织群组
### 报告和分析
- **获取报告** - 访问各种报告（劳动力、调度、出勤）
- **创建销售记录** - 记录用于分析的销售数据
- **获取标签** - 检索用于分类的可用标签
### 设置
- **更新设置** - 修改组织或用户设置
### 高级
- **Sling API 调用** - 对任何 Sling 端点进行自定义 API 调用
## 安装
1. 克隆此仓库：
```bash
git clone <仓库 URL>
cd mcp-sling
```
2. 安装依赖项：
```bash
npm install
```
3. 构建项目：
```bash
npm run build
```
4. 获取您的 Sling 授权令牌：
**重要：** 由于 Sling 登录端点的验证码要求，您需要从浏览器中获取授权令牌。
请遵循详细指南： **[TOKEN_GUIDE.md](./TOKEN_GUIDE.md)**
5. 使用令牌创建 `.env` 文件：
```bash
cp .env.example .env
```
编辑 `.env` 并添加您的令牌：
```env
SLING_TOKEN=您的浏览器令牌
SLING_SERVER=api
```
## 配置
### 环境变量
**推荐方法（避免验证码）：**
- **SLING_TOKEN**（必需）- 来自浏览器的 Sling 授权令牌
- 请参阅 [TOKEN_GUIDE.md](./TOKEN_GUIDE.md) 获取说明
- **SLING_SERVER**（可选）- 要使用的 API 服务器（默认： "api"，使用 "test-api" 进行测试）
**替代方法（需要验证码 - 不推荐）：**
- **SLING_EMAIL** - 您的 Sling 账户电子邮件
- **SLING_PASSWORD** - 您的 Sling 账户密码
- 注意：由于 `/account/login` 端点的验证码要求，目前无法正常工作
### Claude 桌面配置
将以下内容添加到您的 Claude 桌面配置文件中：
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
**推荐：使用令牌**
```json
{
"mcpServers": {
"sling": {
"command": "node",
"args": ["/绝对路径/to/mcp-sling/dist/index.js"],
"env": {
"SLING_TOKEN": "您的浏览器令牌"
}
}
}
}
```
**替代：使用 .env 文件**
```json
{
"mcpServers": {
"sling": {
"command": "node",
"args": ["/绝对路径/to/mcp-sling/dist/index.js"]
}
}
}
```
（需要配置 `.env` 文件）
## 使用示例
配置完成后，您可以通过 Claude 使用 Sling 工具。以下是一些示例查询：
### 获取所有用户
```
您可以获取我的 Sling 组织中所有用户的列表吗？
```
### 查看日历
```
请显示用户 ID 12345 在组织 67890 中 2024-01-15 的日历
```
### 创建班次
```
为用户 12345 创建一个班次，开始于 2024-01-20T09:00:00Z，结束于 2024-01-20T17:00:00Z，职位为“收银员”
```
### 获取报告
```
获取 2024-01-01 至 2024-01-31 期间的劳动力报告
```
### 自定义 API 调用
```
对 /custom/endpoint 发出 GET 请求，参数为 {"filter": "active"}
```
## 身份验证
此服务器使用您配置的凭证自动处理身份验证。身份验证流程：
1. 在第一次请求时，服务器使用您的电子邮件/密码登录 Sling
2. 身份验证令牌被缓存并在后续请求中重复使用
3. 如果令牌过期（401 错误），服务器会自动刷新它
4. 令牌通常有效期为 1 小时
注意：Sling API 使用电子邮件/密码身份验证，如其官方示例中所述。
### 关于验证码
**重要更新：** 自 2024 年 11 月起，Sling 在 `/account/login` API 端点添加了验证码保护。这意味着直接的电子邮件/密码身份验证在没有解决验证码挑战的情况下不再有效。
**解决方案：** 而是使用从浏览器预先获取的授权令牌。请参阅 [TOKEN_GUIDE.md](./TOKEN_GUIDE.md) 获取详细说明。
**为什么这种方法有效：**
- 从浏览器会话获取的令牌不需要验证码
- 令牌通常有效期为数周或数月
- 您只需在令牌过期或更改密码时获取新令牌
- 在 Sling 提供替代 API 身份验证方法之前，这是推荐的方法
## API 文档
有关 Sling API 端点和数据格式的详细信息，请参阅：
- [官方 Sling API 文档](https://api.getsling.com/)
- [Sling API GitHub 仓库](https://github.com/getsling/getsling-api-docs)
## 开发
### 构建
```bash
npm run build
```
### 监视模式
```bash
npm run watch
```
### 运行开发服务器
```bash
npm run dev
```
### 测试身份验证
要验证您的凭证在与 Claude 结合使用之前是否有效：
```bash
node test-auth.js
```
这将尝试身份验证并显示详细的调试信息。
## 权限
您的 API 访问级别与您的 Sling 用户权限相匹配：
- **管理员令牌** - 对所有组织数据的完全访问权限
- **员工令牌** - 仅限于该用户的信息
## 故障排除
### “未从 Sling API 收到授权令牌”
服务器现在包含详细的调试日志记录。请在 MCP 服务器日志（Claude 桌面开发人员控制台）中查看：
- 响应状态码
- 响应头
- 响应正文
这将有助于确定令牌的位置。
**快速修复：**
1. 验证 `.env` 中的凭证是否正确（无额外引号/空格）
2. 使用 curl 测试登录：
```bash
curl -i -X POST https://api.getsling.com/account/login \
-H "Content-Type: application/json" \
-d '{"email":"your@email.com","password":"password"}'
```
3. 在响应中查找 `authorization:` 头
**有关详细故障排除步骤，请参阅 [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)**
### 身份验证问题
- 验证您的电子邮件和密码在 `.env` 中是否正确
- 检查您是否可以使用这些凭证登录 Sling 网络应用程序
- 确保您正在使用正确的服务器（api vs test-api）
- 确保您不是在使用 OAuth 提供商凭证（Google/Facebook）
### API 错误
- 检查错误消息以获取具体详细信息
- 验证您的用户是否具有访问请求资源的权限
- 确保日期格式为 ISO 8601 格式（例如，“2024-01-20T09:00:00Z”）
### 连接问题
- 验证您是否具有互联网连接
- 检查 api.getsling.com 是否可访问
- 尝试在测试环境中使用 SLING_SERVER=test-api
### 调试
服务器将详细的身份验证信息记录到 stderr：
- 来自 Sling API 的所有响应头
- 响应正文内容
- 令牌提取尝试
在以下位置查看这些日志：
- **Claude 桌面版**：帮助 → 开发者工具 → 控制台
- **终端**：MCP 服务器进程的 stderr 输出
## 许可证
MIT
## 贡献
欢迎贡献！请随时提交拉取请求。
## 支持
对于以下问题：
- **此 MCP 服务器**：在此仓库中打开问题
- **Sling API**：请参阅 [Sling API 文档](https://github.com/getsling/getsling-api-docs)
- **MCP 协议**：请参阅 [MCP 文档](https://modelcontextprotocol.io/)
