towerim 0.0.0-stage → 1.0.16
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/README.md +92 -2
- package/SKILL.md +111 -0
- package/package.json +1 -6
- package/tower.cjs +25 -0
package/README.md
CHANGED
|
@@ -1,3 +1,93 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Tower MCP(AgentsTower)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
把 Tower.im 接入 AI 客户端(Claude Code、Codex、Cursor 等)的命令行与服务工具。编译后会得到一个独立的 `tower` 程序,同时支持两种使用方式:
|
|
4
|
+
|
|
5
|
+
1. **个人本地使用(stdio MCP)**:在自己电脑上运行 `tower login` 登录 Tower 账号,然后把 `tower mcp` 配进 AI 客户端,直接读写团队、项目、任务、知识库和工时。
|
|
6
|
+
2. **团队自托管(HTTP MCP + 网页控制台)**:在服务器上运行 `tower serve`,团队成员在网页上绑定自己的 Tower 账号并获取 `at_sk-...` 密钥,就能通过 HTTP 地址接入 MCP;同时自带网页版 REST API / MCP 调试台和成员管理后台。
|
|
7
|
+
|
|
8
|
+
两种模式共用同一套 MCP 工具和 SQLite 存储逻辑。
|
|
9
|
+
|
|
10
|
+
## npm 安装
|
|
11
|
+
|
|
12
|
+
Windows、macOS 和 Linux 均支持 x64 与 arm64。运行 `npm install -g towerim` 后即可使用 `tower login`。MCP 客户端也可以通过 `npx --yes towerim@latest mcp` 启动。npm 会按当前 Node.js 的系统和架构安装对应的二进制包,请保留可选依赖。
|
|
13
|
+
|
|
14
|
+
## 编译构建
|
|
15
|
+
|
|
16
|
+
在仓库根目录执行(需要 Go 1.26、Node.js 和 pnpm):
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
make install
|
|
20
|
+
make build
|
|
21
|
+
./server/bin/tower --version
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
编译产物为 `server/bin/tower`,前端网页控制台已内嵌在二进制中。
|
|
25
|
+
|
|
26
|
+
## 常用命令
|
|
27
|
+
|
|
28
|
+
| 命令 | 说明 |
|
|
29
|
+
| --- | --- |
|
|
30
|
+
| `tower login [--reconfigure]` | 在终端登录 Tower 账号并保存本地凭据(加 `--reconfigure` 可重填 OAuth 应用配置) |
|
|
31
|
+
| `tower status` | 查看本地配置目录、当前绑定的 Tower 账号、Token 与网页会话状态 |
|
|
32
|
+
| `tower logout [--all]` | 退出本地绑定的 Tower 账号(加 `--all` 同时清除 OAuth 应用配置) |
|
|
33
|
+
| `tower mcp`(或直接运行 `tower`) | 启动本地 stdio MCP 服务(供 AI 客户端调用) |
|
|
34
|
+
| `tower serve` | 启动网页控制台和 Streamable HTTP MCP 服务 |
|
|
35
|
+
| `tower user list` | 列出数据库中的所有用户 |
|
|
36
|
+
| `tower user reset-password <用户名> <新密码>` | 重置指定用户密码 |
|
|
37
|
+
| `tower admin grant <用户名>` | 授予管理员权限 |
|
|
38
|
+
| `tower admin revoke <用户名>` | 取消管理员权限 |
|
|
39
|
+
| `tower --version` | 查看当前版本号 |
|
|
40
|
+
|
|
41
|
+
## 方式一:个人本地使用(stdio MCP)
|
|
42
|
+
|
|
43
|
+
1. 在终端运行:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
./server/bin/tower login
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
如果当前环境尚未配置 Tower OAuth 应用信息,程序会提示输入 `Client ID`、`Client Secret` 和回调地址;之后选择邮箱密码或微信扫码登录,程序会自动完成授权并保存凭据。
|
|
50
|
+
|
|
51
|
+
2. 在 AI 客户端配置 MCP,命令填 `tower` 的绝对路径,参数填 `mcp`(以 Codex 为例):
|
|
52
|
+
|
|
53
|
+
```toml
|
|
54
|
+
[mcp_servers.tower]
|
|
55
|
+
command = "/绝对路径/server/bin/tower"
|
|
56
|
+
args = ["mcp"]
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
3. 将 [本地 Skill](standalone/SKILL.md) 安装到你的 Agent Skill 目录,帮助 Agent 正确使用各项工具。
|
|
60
|
+
|
|
61
|
+
**本地数据说明**:
|
|
62
|
+
- 默认数据库路径为 `~/.config/tower/tower.db`;若设置了 `XDG_CONFIG_HOME`,则存放在 `$XDG_CONFIG_HOME/tower/tower.db`;也可以用 `TOWER_CONFIG_DIR` 直接指定存放目录。
|
|
63
|
+
- 多个 Agent 共用同一配置目录时,会共享本地账号和默认绑定的 Tower 账号。
|
|
64
|
+
- 历史版本的 `credentials.json` 会在启动时自动导入到 SQLite 数据库。
|
|
65
|
+
|
|
66
|
+
## 方式二:团队自托管(HTTP 服务)
|
|
67
|
+
|
|
68
|
+
1. 复制并编辑环境变量配置:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
cp server/.env.example server/.env
|
|
72
|
+
# 填写 TOWER_CLIENT_ID、TOWER_CLIENT_SECRET 等配置
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
2. 启动服务:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
make run
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
`make run` 会在 `server/` 目录下执行 `go run . serve`。如果直接运行编译好的二进制,可在 `server/` 目录下执行 `./bin/tower serve`(同样会读取 `server/.env`)。
|
|
82
|
+
|
|
83
|
+
服务默认监听 `[::]:8888`,数据库默认使用 `server/data/data.db`,MCP 接口路径为 `/mcp`。完整的环境变量、命令行管理和接入示例见 [HTTP 服务说明](server/README.md)。
|
|
84
|
+
|
|
85
|
+
> **提示**:如果想用网页控制台来管理本地模式的 `tower.db`,只需启动 `tower serve` 时将 `DB_PATH` 指向该 `tower.db`(并配置好相同的 Tower OAuth 应用信息)。本地模式自动创建的默认用户名为 `standalone`,初始密码也是 `standalone`;如果要对外开放端口,请先修改该密码。
|
|
86
|
+
|
|
87
|
+
## 开发、测试与更多文档
|
|
88
|
+
|
|
89
|
+
- `make dev`:同时启动 Go 后端热重载(Air)与前端 Vite 开发服务。
|
|
90
|
+
- `make test`:构建前端并运行全部 Go 测试和 `go vet`。
|
|
91
|
+
- `make test-standalone`:只运行本地模式相关的测试。
|
|
92
|
+
- `make docker-build`:构建默认运行 `tower serve` 的 Docker 镜像;生产发布与回滚见 [单机蓝绿部署](deploy/README.md)。
|
|
93
|
+
- 目录说明:`standalone/` 存放本地 Skill,`server/` 为 Go 服务端与前端控制台源码,`docs/` 为 [Tower API 参考文档](docs/README.md)。
|
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/package.json
CHANGED
|
@@ -1,6 +1 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "towerim",
|
|
3
|
-
"version": "0.0.0-stage",
|
|
4
|
-
"stub": true,
|
|
5
|
-
"description": "Temporary package placeholder for staged publishing"
|
|
6
|
-
}
|
|
1
|
+
{"version": "1.0.16", "name": "towerim", "description": "Tower MCP server and CLI", "bin": {"tower": "tower.cjs"}, "optionalDependencies": {"@xxn6141/towerim-linux-x64": "1.0.16", "@xxn6141/towerim-linux-arm64": "1.0.16", "@xxn6141/towerim-darwin-x64": "1.0.16", "@xxn6141/towerim-darwin-arm64": "1.0.16", "@xxn6141/towerim-win32-x64": "1.0.16", "@xxn6141/towerim-win32-arm64": "1.0.16"}}
|
package/tower.cjs
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
const { spawn } = require('node:child_process');
|
|
3
|
+
const name = `@xxn6141/towerim-${process.platform}-${process.arch}`;
|
|
4
|
+
const binary = process.platform === 'win32' ? 'tower.exe' : 'tower';
|
|
5
|
+
let executable;
|
|
6
|
+
try {
|
|
7
|
+
executable = require.resolve(`${name}/bin/${binary}`);
|
|
8
|
+
} catch {
|
|
9
|
+
const supported = Object.hasOwn(require('./package.json').optionalDependencies, name);
|
|
10
|
+
console.error(supported
|
|
11
|
+
? `Missing ${name}. Reinstall towerim with npm --include=optional.`
|
|
12
|
+
: `Unsupported platform: ${process.platform} ${process.arch}`);
|
|
13
|
+
process.exit(1);
|
|
14
|
+
}
|
|
15
|
+
const child = spawn(executable, process.argv.slice(2), { stdio: 'inherit' });
|
|
16
|
+
for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
|
|
17
|
+
process.on(signal, () => child.kill(signal));
|
|
18
|
+
}
|
|
19
|
+
child.on('error', error => {
|
|
20
|
+
console.error(error.message);
|
|
21
|
+
process.exitCode = 1;
|
|
22
|
+
});
|
|
23
|
+
child.on('exit', (code, signal) => {
|
|
24
|
+
process.exitCode = code ?? (128 + require('node:os').constants.signals[signal]);
|
|
25
|
+
});
|