@stellar_ai/mcp_fossil_scm 0.1.2 → 0.2.0

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