内容
# Strety MCP 服务器
用于将 Strety 与 Claude Code 集成的 MCP（模型上下文协议）服务器。
## 功能
- **读取工具：** 列出待办事项（按负责人、完成状态过滤），获取待办事项详情，列出人员
- **写入工具：** 创建、更新、完成/取消完成和删除待办事项
- 自动刷新 OAuth令牌
- 自动处理 PATCH 操作的 ETag
- 负责人名称解析（部分匹配，例如 "Brent" 解析为完整 ID）
## 安装
```bash
cd /Users/brent/scripts/CB-Workspace/mcp-servers/strety
npm install
npm run build
```
## 配置
### 1. 创建 Strety OAuth 应用
1. 访问 https://2.strety.com
2. 导航到：我的集成 > 我的应用
3. 创建新应用，参数如下：
- **名称：** Strety-MCP
- **重定向 URI：** `https://localhost:8888/callback`
- **作用域：** `read`，`write`
### 2. 获取 OAuth 令牌
参见 [todo/strety-oauth-flow.md](todo/strety-oauth-flow.md) 获取详细说明。
**快速版：**
```bash
# 终端 1：启动监听器
nc -l 8888
# 终端 2：打开此网址（替换 CLIENT_ID）
# https://2.strety.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://localhost:8888/callback&response_type=code&scope=read+write
# 交换代码为令牌
curl -X POST "https://2.strety.com/api/v1/oauth/token" \
-d "grant_type=authorization_code" \
-d "code=CODE_FROM_CALLBACK" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "redirect_uri=https://localhost:8888/callback"
```
### 3. 保存令牌
```bash
mkdir -p ~/.mcp-strety
cat > ~/.mcp-strety/token.json << 'EOF'
{
"access_token": "YOUR_ACCESS_TOKEN",
"refresh_token": "YOUR_REFRESH_TOKEN",
"saved_at": "2026-01-27T00:00:00.000Z"
}
EOF
```
### 4. 添加到 Claude Code
添加到 `~/.mcp.json` 或项目 `.mcp.json`：
```json
{
"mcpServers": {
"strety": {
"command": "node",
"args": ["/Users/brent/scripts/CB-Workspace/mcp-servers/strety/dist/index.js"],
"env": {
"STRETY_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN",
"STRETY_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN",
"STRETY_CLIENT_ID": "YOUR_CLIENT_ID",
"STRETY_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
}
}
}
}
```
### 5. 重启 Claude Code
MCP 服务器在 Claude Code 启动时加载。
## 可用工具
### 读取工具
| 工具 | 描述 |
|------|-------------|
| `strety_list_todos` | 列出待办事项，可选过滤（负责人，完成状态） |
| `strety_get_todo` | 获取特定待办事项的完整详情 |
| `strety_list_people` | 列出组织中的所有人员 |
### 写入工具
| 工具 | 描述 |
|------|-------------|
| `strety_create_todo` | 创建带有标题、描述、负责人、截止日期、优先级的全新待办事项 |
| `strety_update_todo` | 更新现有待办事项的字段（自动 ETag 处理） |
| `strety_complete_todo` | 将待办事项标记为完成或取消完成（自动 ETag 处理） |
| `strety_delete_todo` | 永久删除待办事项 |
**注意：** 写入工具需要带有 `read` 和 `write` 作用域的 OAuth 令牌。PATCH 操作（更新，完成）会自动获取请求所需的 ETag。
## 令牌管理
服务器自动处理令牌刷新：
1. 从 `~/.mcp-strety/token.json`（首选）或环境变量加载令牌
2. 当出现 401 时，服务器尝试使用刷新令牌刷新
3. 新令牌保存回 `~/.mcp-strety/token.json`
**重要：** 令牌在 2 小时后过期。自动刷新处理此问题，但如果刷新令牌也过期，则需要重新授权。
## API 说明
- **基准 URL：** `https://2.strety.com/api/v1`
- **页面大小限制：** 每次请求最多 20 项
- **速率限制：** 10 秒内 10 次请求
- **分页：** 服务器最多获取 50 页以查找所有匹配的待办事项
## 故障排除
### "身份验证失败" 错误
1. 检查令牌是否过期
2. 尝试手动刷新（参见 oauth-flow.md）
3. 如果刷新失败，请完全重新授权
### 使用写入工具时出现 "无效作用域" 或 403
令牌仅具有 `read` 作用域。重新授权为 `read+write` 作用域（参见 OAuth 流程文档）。
### 待办事项未显示
服务器分页最多 50 页。如果 Brent 的待办事项分布在多个页面上，它们仍然应该被找到。检查负责人过滤器是否正确。
## 文件
```
strety/
├── src/index.ts # 主要服务器代码（7 个工具）
├── dist/index.js # 编译输出（gitignored）
├── package.json
├── tsconfig.json
├── .gitignore
├── README.md # 本文件
└── docs/
├── README.md # 文档索引
├── strety-oauth-flow.md # OAuth 文档
├── strety-api-mapping.md # API 端点参考
└── strety-mcp-tools-spec.md # 工具规格
```
## 开发
```bash
# 构建
npm run build
# 监视模式（如果配置）
npm run dev
```
