@stellar_ai/mcp_fossil_scm 0.1.1 → 0.1.3

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.
Files changed (55) hide show
  1. package/LICENSE +28 -0
  2. package/README.md +140 -113
  3. package/dist/capabilities.js +6 -7
  4. package/dist/cli.js +28 -24
  5. package/dist/config.js +7 -32
  6. package/dist/core/fossil.js +67 -79
  7. package/dist/core/gitignore.js +136 -0
  8. package/dist/core/sql.js +3 -2
  9. package/dist/index.js +8 -7
  10. package/dist/prompts.js +167 -0
  11. package/dist/server.js +6 -5
  12. package/dist/tools/admin.js +454 -86
  13. package/dist/tools/chat.js +22 -26
  14. package/dist/tools/common.js +14 -5
  15. package/dist/tools/forum.js +37 -29
  16. package/dist/tools/tickets.js +32 -11
  17. package/dist/tools/version-control.js +880 -105
  18. package/dist/tools/wiki.js +17 -18
  19. package/docs/README.md +31 -0
  20. package/docs/admin.md +663 -0
  21. package/docs/chat.md +152 -0
  22. package/docs/forum.md +146 -0
  23. package/docs/prompts.md +39 -0
  24. package/docs/tickets.md +179 -0
  25. package/docs/vcs.md +1089 -0
  26. package/docs/wiki.md +140 -0
  27. package/package.json +11 -6
  28. package/dist/capabilities.d.ts +0 -32
  29. package/dist/capabilities.js.map +0 -1
  30. package/dist/cli.d.ts +0 -27
  31. package/dist/cli.js.map +0 -1
  32. package/dist/config.d.ts +0 -27
  33. package/dist/config.js.map +0 -1
  34. package/dist/core/fossil.d.ts +0 -104
  35. package/dist/core/fossil.js.map +0 -1
  36. package/dist/core/sql.d.ts +0 -29
  37. package/dist/core/sql.js.map +0 -1
  38. package/dist/index.d.ts +0 -2
  39. package/dist/index.js.map +0 -1
  40. package/dist/server.d.ts +0 -13
  41. package/dist/server.js.map +0 -1
  42. package/dist/tools/admin.d.ts +0 -3
  43. package/dist/tools/admin.js.map +0 -1
  44. package/dist/tools/chat.d.ts +0 -10
  45. package/dist/tools/chat.js.map +0 -1
  46. package/dist/tools/common.d.ts +0 -9
  47. package/dist/tools/common.js.map +0 -1
  48. package/dist/tools/forum.d.ts +0 -3
  49. package/dist/tools/forum.js.map +0 -1
  50. package/dist/tools/tickets.d.ts +0 -8
  51. package/dist/tools/tickets.js.map +0 -1
  52. package/dist/tools/version-control.d.ts +0 -3
  53. package/dist/tools/version-control.js.map +0 -1
  54. package/dist/tools/wiki.d.ts +0 -3
  55. package/dist/tools/wiki.js.map +0 -1
package/LICENSE ADDED
@@ -0,0 +1,28 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2026 ri-fumo
4
+
5
+ Redistribution and use in source and binary forms, with or without
6
+ modification, are permitted provided that the following conditions are met:
7
+
8
+ 1. Redistributions of source code must retain the above copyright notice, this
9
+ list of conditions and the following disclaimer.
10
+
11
+ 2. Redistributions in binary form must reproduce the above copyright notice,
12
+ this list of conditions and the following disclaimer in the documentation
13
+ and/or other materials provided with the distribution.
14
+
15
+ 3. Neither the name of the copyright holder nor the names of its
16
+ contributors may be used to endorse or promote products derived from
17
+ this software without specific prior written permission.
18
+
19
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
package/README.md CHANGED
@@ -1,172 +1,199 @@
1
1
  # fossil-scm
2
2
 
