@stellar_ai/mcp_fossil_scm 0.1.2 → 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.
package/docs/wiki.md ADDED
@@ -0,0 +1,140 @@
1
+ # Wiki 能力(`-c w`)工具說明
2
+
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.1.3` 及之後,fossil 2.21 實測。
4
+
5
+ `-c w` 註冊 3 個工具:`fossil_wiki_ls` / `fossil_wiki_read` / `fossil_wiki_write`。
6
+ (組合啟用:`-c aw`。)
7
+
8
+ ---
9
+
10
+ ## 1. 通用約定
11
+
12
+ - 都要 **check-out**;僅有倉庫檔案時報 fossil 的 `use --repository or -R to specify the repository database`。
13
+ - `workspace` 語義見 `docs/admin.md` §2.1。
14
+ - 頁面名大小寫不敏感地比較(fossil 內部會規範化),工具在寫入前用一次 `fossil wiki ls` 判斷頁面是否存在。
15
+
16
+ ---
17
+
18
+ ## 2. `fossil_wiki_ls`
19
+
20
+ ```bash
21
+ fossil wiki ls
22
+ ```
23
+
24
+ | 參數 | 類型 | 必填/預設 | 說明 |
25
+ | --- | --- | --- | --- |
26
+ | `workspace` | string | 見 admin §2.1 | check-out 目錄 |
27
+
28
+ 真實輸出(每行一個頁面名):
29
+
30
+ ```
31
+ Home
32
+ ```
33
+
34
+ 空倉庫 → `No wiki pages.`
35
+
36
+ ---
37
+
38
+ ## 3. `fossil_wiki_read`
39
+
40
+ ```bash
41
+ fossil wiki export <page_name>
42
+ ```
43
+
44
+ 匯出**原始** wiki 文字(markdown 與 fossil 的 `[[link]]` 混排語法原樣保留)。
45
+
46
+ | 參數 | 類型 | 必填/預設 | 說明 |
47
+ | --- | --- | --- | --- |
48
+ | `page_name` | string | **必填** | 要讀取的頁面名 |
49
+ | `workspace` | string | 見 admin §2.1 | check-out 目錄 |
50
+
51
+ 真實輸出(寫入了 `# Hello\n\nsecond\n` 的頁面):
52
+
53
+ ```
54
+ # Hello
55
+
56
+ second
57
+ ```
58
+
59
+ 頁面不存在時(fossil 原文):
60
+
61
+ ```
62
+ ERROR: Fossil command failed (exit code 1).
63
+ wiki page [Nope] not found
64
+ COMMAND: fossil wiki export Nope
65
+ WORKSPACE: /tmp/tw
66
+ ```
67
+
68
+ ---
69
+
70
+ ## 4. `fossil_wiki_write`
71
+
72
+ 建立或覆蓋頁面。流程:把內容寫進臨時目錄裡的 `page.md`,再呼叫
73
+
74
+ ```bash
75
+ fossil wiki create <page_name> <tmpfile> # 頁面不存在
76
+ fossil wiki commit <page_name> <tmpfile> # 頁面已存在
77
+ ```
78
+
79
+ | 參數 | 類型 | 必填/預設 | 說明 |
80
+ | --- | --- | --- | --- |
81
+ | `page_name` | string | **必填** | 頁面名,不存在時自動建立 |
82
+ | `content` | string | **必填** | 完整頁面內容(整頁覆蓋) |
83
+ | `workspace` | string | 見 admin §2.1 | check-out 目錄 |
84
+
85
+ 真實輸出——新建:
86
+
87
+ ```
88
+ Created new wiki page Home.
89
+
90
+ Wiki page 'Home' saved.
91
+ ```
92
+
93
+ 真實輸出——覆蓋:
94
+
95
+ ```
96
+ Updated wiki page Home.
97
+
98
+ Wiki page 'Home' saved.
99
+ ```
100
+
101
+ 實現要點(`src/tools/wiki.ts`):
102
+
103
+ - 先用 `fossil wiki ls` 拿到頁面集合(**小寫化**後比較),據此選 `create` 或 `commit`,避免“先 commit 失敗再 create”的兩次往返。
104
+ - `create` 失敗時回退一次 `commit`(頁面可能在這期間被別人建立)。
105
+ - 列表不可讀(例如不在 check-out 裡)時先試 `commit`,命中 `MISSING_PAGE_PATTERN`
106
+ (`no such wiki page` / `not found` / `doesn't exist` / `does not exist`)再 `create`。
107
+ - 臨時目錄用 `mkdtemp(path.join(tmpdir(), 'fossil-wiki-'))`,`finally` 裡 `rm -rf` 清理,內容不落進 workspace。
108
+
109
+ ---
110
+
111
+ ## 5. 典型流程
112
+
113
+ ```
114
+ fossil_wiki_write { page_name: 'Home', content: '# Hello\n\n歡迎\n' }
115
+ fossil_wiki_write { page_name: 'Design', content: '# 設計\n\n見 [[Home]]\n' }
116
+ fossil_wiki_ls
117
+ fossil_wiki_read { page_name: 'Design' }
118
+ ```
119
+
120
+ wiki 的每次寫入都是一條 `W` 事件,`fossil_timeline` 可見。
121
+
122
+ ---
123
+
124
+ ## 6. 已知邊界
125
+
126
+ 1. **`content` 是整頁覆蓋**;要改一段必須先 `fossil_wiki_read` 再整體寫回。
127
+ 2. **頁面名原樣傳給 fossil**(空格/下劃線/大小寫保持原樣);非法名由 fossil 判定。
128
+ 3. **不支援刪除頁面**(fossil 也沒有直接 CLI)。
129
+ 4. **不支援附件/技術說明類頁面**:`wiki export` 只導主體文字。
130
+ 5. **臨時檔案在系統 tmp 中**;`FOSSIL_WORKSPACE` 的磁碟權限不影響它,但 `/tmp` 需要可寫。
131
+
132
+ ---
133
+
134
+ ## 7. 原始碼位置
135
+
136
+ | 檔案 | 內容 |
137
+ | --- | --- |
138
+ | `src/tools/wiki.ts` | 3 個工具 + `listWikiPages` / `writeWikiPage` / `MISSING_PAGE_PATTERN` |
139
+ | `src/core/fossil.ts` | `runFossil` / `renderOutcome` / `FossilOutcome` |
140
+ | `src/tools/common.ts` | `workspaceParam` |
package/package.json CHANGED
@@ -1,14 +1,15 @@
1
1
  {
2
2
  "name": "@stellar_ai/mcp_fossil_scm",
3
- "version": "0.1.2",
4
- "description": "Selective MCP servers for Fossil SCM: Admin, VCS, Forum, Tickets, Wiki and Chat",
3
+ "version": "0.1.3",
4
+ "description": "Capability-scoped MCP server for Fossil SCM: Admin, VCS, Forum, Tickets, Wiki and Chat",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
7
7
  "bin": {
8
8
  "fossil-scm": "dist/index.js"
9
9
  },
10
10
  "files": [
11
- "dist"
11
+ "dist",
12
+ "docs"
12
13
  ],
13
14
  "engines": {
14
15
  "node": ">=20"
@@ -37,12 +38,14 @@
37
38
  "author": "ri-fumo",
38
39
  "scripts": {
39
40
  "build": "tsc -p tsconfig.build.json",
40
- "typecheck": "tsc -p tsconfig.build.json --noEmit",
41
+ "typecheck": "tsc -p tsconfig.json",
41
42
  "start": "node dist/index.js",
42
43
  "dev": "pnpm build && node dist/index.js --verbose",
43
44
  "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
45
+ "prebuild": "pnpm clean",
44
46
  "smoke": "node scripts/smoke.mjs",
45
- "test": "pnpm typecheck && pnpm build && pnpm smoke",
46
- "prebuild": "pnpm clean"
47
+ "test": "pnpm typecheck && pnpm build && pnpm check:docs && pnpm smoke",
48
+ "link-local": "bash scripts/link-local.sh",
49
+ "check:docs": "node scripts/check-docs.mjs"
47
50
  }
48
51
  }