towerim 0.0.0-stage → 1.0.15
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/SKILL.md +111 -0
- package/bin/tower +0 -0
- package/package.json +15 -3
- package/README.md +0 -3
package/SKILL.md
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: tower
|
|
3
|
+
description: 通过本地 Tower MCP 连接 Tower.im:查看我的待办、逾期任务和通知,解析 tower.im 任务与知识库文档链接,搜索/筛选项目任务,创建、指派、评论、完成任务,上传项目文件以及查询或登记工时。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Tower(本地 MCP 使用指南)
|
|
7
|
+
|
|
8
|
+
## 1. 本地安装与接入
|
|
9
|
+
|
|
10
|
+
1. 在仓库根目录编译并安装到本地 `PATH`(默认安装到 `~/.local/bin/tower`):
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
make install-local
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
(也可以只执行 `make build`,产物在 `server/bin/tower`。)
|
|
17
|
+
|
|
18
|
+
2. 在终端运行 `tower login`:
|
|
19
|
+
- 如果尚未配置 Tower OAuth 应用,按终端提示输入 `Client ID`、`Client Secret` 和回调地址(密钥不回显,回调地址可直接回车用默认值)。程序优先读取环境变量或当前目录 `.env` 中的 `TOWER_CLIENT_ID`、`TOWER_CLIENT_SECRET`、`TOWER_REDIRECT_URI`,其次读取数据库已保存的配置;默认回调地址为 `SITE_BASE_URL/oauth2/callback`(未设置时为 `http://localhost:8888/oauth2/callback`)。
|
|
20
|
+
- 选择邮箱密码或微信扫码登录 Tower(微信扫码会优先在终端直接显示二维码字符画,不支持时自动保存并打开图片);如遇到两步验证按提示输入验证码。程序会自动完成 OAuth 授权并保存 Token,无需另起 HTTP 服务。
|
|
21
|
+
- 常用本地维护命令:
|
|
22
|
+
- `tower status`:查看配置目录、当前激活的 Tower 账号、Token 有效期和网页会话状态。
|
|
23
|
+
- `tower login --reconfigure`:重新填写 Tower OAuth 应用配置并登录。
|
|
24
|
+
- `tower logout`(或 `tower logout --all`):退出本地绑定的 Tower 账号(加 `--all` 会同时清除本地 OAuth 应用配置)。
|
|
25
|
+
3. 将 `tower` 的绝对路径配进 AI 客户端的 stdio MCP 配置(参数传 `mcp`,也可省略参数直接运行)。以 Codex 为例:
|
|
26
|
+
|
|
27
|
+
```toml
|
|
28
|
+
[mcp_servers.tower]
|
|
29
|
+
command = "/home/你的用户名/.local/bin/tower"
|
|
30
|
+
args = ["mcp"]
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
**本地存储说明**:
|
|
34
|
+
- 首次启动会在 `~/.config/tower/tower.db` 创建内置用户 `standalone`(初始密码也为 `standalone`),保存 OAuth 配置、网页 Cookie 和 Token,并自动导入旧版 `credentials.json`。
|
|
35
|
+
- 可通过 `XDG_CONFIG_HOME`(使用其下的 `tower/tower.db`)或 `TOWER_CONFIG_DIR` 自定义数据库目录。多个 Agent 共用同一目录时,共享最早绑定且仍有效的 Tower 账号与 Token 刷新状态。
|
|
36
|
+
|
|
37
|
+
## 2. 常见网页链接速查
|
|
38
|
+
|
|
39
|
+
收到用户贴来的 Tower 网页链接时,直接按下面方式一步调用,不需要从团队/项目一层层翻:
|
|
40
|
+
|
|
41
|
+
| 网页链接格式 | 直接调用的工具 |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| `https://tower.im/teams/{团队编号}/todos/{任务编号}` | `get_todo_by_number(team_id="{团队编号}", team_wide_id="{任务编号}")` |
|
|
44
|
+
| `https://tower.im/teams/{团队编号}/repository_documents/{文档编号}` | 先 `get_team_resource(team_id="{团队编号}", resource_id="{文档编号}")` 或直接用 `read_repository_item(team_id, url)` |
|
|
45
|
+
| 已知 32 位任务 GUID | `get_todo(todo_id)` |
|
|
46
|
+
|
|
47
|
+
## 3. 标准 ID 查询链路
|
|
48
|
+
|
|
49
|
+
Tower 资源按层级组织。除了直接汇总的快捷工具外,常规操作按以下顺序拿到前置 ID:
|
|
50
|
+
|
|
51
|
+
1. **快速查看我的待办(首选)**
|
|
52
|
+
- 直接调用 `my_todo_overview`,无需提前知道 `team_id` 或 `member_id`,自动返回你在各团队的 `team_id`、`member_id` 和未完成待办。
|
|
53
|
+
2. **团队 -> 项目 / 成员**
|
|
54
|
+
- `list_teams` -> 获取 `team_id`
|
|
55
|
+
- `list_projects(team_id)` -> 获取 `project_id`
|
|
56
|
+
- `list_team_members(team_id)` 或 `get_my_team_member(team_id)` -> 获取 `member_id`(指派任务、填报工时用)
|
|
57
|
+
3. **项目 -> 任务清单 -> 任务**
|
|
58
|
+
- `list_todolists(project_id)` -> 获取 `todolist_id`
|
|
59
|
+
- `list_todos(todolist_id)` 查询任务,或 `create_todo` 新建任务
|
|
60
|
+
- 任务后续操作(评论、指派/移除负责人 `assign_todo` / `unassign_todo`、改截止日期 `update_todo_due`、完成 `complete_todo`、重开 `reopen_todo`)均使用 `todo_id`。
|
|
61
|
+
4. **一步上传项目文件**
|
|
62
|
+
- 优先用复合工具 `upload_file`(传入 `team_id`、`project_id`、`filename` 以及 `content` 文本或 `content_base64`),服务端会自动算 MD5、申请 OSS 签名、直传并关联到项目。
|
|
63
|
+
|
|
64
|
+
## 4. 搜索、筛选与知识库
|
|
65
|
+
|
|
66
|
+
### 关键词与条件搜索
|
|
67
|
+
- **网页全文/标签搜索 `search_todos`**:必须传非空的 `keyword` 或 `tag`(可带 `#`,传了有效 `tag` 时会忽略空白 `keyword`)。
|
|
68
|
+
- 可选参数:`member_guid`(Tower API 成员 ID,传入后只搜该成员所在团队)、`target_gid`、`category`、`sort`、`exclude_trash`。
|
|
69
|
+
- 每次返回各搜索团队的一页结果;拿到 `next_page` 时,保留原筛选条件并传 `page=next_page` 继续翻页。
|
|
70
|
+
- 注意:`tag` 搜索匹配的是 Tower 全文索引里的 `#标签` 文本;要按任务上的结构化标签筛选,请用下面的 `filter_project_todos`。
|
|
71
|
+
- **API 扫描搜索 `advanced_search_todos`**:按 API `project_id`、团队或完成状态限量扫描任务时使用。
|
|
72
|
+
- **项目内精细条件查询 `filter_project_todos`(Multi-API)**:
|
|
73
|
+
- 传 `project_id`、`status`(如 `"uncompleted"`)以及 `conditions`,例如:
|
|
74
|
+
`conditions: [{"field":"label","operator":"in","value":"bug"},{"field":"custom.<字段 key>","operator":"in","value":"Web"}]`
|
|
75
|
+
- 筛选条件里的选项传**显示名称**,写入任务时传**选项 ID**。
|
|
76
|
+
- 日期按北京时间自然日比较,例如 `{"field":"created_at","operator":"eq","value":"2026-11-19"}` 查当天新建的任务。
|
|
77
|
+
- 每页按匹配条数计算,只有确认还有更多匹配时才返回 `next_cursor`。
|
|
78
|
+
|
|
79
|
+
### 知识库与网页资源
|
|
80
|
+
- **搜索知识库**:先用 `list_teams` 拿到团队 GUID,再调 `search_todos(team_id, keyword, category=18)`。不传团队和成员时默认只搜当前网页团队;跨团队搜需显式传 `all_teams=true`。拿到命中的 `team_id` 和 `url` 后,原样传给 `read_repository_item` 读取 Markdown 正文。
|
|
81
|
+
- **浏览知识库目录**:先 `list_repositories(team_id)`,再用 `list_repository_items(team_id, url)` 逐层往下看(不需要关键词)。注意目录项里的 `id` 是网页短编号,读取正文要用 `url`。
|
|
82
|
+
- **查评论与网页链接映射**:`category=7` 返回评论,`parent_type` 和 `parent_url` 指向被评论的资源;零命中只代表当前页在 Tower 网页索引里没匹配到。
|
|
83
|
+
- 网页路径 `/teams/{team_number}/repository_documents/{resource_number}` 中的两个数字分别是团队编号和资源短编号。用 `get_team_resource`(传团队 GUID 或数字编号 + 资源短编号)可换取 Open API 资源 GUID(搜索结果映射成功时也会直接填在 `id` 里)。`raw_request` 只能访问 Open API,读知识库正文必须用 `read_repository_item`。
|
|
84
|
+
|
|
85
|
+
### 需登录 Tower 网页后才能使用的扩展工具
|
|
86
|
+
- `get_project_task_fields(project_id)`:查询项目的结构化标签 ID、自定义字段 key 和选项,返回值可直接用于 `create_todo`、`update_todo`。
|
|
87
|
+
- `move_todo_in_project(todo_id, project_id, todolist_id)`:把任务在指定项目内移动到目标清单。(跨项目关联用 `add_todo_project`,设置父任务用 `update_todo.parent_id`。)
|
|
88
|
+
- `list_todo_history(todo_id)`:按时间从早到晚返回变更记录和评论。每页默认 20 条,可传 `page_size`(1–50),有 `next_offset` 时将其作为 `offset` 继续翻页。
|
|
89
|
+
|
|
90
|
+
## 5. 分页、排序与返回边界
|
|
91
|
+
|
|
92
|
+
- **标准列表分页**:`list_*` 默认每页 20 条、最大 50 条。收到 `meta.next_page` 时保留原筛选参数和 `page_size` 继续翻页。
|
|
93
|
+
- **活动流游标分页**:`list_events` 把 `meta.next_cursor` 传给下一次的 `last_item_id`,保留原 `page_size`。
|
|
94
|
+
- **倒序取最新任务**:
|
|
95
|
+
- `list_todos(order="-created_at")`:会先拉完该清单的所有页再按创建时间倒序分页返回。
|
|
96
|
+
- `list_project_todos`(默认含已完成,传 `completed_todo=false` 只查未完成)与 `filter_project_todos` 都支持 `order="-created_at"`;首屏排序需要扫描整个项目,翻页时保留筛选和排序条件并把 `next_cursor` 传给 `cursor`(游标在当前进程内 15 分钟有效)。
|
|
97
|
+
- `list_member_created_todos` 和 `list_member_assigned_todos` 也支持 `order="-created_at"`;若跨成员查询返回 `scope_complete=false`,说明只扫描了部分范围,仅保证已返回数据的顺序,总数未知。
|
|
98
|
+
- **逾期 / 截止日期查询**:`list_member_assigned_uncompleted_todos(overdue=true)` 查北京时间今天之前已到期的未完成任务,也可用 `due_before=YYYY-MM-DD`(截止当天不计入)。不传 `page` 和 `page_size` 时一次返回所有可确认的匹配项;传了任一分页参数则按页返回(筛选模式默认每页 50 条)。若 `scope_complete` 为「否」,结果仅反映已扫描到且能确认截止日期的记录。
|
|
99
|
+
- **元信息含义**:
|
|
100
|
+
- `meta.returned`:本次实际返回条数;只有能确认总量时才会给出 `meta.total`。
|
|
101
|
+
- `meta.has_more` 为「未知」时,表示上游没给足是否还有下一页的依据;如果同时给了下一页参数,可以继续请求确认。
|
|
102
|
+
- 无法取全时,`meta.incomplete_reason` 会说明原因(`my_todo_overview` 和 `advanced_search_todos` 在顶层返回该字段)。
|
|
103
|
+
- 成员未完成任务优先通过任务关系接口查,不可用时回退到 Tower 专用列表(专用列表可能漏掉部分任务,此时总数未知)。
|
|
104
|
+
- `my_todo_overview` 未指定 `team_id` 时最多检查 10 个团队,每团队每类任务默认 20 条、最多 50 条。
|
|
105
|
+
- **原始请求 `raw_request`**:对已知分页路径使用上述默认页大小和上限。支持传 `data_only=true` 只拿当前页数据,或 `fields=["id","content","created_at"]` 裁剪返回字段。
|
|
106
|
+
|
|
107
|
+
## 6. 常规操作与硬删除保护
|
|
108
|
+
|
|
109
|
+
- **常规协作默认放行**:`complete_todo`、`reopen_todo`、`assign_todo`、`unassign_todo` 属于非破坏性写入,只要当前成员在 Tower 有权操作即可直接执行。更新通知成员时向 `update_todo_cc_members` 传完整成员列表,传空数组即清空。
|
|
110
|
+
- **工时权限**:如果 `list_project_time_logs` 返回 403,可以改用 `list_todo_time_logs` 查询单个任务的工时。
|
|
111
|
+
- **硬删除保护**:本地 MCP 读取同一份数据库配置,默认拦截删项目、任务、讨论、文件、工时等硬删除请求。
|
package/bin/tower
ADDED
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,18 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "towerim",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "1.0.15",
|
|
4
|
+
"description": "Tower MCP server and CLI",
|
|
5
|
+
"bin": {
|
|
6
|
+
"tower": "bin/tower"
|
|
7
|
+
},
|
|
8
|
+
"os": [
|
|
9
|
+
"linux"
|
|
10
|
+
],
|
|
11
|
+
"cpu": [
|
|
12
|
+
"x64"
|
|
13
|
+
],
|
|
14
|
+
"files": [
|
|
15
|
+
"bin/tower",
|
|
16
|
+
"SKILL.md"
|
|
17
|
+
]
|
|
6
18
|
}
|
package/README.md
DELETED