3
- MCP (Model Context Protocol) server for [Fossil SCM](https://fossil-scm.org/).
3
+ [Fossil SCM](https://fossil-scm.org/) 的 MCP(Model Context Protocol)伺服器。
4
4
 
5
- One binary, one list of capability letters: `--capability` decides which tool groups this process exposes,
6
- so a client loads only what it needs. Each letter is the **initial** of its capability name.
5
+ 六種能力(Admin、VCS、Forum、Tickets、Wiki、Chat)、一個執行檔、一組字母:`--capability` 決定這個行程
6
+ 要暴露哪些工具組,客戶端只載入需要的部分。每個字母是其能力名稱的**首字母**。
7
7
 
8
- | Letter | Capability | Tools | What it exposes |
8
+ | 字母 | 能力 | 工具 | 暴露的內容 |
9
9
  | --- | --- | --- | --- |
10
- | `a` | **A**dmin | 5 | Repository lifecycle: `init`, `open`, `close`, `clone`, `settings` |
11
- | `v` | **V**CS | 20 | Version control: status, diff, history, add/commit, branch, merge, update, undo, … |
12
- | `f` | **F**orum | 3 | Forum thread list, thread reading and text search (read-only) |
13
- | `t` | **T**ickets | 3 | Ticket reports, creation, field updates |
14
- | `w` | **W**iki | 3 | List, export and create/replace wiki pages |
15
- | `c` | **C**hat | 4 | Chatroom URL, send, pull history, read locally stored messages |
10
+ | `a` | **A**dmin | 11 | 倉庫生命週期:`init`、`open`、`close`、`clone`、`settings`、`remote`、`push`、`pull`、`sync`、`rebuild`、`config` |
11
+ | `v` | **V**CS | 40 | 版本控制:status、diff、歷史、add/commit、branch、merge、update、undo、blame/grep/whatis … |
12
+ | `f` | **F**orum | 3 | 論壇主題列表、讀取與文字搜尋(只讀) |
13
+ | `t` | **T**ickets | 4 | 工單報表、建立、欄位更新 |
14
+ | `w` | **W**iki | 3 | 列表、匯出與建立/覆寫 wiki 頁面 |
15
+ | `c` | **C**hat | 4 | 聊天室 URL、傳送、拉取歷史、讀取本地訊息 |
16
16
 
17
- The letters are written **together in a single value**: `-c v` (20 tools), `-c avf` (28), `-c aftw` (14),
18
- and a single capital `-c A` for everything (38, also the default). Commas, spaces, `all`/`All` and repeated
19
- `-c` flags are rejected.
17
+ 字母**寫在單一值裡**:`-c v`(40 個工具)、`-c avf`(54)、`-c aftw`(21),單一的大寫 `-c A` 為全部
18
+ (65,也是預設)。逗號、空白、`all`/`All` 與重複的 `-c` 都會被拒絕。
20
19
 
21
- > Naming: the Fossil executable/command is `fossil`; this server is always called `fossil-scm`.
20
+ > 命名:Fossil 的可執行檔/指令叫 `fossil`;本伺服器一律叫 `fossil-scm`。
22
21
 
23
- TypeScript rewrite of the original single-file Python server (`./,server.py`), built on the
24
- MCP TypeScript SDK v2 (`@modelcontextprotocol/server`).
22
+ 以 TypeScript 重寫先前單檔的 Python 實作,建構在 MCP TypeScript SDK v2(`@modelcontextprotocol/server`)之上。
25
23
 
26
- ## Requirements
24
+ ## 需求
27
25
 
28
26
  - Node.js >= 20
29
- - `fossil` on `PATH` (or set `FOSSIL_BIN`)
27
+ - `PATH` 上的 `fossil`(或設定 `FOSSIL_BIN`)
30
28
 
31
- ## Build & run
29
+ ## 安裝
30
+
31
+ ```bash
32
+ pnpm add @stellar_ai/mcp_fossil_scm # or: npm i -g @stellar_ai/mcp_fossil_scm
33
+ npx -y @stellar_ai/mcp_fossil_scm -c avf --workspace /path/to/workspace
34
+ ```
35
+
36
+ ## 從原始碼建置與執行
32
37
 
33
38
  ```bash
34
39
  pnpm install
35
40
  pnpm build
36
41
 
37
- node dist/index.js -c v --repository /path/to/workspace # version control only
38
- node dist/index.js -c avf --repository /path/to/workspace # admin + VCS + forum
39
- node dist/index.js -c aftw --repository /path/to/workspace # admin + forum + tickets + wiki
40
- node dist/index.js -c A --repository /path/to/workspace # everything
42
+ node dist/index.js -c v --workspace /path/to/workspace # 只啟用版本控制
43
+ node dist/index.js -c avf --workspace /path/to/workspace # admin + VCS + forum
44
+ node dist/index.js -c aftw --workspace /path/to/workspace # admin + forum + tickets + wiki
45
+ node dist/index.js -c A --workspace /path/to/workspace # 全部
41
46
  ```
42
47
 
43
- After `npm link` / a global install the same binary is on `PATH` as `fossil-scm`:
48
+ `npm link` 或全域安裝後,同一個執行檔以 `fossil-scm` 出現在 `PATH` 上:
44
49
 
45
50
  ```bash
46
- fossil-scm -c avf --repository /path/to/workspace
51
+ fossil-scm -c avf --workspace /path/to/workspace
47
52
  ```
48
53
 
49
- ### Selective enabling from an MCP client
54
+ ### 從 MCP 客戶端選擇性啟用
50
55
 
51
- Point several client entries at the same binary, each with its own letters. Every entry becomes an
52
- independent MCP server process with its own tool list:
56
+ 把多個客戶端項目指向同一個執行檔,各自帶自己的字母。每個項目都是獨立的 MCP 伺服器行程,有各自的工具清單:
53
57
 
54
58
  ```json
55
59
  {
56
60
  "mcpServers": {
57
61
  "fossil-admin": {
58
62
  "command": "node",
59
- "args": ["/abs/path/fossil-scm/dist/index.js", "-c", "a", "--repository", "/path/to/workspace"]
63
+ "args": ["/abs/path/fossil-scm/dist/index.js", "-c", "a", "--workspace", "/path/to/workspace"]
60
64
  },
61
65
  "fossil-vcs": {
62
66
  "command": "node",
63
- "args": ["/abs/path/fossil-scm/dist/index.js", "-c", "v", "--repository", "/path/to/workspace"]
67
+ "args": ["/abs/path/fossil-scm/dist/index.js", "-c", "v", "--workspace", "/path/to/workspace"]
64
68
  },
65
69
  "fossil-forum": {
66
70
  "command": "node",
67
- "args": ["/abs/path/fossil-scm/dist/index.js", "-c", "f", "--repository", "/path/to/workspace"]
71
+ "args": ["/abs/path/fossil-scm/dist/index.js", "-c", "f", "--workspace", "/path/to/workspace"]
68
72
  },
69
73
  "fossil-tickets": {
70
74
  "command": "node",
71
- "args": ["/abs/path/fossil-scm/dist/index.js", "-c", "t", "--repository", "/path/to/workspace"]
75
+ "args": ["/abs/path/fossil-scm/dist/index.js", "-c", "t", "--workspace", "/path/to/workspace"]
72
76
  },
73
77
  "fossil-wiki": {
74
78
  "command": "node",
75
- "args": ["/abs/path/fossil-scm/dist/index.js", "-c", "w", "--repository", "/path/to/workspace"]
79
+ "args": ["/abs/path/fossil-scm/dist/index.js", "-c", "w", "--workspace", "/path/to/workspace"]
76
80
  },
77
81
  "fossil-chat": {
78
82
  "command": "node",
79
- "args": ["/abs/path/fossil-scm/dist/index.js", "-c", "c", "--repository", "/path/to/workspace"]
83
+ "args": ["/abs/path/fossil-scm/dist/index.js", "-c", "c", "--workspace", "/path/to/workspace"]
80
84
  }
81
85
  }
82
86
  }
83
87
  ```
84
88
 
85
- The name reported during the handshake follows the selection: `fossil-scm-a`, `fossil-scm-v`, `fossil-scm-f`,
86
- `fossil-scm-t`, `fossil-scm-w`, `fossil-scm-c` for a single group, plain `fossil-scm` when several are combined.
89
+ 握手回報的名稱跟著選擇走:單一組是 `fossil-scm-a`、`fossil-scm-v`、`fossil-scm-f`、`fossil-scm-t`、
90
+ `fossil-scm-w`、`fossil-scm-c`,多組合併時是單純的 `fossil-scm`。
87
91
 
88
- ## Configuration
92
+ ## 設定
89
93
 
90
- | CLI flag | Meaning |
94
+ | 命令列旗標 | 意義 |
91
95
  | --- | --- |
92
- | `-c, --capability LIST` | One value with the capability initials together: `a` `v` `f` `t` `w` `c` → `-c avf`; a single capital `A` for everything. No separators, no repeated flag. Default: `FOSSIL_CAPABILITIES`, else all |
93
- | `--repository DIR` (also `--workspace`, `--cwd`, `-R`) | Default workspace for tool calls that omit `cwd` |
94
- | `--verbose`, `-v` | Diagnostics on stderr (stdout is reserved for the protocol) |
95
- | `--help`, `-h` | Usage, capability table and examples |
96
+ | `-c, --capability LIST` | 能力首字母寫在同一個值裡:`a` `v` `f` `t` `w` `c` → `-c avf`;單一大寫 `A` 為全部。無分隔符、不可重複。預設取 `FOSSIL_CAPABILITIES`,再無則 `A` |
97
+ | `--workspace DIR` | 工具呼叫省略 `workspace` 時的預設工作區;未給時用行程工作目錄 |
98
+ | `--verbose`, `-v` | 在 stderr 輸出診斷訊息(stdout 保留給協定) |
99
+ | `--help`, `-h` | 用法、能力表與範例 |
96
100
 
97
- | Environment variable | Default | Meaning |
101
+ | 環境變數 | 預設 | 意義 |
98
102
  | --- | --- | --- |
99
- | `FOSSIL_CAPABILITIES` | all | Default capability letters (same syntax as `--capability`, e.g. `avf` or `A`) |
100
- | `FOSSIL_WORKSPACE` / `FOSSIL_CWD` | cwd | Default workspace |
101
- | `FOSSIL_BIN` | `fossil` | Fossil executable (full path works too) |
102
- | `FOSSIL_TIMEOUT_MS` | `30000` | Timeout for regular commands |
103
- | `FOSSIL_NETWORK_TIMEOUT_MS` | `600000` | Timeout for `clone`, `chat send`, `chat pull` |
104
- | `FOSSIL_MAX_OUTPUT_CHARS` | `120000` | Output truncation threshold (head + tail are kept) |
105
- | `FOSSIL_MAX_CAPTURE_BYTES` | `4194304` | Per-stream capture cap |
106
- | `FOSSIL_REPOS_DIR` | `.fossil_repositories` | Sibling folder holding auto-derived `*.fossil` databases |
107
-
108
- Repository databases resolve to `<parent-of-workspace>/.fossil_repositories/<name>.fossil` unless an
109
- explicit path is passed to a tool.
110
-
111
- ## Tools
112
-
113
- **`a` Admin (5)** — `fossil_init`, `fossil_open`, `fossil_close`, `fossil_clone`, `fossil_settings`
114
-
115
- **`v` VCS (20)** — `fossil_status`, `fossil_diff`, `fossil_cat`, `fossil_finfo`, `fossil_revert`,
116
- `fossil_stash`, `fossil_tag`, `fossil_addremove`, `fossil_commit`, `fossil_add`, `fossil_rm`, `fossil_mv`,
117
- `fossil_extras`, `fossil_clean`, `fossil_timeline`, `fossil_info`, `fossil_branch`, `fossil_merge`,
118
- `fossil_update`, `fossil_undo`
119
-
120
- **`f` Forum (3)** — `fossil_forum_list`, `fossil_forum_read`, `fossil_forum_search`
121
-
122
- **`t` Tickets (3)** — `fossil_ticket_list`, `fossil_ticket_create`, `fossil_ticket_update`
123
-
124
- **`w` Wiki (3)** — `fossil_wiki_ls`, `fossil_wiki_read`, `fossil_wiki_write`
125
-
126
- **`c` Chat (4)** — `fossil_chat_url`, `fossil_chat_send`, `fossil_chat_pull`, `fossil_chat_read`
127
-
128
- `fossil_init` / `fossil_open` (capability `a`) apply the recommended settings automatically
129
- (`crlf-glob='*'`, `dotfiles=1`, `ignore-glob`, `binary-glob`) and create + stage `.editorconfig` when it is
130
- missing. VCS and the content capabilities (`v`, `f`, `t`, `w`, `c`) expect an already opened check-out.
131
-
132
- ### Capability notes
133
-
134
- - **Forum is read-only.** Fossil 2.x has no CLI or JSON API to create forum posts — that lives in the web
135
- UI — so the tools read the `F` artifacts Fossil stores in `event`/`blob` (via `fossil sql --readonly`)
136
- and never write. `fossil_forum_read` accepts any post hash (prefixes work) and prints the whole thread.
137
- - **Chat reads local data.** `fossil_chat_pull` downloads the chatroom into the clone (setup privilege
138
- required on the server) or into an archive with `out`; `fossil_chat_read` reads either the clone or that
139
- archive. `fossil_chat_send` needs a reachable remote and stored credentials.
140
- - **SQL is always read-only and JSON-parsed.** `fossil sql --readonly -json` keeps values typed; SQL errors
141
- are detected even though the sqlite shell exits with status 0.
142
-
143
- ## What changed compared with the Python version
144
-
145
- - **Selectable capabilities, one binary.** Tools are registered per capability (`src/capabilities.ts`) and
146
- `--capability` takes the capability initials written together in one value (`avf`, `aftw`, single capital `A`
147
- for all) or `FOSSIL_CAPABILITIES`, so clients can enable only the groups they want.
148
- - **No interactive hangs.** `spawn` without a shell, stdin is always closed, `SIGTERM`→`SIGKILL` escalation,
149
- and per-command timeouts. The commit flow still answers the "commit anyhow" prompt with `a`.
150
- - **Fewer process spawns.** The four auto-config `fossil sql` calls collapse into one multi-statement
151
- invocation; `fossil_status` runs `status` + `extra` in parallel; `fossil_wiki_write` picks `create` vs
152
- `commit` from one page listing instead of failing a `commit` first.
153
- - **Real error semantics.** Failures return `isError: true` with exit code, stdout/stderr and the executed
154
- command, instead of a string the caller has to sniff for `"ERROR:"`.
155
- - **Validated inputs.** Every tool declares a Zod schema (enums for sub-commands, integer limits, defaulted
156
- flags), so the model gets accurate schemas and invalid arguments are rejected before spawning fossil.
157
- - **Safer SQL.** Auto-config values are escaped instead of being interpolated raw, and query tools open the
158
- repository with `--readonly`.
159
- - **Bounded output.** Long command output is truncated head + tail, and per-stream capture is capped.
160
- - **Structure + tests.** `src/config.ts` (env/flags), `src/core/*` (process runner, SQL, path resolution),
161
- `src/tools/*` (tool groups), `src/capabilities.ts`, `src/server.ts`, `src/cli.ts`, `src/index.ts`.
162
- `pnpm smoke` drives the real stdio interface for every capability initial and combination.
163
-
164
- ## Development
103
+ | `FOSSIL_CAPABILITIES` | `A` | 預設能力字母(語法同 `--capability`,例如 `avf` 或 `A`) |
104
+ | `FOSSIL_WORKSPACE` | 行程 cwd | 預設工作區 |
105
+ | `FOSSIL_BIN` | `fossil` | Fossil 執行檔(也可給完整路徑) |
106
+ | `FOSSIL_TIMEOUT_MS` | `30000` | 一般命令的逾時 |
107
+ | `FOSSIL_NETWORK_TIMEOUT_MS` | `600000` | 網路命令的逾時:`clone`、`push`/`pull`/`sync`、`config` 的網路動作、`chat send`/`chat pull` |
108
+ | `FOSSIL_MAX_OUTPUT_CHARS` | `120000` | 輸出截斷門檻(保留首尾) |
109
+ | `FOSSIL_MAX_CAPTURE_BYTES` | `4194304` | 每條串流的捕獲上限 |
110
+
111
+ `fossil_init` / `fossil_open` 從 `repository` 參數取得倉庫位置(絕對路徑,或相對 workspace);路徑原樣使用。
112
+
113
+ ## 工具
114
+
115
+ **`a` Admin(11)** — `fossil_init`、`fossil_open`、`fossil_close`、`fossil_clone`、`fossil_settings`、
116
+ `fossil_remote`、`fossil_push`、`fossil_pull`、`fossil_sync`、`fossil_rebuild`、`fossil_config`
117
+
118
+ **`v` VCS(40)** — `fossil_status`、`fossil_diff`、`fossil_cat`、`fossil_finfo`、`fossil_revert`、
119
+ `fossil_stash`、`fossil_tag`、`fossil_addremove`、`fossil_commit`、`fossil_add`、`fossil_rm`、`fossil_mv`、
120
+ `fossil_extras`、`fossil_clean`、`fossil_timeline`、`fossil_info`、`fossil_branch`、`fossil_merge`、
121
+ `fossil_update`、`fossil_undo`、`fossil_changes`、`fossil_annotate`、`fossil_grep`、`fossil_whatis`、
122
+ `fossil_merge_base`、`fossil_leaves`、`fossil_descendants`、`fossil_unpublished`、`fossil_ls`、
123
+ `fossil_search`、`fossil_artifact`、`fossil_describe`、`fossil_archive`、`fossil_unversioned`、
124
+ `fossil_touch`、`fossil_amend`、`fossil_patch`、`fossil_bisect`、`fossil_sql`、
125
+ `fossil_ignore_from_gitignore`
126
+
127
+ **`f` Forum(3)** — `fossil_forum_list`、`fossil_forum_read`、`fossil_forum_search`
128
+
129
+ **`t` Tickets(4)** — `fossil_ticket_list`、`fossil_ticket_show`、`fossil_ticket_create`、
130
+ `fossil_ticket_update`
131
+
132
+ **`w` Wiki(3)** — `fossil_wiki_ls`、`fossil_wiki_read`、`fossil_wiki_write`
133
+
134
+ **`c` Chat(4)** — `fossil_chat_url`、`fossil_chat_send`、`fossil_chat_pull`、`fossil_chat_read`
135
+
136
+ `fossil_init`(能力 `a`)只建倉庫資料庫,`fossil_open` 只建 check-out。組態歸專案所有
137
+ (`.fossil-settings/`、`.editorconfig` …)。VCS 與內容類能力(`v`、`f`、`t`、`w`、`c`)要求 `workspace`
138
+ 裡已有開啟的 check-out。
139
+
140
+ ### 能力說明
141
+
142
+ - **Forum 只讀。** Fossil 2.x 沒有建立論壇貼文的 CLI 或 JSON 介面——那在 Web UI 裡——所以工具改讀 Fossil
143
+ 存在 `event`/`blob` 的 `F` 工件(透過 `fossil sql --readonly`)。`fossil_forum_read` 接受任何貼文雜湊
144
+ (前綴可用)並印出整串討論。
145
+ - **Chat 讀本地資料。** `fossil_chat_pull` 把聊天室下載進 clone(伺服器端需要 setup 權限),或用 `out`
146
+ 下載成封存檔;`fossil_chat_read` 讀 clone 或該封存檔。`fossil_chat_send` 需要可連線的遠端與已存的憑證。
147
+ - **SQL 一律只讀並以 JSON 解析。** `fossil sql --readonly -json` 保留值類型;sqlite shell 即使以狀態 0
148
+ 結束,SQL 錯誤仍會被偵測。
149
+
150
+ 伺服器也註冊 MCP 提示(`prompts/list` / `prompts/get`):`fossil-review-changes`、`fossil-commit-workflow`、
151
+ `fossil-ignore-conversion`、`fossil-trace-change`、`fossil-bisect-hunt`、`fossil-sync-remote`、
152
+ `fossil-repair-repository`、`fossil-ticket-triage`,
153
+ 把常用的多步流程寫成一段指示交給模型。
154
+
155
+ 逐工具說明(參數、真實 argv、真實輸出、邊界情況)在 [`docs/`](./docs/README.md):
156
+ [admin](./docs/admin.md)、[VCS](./docs/vcs.md)、[forum](./docs/forum.md)、[tickets](./docs/tickets.md)、
157
+ [wiki](./docs/wiki.md)、[chat](./docs/chat.md)、[prompts](./docs/prompts.md)。
158
+
159
+ ## 與 Python 版本的差異
160
+
161
+ - **可選能力、單一執行檔。** 工具按能力組註冊(`src/capabilities.ts`:Admin、VCS、Forum、Tickets、Wiki、
162
+ Chat),`--capability` 取寫在同一值裡的首字母(`avf`、`aftw`、單一大寫 `A` 為全部)或 `FOSSIL_CAPABILITIES`,
163
+ 客戶端只啟用需要的部分。
164
+ - **不會互動卡住。** 不經 shell 的 `spawn`、stdin 一律關閉、`SIGTERM`→`SIGKILL` 升級、逐命令逾時。
165
+ 提交流程仍以 `a` 回答 "commit anyhow" 提示。
166
+ - **組態歸專案所有。** `fossil_init` 建資料庫、`fossil_open` 建 check-out;設定存在倉庫自己的
167
+ `.fossil-settings/*`,同一個倉庫在每個客戶端行為一致。
168
+ - **更少的行程。** `fossil_status` 併發跑 `status` + `extra`;`fossil_wiki_write` 用一次頁面列表決定
169
+ `create` 還是 `commit`,不用先失敗一次 `commit`。
170
+ - **真實的錯誤語義。** 失敗回傳 `isError: true`,附退出碼、stdout/stderr 與實際執行的命令,呼叫方不必從
171
+ 字串裡嗅 `"ERROR:"`。Admin 另外補上提示:`fossil_init` 建父目錄、`fossil_settings` 可讀寫清除並限定範圍
172
+ (`unset`、`global`、`exact`),沒有 check-out 時加警告,`fossil_close` 在未提交變更時指向 `force: true`,
173
+ admin 密碼在 `reveal_secrets: true` 之外一律遮蔽。
174
+ - **輸入驗證。** 每個工具都宣告 Zod schema(子命令用 enum、整數上限、帶預設的旗標),模型拿到準確的 schema,
175
+ 非法參數在 spawn fossil 之前就被拒絕。
176
+ - **更安全的 SQL。** 查詢類工具以 `--readonly` 開啟倉庫,值在插值前轉義,並偵測 sqlite shell
177
+ 「錯誤走 stderr、退出碼卻為 0」的行為。
178
+ - **有界輸出。** 長輸出截首尾,每條串流的捕獲有上限。
179
+ - **結構與測試。** `src/config.ts`(env/旗標)、`src/core/*`(行程執行器、SQL、路徑解析)、
180
+ `src/tools/*`(工具組)、`src/capabilities.ts`、`src/server.ts`、`src/cli.ts`、`src/index.ts`,
181
+ 由 `tsconfig.build.json` 建置到 `dist`。`pnpm smoke` 驅動真實 stdio 介面,涵蓋每個能力首字母與組合。
182
+
183
+ ## 開發
165
184
 
166
185
  ```bash
167
- pnpm build # compile src -> dist
168
- pnpm typecheck # tsc --noEmit (tsconfig.build.json)
169
- pnpm smoke # end-to-end stdio test (each initial, combinations, env selection, bad input)
186
+ pnpm build # 編譯 src -> dist(prebuild 會先清空 dist)
187
+ pnpm typecheck # tsc(tsconfig.json:strict、erasable syntax only、noEmit)
188
+ pnpm smoke # 端到端 stdio 測試(各首字母、組合、env 選擇、錯誤輸入)
170
189
  pnpm test # typecheck + build + smoke
171
- pnpm pack # build the publishable tarball
190
+ pnpm pack # prepack 重建 dist 後產出 tarball
172
191
  ```
192
+
193
+ `dist` 只有 `.js` 檔——沒有 source map、沒有 `.d.ts`(`tsconfig.build.json` 設 `sourceMap: false` 且不產生
194
+ 宣告檔,`prebuild` / `prepack` 從零重建 `dist`)。tarball 是 `dist` 加上 `README.md` 與 `LICENSE`。
195
+ 專案層的 `.npmrc`(registry token)已被忽略。
196
+
197
+ ## 授權
198
+
199
+ BSD 3-Clause — 見 [LICENSE](./LICENSE)。Copyright (c) 2026 ri-fumo.
@@ -22,15 +22,15 @@ export const CAPABILITIES = {
22
22
  a: {
23
23
  id: 'a',
24
24
  title: 'Admin',
25
- description: 'Repository lifecycle (init/open/close/clone/settings)',
26
- toolCount: 5,
25
+ description: 'Repository lifecycle (init/open/close/clone/settings), remote URLs and sync',
26
+ toolCount: 11,
27
27
  register: registerAdminTools,
28
28
  },
29
29
  v: {
30
30
  id: 'v',
31
31
  title: 'VCS',
32
- description: 'All version-control commands',
33
- toolCount: 20,
32
+ description: 'Version control: working tree, history, commits, branches, queries and ignore rules',
33
+ toolCount: 40,
34
34
  register: registerVersionControlTools,
35
35
  },
36
36
  f: {
@@ -43,8 +43,8 @@ export const CAPABILITIES = {
43
43
  t: {
44
44
  id: 't',
45
45
  title: 'Tickets',
46
- description: 'Ticket reports, creation and field updates',
47
- toolCount: 3,
46
+ description: 'Ticket reports, filtered views, creation and field updates',
47
+ toolCount: 4,
48
48
  register: registerTicketTools,
49
49
  },
50
50
  w: {
@@ -73,4 +73,3 @@ export function allCapabilities() {
73
73
  export function toolCountOf(ids) {
74
74
  return ids.reduce((total, id) => total + CAPABILITIES[id].toolCount, 0);
75
75
  }
76
- //# sourceMappingURL=capabilities.js.map
package/dist/cli.js CHANGED
@@ -1,9 +1,9 @@
1
1
  import { serveStdio } from '@modelcontextprotocol/server/stdio';
2
2
  import { CAPABILITIES, CAPABILITY_IDS, allCapabilities, isCapabilityId, toolCountOf, } from './capabilities.js';
3
- import { SERVER_NAME, SERVER_VERSION, getDefaultCwd, setDefaultCwd } from './config.js';
3
+ import { SERVER_NAME, SERVER_VERSION, getDefaultWorkspace, setDefaultWorkspace } from './config.js';
4
4
  import { createServer } from './server.js';
5
- const VALUE_FLAGS = new Set(['--repository', '--workspace', '--cwd', '-R', '--capability', '-c']);
6
- const CWD_FLAGS = new Set(['--repository', '--workspace', '--cwd', '-R']);
5
+ const WORKSPACE_FLAG = '--workspace';
6
+ const CAPABILITY_FLAGS = new Set(['--capability', '-c']);
7
7
  /** Thrown for invalid command lines; callers print the message plus the help. */
8
8
  export class UsageError extends Error {
9
9
  }
@@ -40,11 +40,12 @@ function addCapabilities(spec, selected) {
40
40
  *
41
41
  * `--capability` takes capability initials written together (`avf`, `twc`) or a
42
42
  * single capital `A` for everything; when it is absent the list comes from
43
- * `FOSSIL_CAPABILITIES` (or every capability).
44
- * `--repository DIR` is consumed here so it can never reach the MCP transport.
43
+ * `FOSSIL_CAPABILITIES` (or every capability). `--workspace DIR` (or
44
+ * `FOSSIL_WORKSPACE`) sets the default workspace; otherwise tool calls fall
45
+ * back to the process working directory.
45
46
  */
46
47
  export function parseArgs(argv, env = process.env) {
47
- let cwd = env.FOSSIL_WORKSPACE?.trim() || env.FOSSIL_CWD?.trim() || undefined;
48
+ let workspace = env.FOSSIL_WORKSPACE?.trim() || undefined;
48
49
  let verbose = false;
49
50
  let help = false;
50
51
  const selected = new Set();
@@ -63,8 +64,9 @@ export function parseArgs(argv, env = process.env) {
63
64
  }
64
65
  const equalsIndex = arg.indexOf('=');
65
66
  const flagName = equalsIndex > 0 ? arg.slice(0, equalsIndex) : arg;
66
- if (!VALUE_FLAGS.has(flagName))
67
+ if (flagName !== WORKSPACE_FLAG && !CAPABILITY_FLAGS.has(flagName)) {
67
68
  continue; // Unknown flags are ignored (MCP clients add their own).
69
+ }
68
70
  const inlineValue = equalsIndex > 0 ? arg.slice(equalsIndex + 1) : undefined;
69
71
  const value = inlineValue ?? argv[index + 1];
70
72
  if (inlineValue === undefined)
@@ -72,8 +74,8 @@ export function parseArgs(argv, env = process.env) {
72
74
  if (value === undefined || value.startsWith('-')) {
73
75
  throw new UsageError(`missing value for ${flagName}.`);
74
76
  }
75
- if (CWD_FLAGS.has(flagName)) {
76
- cwd = value;
77
+ if (flagName === WORKSPACE_FLAG) {
78
+ workspace = value;
77
79
  }
78
80
  else {
79
81
  // Exactly one value: all letters belong together, e.g. -c avf.
@@ -91,7 +93,7 @@ export function parseArgs(argv, env = process.env) {
91
93
  if (capabilities.length === 0) {
92
94
  throw new UsageError("no capability selected; use --capability (e.g. 'avf') or FOSSIL_CAPABILITIES, or 'A'.");
93
95
  }
94
- return { cwd, capabilities, verbose, help };
96
+ return { workspace, capabilities, verbose, help };
95
97
  }
96
98
  export function helpText() {
97
99
  const rows = CAPABILITY_IDS.map((id) => {
@@ -101,16 +103,16 @@ export function helpText() {
101
103
  return [
102
104
  `${SERVER_NAME} MCP server v${SERVER_VERSION}`,
103
105
  '',
104
- `Usage: ${SERVER_NAME} [--capability LETTERS] [--repository DIR] [--verbose]`,
106
+ `Usage: ${SERVER_NAME} [--capability LETTERS] [--workspace DIR] [--verbose]`,
105
107
  '',
106
108
  'Options:',
107
109
  ' -c, --capability LIST Capability initials written together in one value:',
108
110
  ' a(Admin) v(VCS) f(Forum) t(Tickets) w(Wiki) c(Chat),',
109
111
  ' e.g. "-c avf". A capital A selects everything.',
110
112
  ' Default: FOSSIL_CAPABILITIES, else every capability.',
111
- ' Each selected group is served as its own MCP server instance.',
112
- ' --repository DIR Default workspace for every tool call',
113
- ' (aliases: --workspace, --cwd, -R)',
113
+ ' Each selected group contributes its tools to this one server.',
114
+ ' --workspace DIR Default workspace for every tool call.',
115
+ ' Without it the process working directory is used.',
114
116
  ' -v, --verbose Log diagnostics to stderr',
115
117
  ' -h, --help Show this help',
116
118
  '',
@@ -118,14 +120,17 @@ export function helpText() {
118
120
  ...rows,
119
121
  '',
120
122
  'Examples:',
121
- ` ${SERVER_NAME} -c v # version control only (20 tools)`,
122
- ` ${SERVER_NAME} -c avf # admin + VCS + forum (28 tools)`,
123
- ` ${SERVER_NAME} -c aftw # admin + forum + tickets + wiki (14 tools)`,
124
- ` ${SERVER_NAME} -c A # everything (38 tools)`,
123
+ ` ${SERVER_NAME} -c v # version control only (40 tools)`,
124
+ ` ${SERVER_NAME} -c avf # admin + VCS + forum (54 tools)`,
125
+ ` ${SERVER_NAME} -c aftw # admin + forum + tickets + wiki (21 tools)`,
126
+ ` ${SERVER_NAME} -c A # everything (65 tools)`,
127
+ '',
128
+ 'Prompts: fossil-review-changes, fossil-commit-workflow, fossil-ignore-conversion,',
129
+ ' fossil-trace-change, fossil-bisect-hunt, fossil-sync-remote,',
130
+ ' fossil-repair-repository, fossil-ticket-triage',
125
131
  '',
126
- 'Environment: FOSSIL_CAPABILITIES, FOSSIL_WORKSPACE, FOSSIL_CWD, FOSSIL_BIN,',
127
- ' FOSSIL_TIMEOUT_MS, FOSSIL_NETWORK_TIMEOUT_MS, FOSSIL_MAX_OUTPUT_CHARS,',
128
- ' FOSSIL_REPOS_DIR',
132
+ 'Environment: FOSSIL_CAPABILITIES, FOSSIL_WORKSPACE, FOSSIL_BIN, FOSSIL_TIMEOUT_MS,',
133
+ ' FOSSIL_NETWORK_TIMEOUT_MS, FOSSIL_MAX_OUTPUT_CHARS, FOSSIL_MAX_CAPTURE_BYTES',
129
134
  '',
130
135
  ].join('\n');
131
136
  }
@@ -152,9 +157,9 @@ export function run(options = {}) {
152
157
  process.stderr.write(helpText());
153
158
  return;
154
159
  }
155
- setDefaultCwd(parsed.cwd);
160
+ setDefaultWorkspace(parsed.workspace);
156
161
  log(parsed.verbose, `starting v${SERVER_VERSION} | capabilities: ${parsed.capabilities.join(',')} (${toolCountOf(parsed.capabilities)} tools) ` +
157
- `| workspace: ${getDefaultCwd() ?? process.cwd()}`);
162
+ `| workspace: ${getDefaultWorkspace() ?? process.cwd()}`);
158
163
  const handle = serveStdio(() => createServer({ capabilities: parsed.capabilities }), {
159
164
  onerror: (error) => process.stderr.write(`[${SERVER_NAME}] transport error: ${error.message}\n`),
160
165
  });
@@ -165,4 +170,3 @@ export function run(options = {}) {
165
170
  process.once('SIGINT', () => shutdown('SIGINT'));
166
171
  process.once('SIGTERM', () => shutdown('SIGTERM'));
167
172
  }
168
- //# sourceMappingURL=cli.js.map
package/dist/config.js CHANGED
@@ -9,14 +9,7 @@ function readPositiveInt(name, fallback) {
9
9
  }
10
10
  /** Server/product name. The fossil *binary* stays `fossil` (see FOSSIL_BIN). */
11
11
  export const SERVER_NAME = 'fossil-scm';
12
- export const SERVER_VERSION = '0.1.0';
13
- export const SERVER_INSTRUCTIONS = [
14
- 'MCP server exposing 31 tools for complete Fossil SCM automation and integration',
15
- '(repositories, check-outs, version control, tickets and wiki).',
16
- 'Every tool accepts an optional `cwd` pointing at the check-out or workspace directory;',
17
- 'when omitted the server default is used (set with --repository, FOSSIL_WORKSPACE or FOSSIL_CWD).',
18
- 'Repository database files are auto-resolved to the sibling ".<repos dir>" folder when no explicit db_name is given.',
19
- ].join(' ');
12
+ export const SERVER_VERSION = '0.1.3';
20
13
  /**
21
14
  * The Fossil executable. The command is named `fossil`; only the server/product
22
15
  * name is written `fossil-scm`. Override with FOSSIL_BIN (e.g. a full path on Windows).
@@ -30,32 +23,14 @@ export const NETWORK_TIMEOUT_MS = readPositiveInt('FOSSIL_NETWORK_TIMEOUT_MS', 6
30
23
  export const MAX_OUTPUT_CHARS = readPositiveInt('FOSSIL_MAX_OUTPUT_CHARS', 120_000);
31
24
  /** Hard cap on bytes buffered per stream (protects the process from runaway commands). */
32
25
  export const MAX_CAPTURE_BYTES = readPositiveInt('FOSSIL_MAX_CAPTURE_BYTES', 4 * 1024 * 1024);
33
- /** Name of the sibling directory that holds auto-derived repository databases. */
34
- export const REPOS_DIR_NAME = env.FOSSIL_REPOS_DIR?.trim() || '.fossil_repositories';
35
- /** Settings applied automatically right after `init` / `open`. */
36
- export const AUTO_SETTINGS = [
37
- ['crlf-glob', '*'],
38
- ['dotfiles', '1'],
39
- ['ignore-glob', 'deschide-ui-fossil.bat,Thumbs.db,.suo,.user,bin/,obj/,*__pycache__*,*.pyc,.venv/'],
40
- ['binary-glob', '*.pcsave,*.png,*.jpg,*.zip,*.exe,*.dll,*.tar.gz'],
41
- ];
42
- /** Content written to `.editorconfig` when a new check-out is opened. */
43
- export const EDITORCONFIG_CONTENT = [
44
- '[*]',
45
- 'end_of_line = lf',
46
- 'insert_final_newline = true',
47
- 'trim_trailing_whitespace = true',
48
- '',
49
- ].join('\n');
50
- let defaultCwd = env.FOSSIL_WORKSPACE?.trim() || env.FOSSIL_CWD?.trim() || undefined;
51
- /** Sets the workspace used when a tool call omits `cwd`. */
52
- export function setDefaultCwd(dir) {
26
+ let defaultWorkspace = env.FOSSIL_WORKSPACE?.trim() || undefined;
27
+ /** Sets the workspace used when a tool call omits `workspace`. */
28
+ export function setDefaultWorkspace(dir) {
53
29
  const trimmed = dir?.trim();
54
30
  if (trimmed)
55
- defaultCwd = path.resolve(trimmed);
31
+ defaultWorkspace = path.resolve(trimmed);
56
32
  }
57
33
  /** Reads the configured default workspace, if any. */
58
- export function getDefaultCwd() {
59
- return defaultCwd;
34
+ export function getDefaultWorkspace() {
35
+ return defaultWorkspace;
60
36
  }
61
- //# sourceMappingURL=config.js.map