@stellar_ai/mcp_fossil_scm 0.2.1 → 0.2.2
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 +32 -30
- package/dist/capabilities.js +30 -22
- package/dist/cli.js +11 -11
- package/dist/config.js +1 -1
- package/dist/core/gitignore.js +7 -4
- package/dist/index.js +1 -1
- package/dist/prompts.js +28 -30
- package/dist/tools/admin.js +54 -54
- package/dist/tools/utils.js +237 -0
- package/dist/tools/version-control.js +1 -231
- package/docs/README.md +6 -5
- package/docs/admin.md +45 -43
- package/docs/chat.md +1 -1
- package/docs/forum.md +1 -1
- package/docs/prompts.md +4 -4
- package/docs/tickets.md +1 -1
- package/docs/utils.md +262 -0
- package/docs/vcs.md +28 -235
- package/docs/wiki.md +1 -1
- package/package.json +2 -2
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { z } from 'zod';
|
|
4
|
+
import { renderOutcome, resolveWorkspace, runFossil, truncateOutput } from '../core/fossil.js';
|
|
5
|
+
import { convertGitignore, renderGlobFile } from '../core/gitignore.js';
|
|
6
|
+
import { runSql } from '../core/sql.js';
|
|
7
|
+
import { flag, pushOption, workspaceParam } from './common.js';
|
|
8
|
+
const repoOptionParam = z
|
|
9
|
+
.string()
|
|
10
|
+
.min(1)
|
|
11
|
+
.optional()
|
|
12
|
+
.describe('Repository database file to read instead of the open check-out, e.g. `repos/app.fossil` (-R). Absolute paths are used verbatim; relative paths resolve against the workspace.');
|
|
13
|
+
/** Utility tools: raw file/artifact/SQL access and ignore-rule conversion. */
|
|
14
|
+
export function registerUtilsTools(server) {
|
|
15
|
+
server.registerTool('fossil_cat', {
|
|
16
|
+
title: 'Cat file revision',
|
|
17
|
+
description: 'Print the content of a file at a given revision.',
|
|
18
|
+
inputSchema: z.object({
|
|
19
|
+
file: z.string().min(1).describe('File path/name inside the repository.'),
|
|
20
|
+
revision: z.string().min(1).optional().describe('Check-in or revision (-r). Defaults to the checked-out version.'),
|
|
21
|
+
repository: repoOptionParam,
|
|
22
|
+
workspace: workspaceParam,
|
|
23
|
+
}),
|
|
24
|
+
annotations: { readOnlyHint: true },
|
|
25
|
+
}, async ({ file, revision, repository, workspace }) => {
|
|
26
|
+
const args = ['cat', file];
|
|
27
|
+
pushOption(args, '-R', repository);
|
|
28
|
+
pushOption(args, '-r', revision);
|
|
29
|
+
return renderOutcome(await runFossil(args, { workspace }));
|
|
30
|
+
});
|
|
31
|
+
server.registerTool('fossil_grep', {
|
|
32
|
+
title: 'Grep history',
|
|
33
|
+
description: 'Match a POSIX extended regular expression over every historical version of the named files, ' +
|
|
34
|
+
'starting at the newest version of each file.',
|
|
35
|
+
inputSchema: z.object({
|
|
36
|
+
pattern: z.string().min(1).describe('POSIX extended regular expression.'),
|
|
37
|
+
files: z.array(z.string().min(1)).min(1).describe('Files to search, newest version first.'),
|
|
38
|
+
ignore_case: flag('Case-insensitive match (-i).'),
|
|
39
|
+
count: flag('Print the number of matching files only (-c).'),
|
|
40
|
+
files_with_matches: flag('Print one artifact hash per matching file instead of the lines (-l).'),
|
|
41
|
+
once: flag('Stop at the first match (--once).'),
|
|
42
|
+
invert_match: flag('Show only files without a match (-v).'),
|
|
43
|
+
no_messages: flag('Suppress messages about unreadable files (-s).'),
|
|
44
|
+
verbose: flag('Report each file as it is analysed (--verbose).'),
|
|
45
|
+
workspace: workspaceParam,
|
|
46
|
+
}),
|
|
47
|
+
annotations: { readOnlyHint: true },
|
|
48
|
+
}, async ({ pattern, files, ignore_case, count, files_with_matches, once, invert_match, no_messages, verbose, workspace, }) => {
|
|
49
|
+
const args = ['grep'];
|
|
50
|
+
if (ignore_case)
|
|
51
|
+
args.push('-i');
|
|
52
|
+
if (count)
|
|
53
|
+
args.push('-c');
|
|
54
|
+
if (files_with_matches)
|
|
55
|
+
args.push('-l');
|
|
56
|
+
if (once)
|
|
57
|
+
args.push('--once');
|
|
58
|
+
if (invert_match)
|
|
59
|
+
args.push('-v');
|
|
60
|
+
if (no_messages)
|
|
61
|
+
args.push('-s');
|
|
62
|
+
if (verbose)
|
|
63
|
+
args.push('--verbose');
|
|
64
|
+
args.push(pattern, ...files);
|
|
65
|
+
return renderOutcome(await runFossil(args, { workspace }), { emptyText: 'No matches.' });
|
|
66
|
+
});
|
|
67
|
+
server.registerTool('fossil_whatis', {
|
|
68
|
+
title: 'What is',
|
|
69
|
+
description: 'Resolve a name (tag, branch, hash prefix, or with file: the content hash) to its artifact hash and role.',
|
|
70
|
+
inputSchema: z.object({
|
|
71
|
+
name: z.string().min(1).describe('Symbol to resolve: tag, branch, hash prefix or filename.'),
|
|
72
|
+
file: flag('Treat name as a file whose content hash is looked up (-f).'),
|
|
73
|
+
type: z.enum(['ci', 't', 'w', 'g', 'e']).optional().describe('Only match this artifact type (--type).'),
|
|
74
|
+
verbose: flag('Include the internal record id (-v).'),
|
|
75
|
+
workspace: workspaceParam,
|
|
76
|
+
}),
|
|
77
|
+
annotations: { readOnlyHint: true },
|
|
78
|
+
}, async ({ name, file, type, verbose, workspace }) => {
|
|
79
|
+
const args = ['whatis'];
|
|
80
|
+
if (file)
|
|
81
|
+
args.push('-f');
|
|
82
|
+
pushOption(args, '--type', type);
|
|
83
|
+
if (verbose)
|
|
84
|
+
args.push('-v');
|
|
85
|
+
args.push(name);
|
|
86
|
+
return renderOutcome(await runFossil(args, { workspace }));
|
|
87
|
+
});
|
|
88
|
+
server.registerTool('fossil_ignore_from_gitignore', {
|
|
89
|
+
title: 'Ignore glob from .gitignore',
|
|
90
|
+
description: 'Convert a .gitignore file into the ignore-glob patterns Fossil matches against check-out paths, ' +
|
|
91
|
+
'and optionally write them to .fossil-settings/ignore-glob.',
|
|
92
|
+
inputSchema: z.object({
|
|
93
|
+
source: z.string().min(1).default('.gitignore').describe('File to convert, relative to the workspace.'),
|
|
94
|
+
write: flag('Write the patterns to .fossil-settings/ignore-glob.'),
|
|
95
|
+
overwrite: flag('Replace an existing .fossil-settings/ignore-glob.'),
|
|
96
|
+
workspace: workspaceParam,
|
|
97
|
+
}),
|
|
98
|
+
}, async ({ source, write, overwrite, workspace }) => {
|
|
99
|
+
const root = resolveWorkspace(workspace);
|
|
100
|
+
const sourcePath = path.resolve(root, source);
|
|
101
|
+
const relative = path.relative(root, sourcePath);
|
|
102
|
+
if (relative.startsWith('..') || path.isAbsolute(relative)) {
|
|
103
|
+
return {
|
|
104
|
+
content: [{ type: 'text', text: `ERROR: \`source\` must stay inside the workspace (${root}).` }],
|
|
105
|
+
isError: true,
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
let content;
|
|
109
|
+
try {
|
|
110
|
+
content = await readFile(sourcePath, 'utf8');
|
|
111
|
+
}
|
|
112
|
+
catch (error) {
|
|
113
|
+
const code = error.code ?? 'unknown error';
|
|
114
|
+
return {
|
|
115
|
+
content: [{ type: 'text', text: `ERROR: cannot read ${relative}: ${code}.` }],
|
|
116
|
+
isError: true,
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
const directory = path.dirname(relative);
|
|
120
|
+
const conversion = convertGitignore(content, { prefix: directory === '.' ? '' : directory });
|
|
121
|
+
const lines = [
|
|
122
|
+
`Converted ${conversion.lineCount} rules from ${relative} into ${conversion.patterns.length} ignore-glob patterns.`,
|
|
123
|
+
'',
|
|
124
|
+
...conversion.patterns,
|
|
125
|
+
];
|
|
126
|
+
if (conversion.warnings.length > 0) {
|
|
127
|
+
lines.push('', ...conversion.warnings.map((warning) => `NOTE: ${warning}.`));
|
|
128
|
+
}
|
|
129
|
+
if (!write)
|
|
130
|
+
return { content: [{ type: 'text', text: lines.join('\n') }] };
|
|
131
|
+
const settingsDir = path.join(root, '.fossil-settings');
|
|
132
|
+
const target = path.join(settingsDir, 'ignore-glob');
|
|
133
|
+
const exists = await stat(target).then(() => true, () => false);
|
|
134
|
+
if (exists && !overwrite) {
|
|
135
|
+
return {
|
|
136
|
+
content: [
|
|
137
|
+
{
|
|
138
|
+
type: 'text',
|
|
139
|
+
text: 'ERROR: .fossil-settings/ignore-glob already exists; pass `overwrite: true` to replace it.',
|
|
140
|
+
},
|
|
141
|
+
],
|
|
142
|
+
isError: true,
|
|
143
|
+
};
|
|
144
|
+
}
|
|
145
|
+
await mkdir(settingsDir, { recursive: true });
|
|
146
|
+
await writeFile(target, renderGlobFile(conversion), 'utf8');
|
|
147
|
+
lines.splice(1, 0, 'Wrote .fossil-settings/ignore-glob.');
|
|
148
|
+
return { content: [{ type: 'text', text: lines.join('\n') }] };
|
|
149
|
+
});
|
|
150
|
+
server.registerTool('fossil_search', {
|
|
151
|
+
title: 'Search timeline',
|
|
152
|
+
description: 'Search check-in and other timeline comments for every given word and print the best matches.',
|
|
153
|
+
inputSchema: z.object({
|
|
154
|
+
pattern: z.string().min(1).describe('Words to look for; all of them must match.'),
|
|
155
|
+
all: flag('Print every match instead of only the best scoring ones (--all).'),
|
|
156
|
+
limit: z.number().int().min(1).optional().describe('Maximum number of matches (-n).'),
|
|
157
|
+
width: z.number().int().min(0).optional().describe('Output width in columns; 0 means no wrapping (-W).'),
|
|
158
|
+
workspace: workspaceParam,
|
|
159
|
+
}),
|
|
160
|
+
annotations: { readOnlyHint: true },
|
|
161
|
+
}, async ({ pattern, all, limit, width, workspace }) => {
|
|
162
|
+
const args = ['search'];
|
|
163
|
+
if (all)
|
|
164
|
+
args.push('-a');
|
|
165
|
+
if (limit !== undefined)
|
|
166
|
+
args.push('-n', String(limit));
|
|
167
|
+
if (width !== undefined)
|
|
168
|
+
args.push('-W', String(width));
|
|
169
|
+
args.push(pattern);
|
|
170
|
+
const outcome = await runFossil(args, { workspace });
|
|
171
|
+
// fossil reports an empty result set as "+++ no more data (0) +++".
|
|
172
|
+
if (outcome.ok && /^\+{3} no more data \(0\) \+{3}$/.test(outcome.stdout.trim())) {
|
|
173
|
+
return { content: [{ type: 'text', text: 'No matches.' }] };
|
|
174
|
+
}
|
|
175
|
+
return renderOutcome(outcome, { emptyText: 'No matches.' });
|
|
176
|
+
});
|
|
177
|
+
server.registerTool('fossil_artifact', {
|
|
178
|
+
title: 'Artifact content',
|
|
179
|
+
description: 'Print the raw content of an artifact by its hash, such as the manifest of a check-in or the blob of a file version.',
|
|
180
|
+
inputSchema: z.object({
|
|
181
|
+
artifact: z.string().min(1).describe('Artifact hash, or a unique prefix of it.'),
|
|
182
|
+
repository: repoOptionParam,
|
|
183
|
+
workspace: workspaceParam,
|
|
184
|
+
}),
|
|
185
|
+
annotations: { readOnlyHint: true },
|
|
186
|
+
}, async ({ artifact, repository, workspace }) => renderOutcome(await runFossil(repository ? ['artifact', '-R', repository, artifact] : ['artifact', artifact], { workspace })));
|
|
187
|
+
server.registerTool('fossil_sql', {
|
|
188
|
+
title: 'SQL query',
|
|
189
|
+
description: 'Run a read-only query against the repository database and return the rows as a table. Pass `limit` inside the SQL, e.g. `SELECT ... LIMIT 20`.',
|
|
190
|
+
inputSchema: z.object({
|
|
191
|
+
query: z.string().min(1).describe('SQL statement, e.g. "SELECT name FROM blob LIMIT 5".'),
|
|
192
|
+
repository: repoOptionParam.describe('Repository database file, e.g. `repos/app.fossil`, to query instead of the one of the check-out (-R).'),
|
|
193
|
+
database: z
|
|
194
|
+
.string()
|
|
195
|
+
.min(1)
|
|
196
|
+
.optional()
|
|
197
|
+
.describe('Standalone SQLite file to query in place of a repository (--no-repository), e.g. a chat archive.'),
|
|
198
|
+
workspace: workspaceParam,
|
|
199
|
+
}),
|
|
200
|
+
annotations: { readOnlyHint: true },
|
|
201
|
+
}, async ({ query, repository, database, workspace }) => {
|
|
202
|
+
const trimmed = query.trim().replace(/;+\s*$/, '');
|
|
203
|
+
if (!/^(select|with|pragma|explain)\b/i.test(trimmed)) {
|
|
204
|
+
return {
|
|
205
|
+
isError: true,
|
|
206
|
+
content: [
|
|
207
|
+
{
|
|
208
|
+
type: 'text',
|
|
209
|
+
text: 'ERROR: the query must start with SELECT, WITH, PRAGMA or EXPLAIN.',
|
|
210
|
+
},
|
|
211
|
+
],
|
|
212
|
+
};
|
|
213
|
+
}
|
|
214
|
+
const result = await runSql(trimmed, { workspace, readonly: true, repository, database });
|
|
215
|
+
if (!result.ok)
|
|
216
|
+
return { isError: true, content: [{ type: 'text', text: result.error }] };
|
|
217
|
+
if (result.rows.length === 0)
|
|
218
|
+
return { content: [{ type: 'text', text: 'No rows.' }] };
|
|
219
|
+
const columns = Object.keys(result.rows[0] ?? {});
|
|
220
|
+
const cell = (value) => {
|
|
221
|
+
if (value === null || value === undefined)
|
|
222
|
+
return 'NULL';
|
|
223
|
+
if (typeof value === 'object')
|
|
224
|
+
return JSON.stringify(value);
|
|
225
|
+
return String(value);
|
|
226
|
+
};
|
|
227
|
+
const lines = [columns.join('\t'), ...result.rows.map((row) => columns.map((column) => cell(row[column])).join('\t'))];
|
|
228
|
+
return {
|
|
229
|
+
content: [
|
|
230
|
+
{
|
|
231
|
+
type: 'text',
|
|
232
|
+
text: truncateOutput(`${lines.join('\n')}\n\n${result.rows.length} row(s).`),
|
|
233
|
+
},
|
|
234
|
+
],
|
|
235
|
+
};
|
|
236
|
+
});
|
|
237
|
+
}
|
|
@@ -1,9 +1,5 @@
|
|
|
1
|
-
import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
|
|
2
|
-
import path from 'node:path';
|
|
3
1
|
import { z } from 'zod';
|
|
4
|
-
import { renderOutcome, renderSections,
|
|
5
|
-
import { convertGitignore, renderGlobFile } from '../core/gitignore.js';
|
|
6
|
-
import { runSql } from '../core/sql.js';
|
|
2
|
+
import { renderOutcome, renderSections, runFossil } from '../core/fossil.js';
|
|
7
3
|
import { clean, workspaceParam, filesParam, flag, pushOption } from './common.js';
|
|
8
4
|
const repoOptionParam = z
|
|
9
5
|
.string()
|
|
@@ -165,22 +161,6 @@ export function registerVersionControlTools(server) {
|
|
|
165
161
|
args.push(...files);
|
|
166
162
|
return renderOutcome(await runFossil(args, { workspace }), { emptyText: 'No differences found.' });
|
|
167
163
|
});
|
|
168
|
-
server.registerTool('fossil_cat', {
|
|
169
|
-
title: 'Cat file revision',
|
|
170
|
-
description: 'Print the content of a file at a given revision.',
|
|
171
|
-
inputSchema: z.object({
|
|
172
|
-
file: z.string().min(1).describe('File path/name inside the repository.'),
|
|
173
|
-
revision: z.string().min(1).optional().describe('Check-in or revision (-r). Defaults to the checked-out version.'),
|
|
174
|
-
repository: repoOptionParam,
|
|
175
|
-
workspace: workspaceParam,
|
|
176
|
-
}),
|
|
177
|
-
annotations: { readOnlyHint: true },
|
|
178
|
-
}, async ({ file, revision, repository, workspace }) => {
|
|
179
|
-
const args = ['cat', file];
|
|
180
|
-
pushOption(args, '-R', repository);
|
|
181
|
-
pushOption(args, '-r', revision);
|
|
182
|
-
return renderOutcome(await runFossil(args, { workspace }));
|
|
183
|
-
});
|
|
184
164
|
server.registerTool('fossil_finfo', {
|
|
185
165
|
title: 'File history',
|
|
186
166
|
description: 'Show the change history of one file, or switch to the artifact facts, status line or file content view.',
|
|
@@ -1020,63 +1000,6 @@ export function registerVersionControlTools(server) {
|
|
|
1020
1000
|
args.push(file);
|
|
1021
1001
|
return renderOutcome(await runFossil(args, { workspace }));
|
|
1022
1002
|
});
|
|
1023
|
-
server.registerTool('fossil_grep', {
|
|
1024
|
-
title: 'Grep history',
|
|
1025
|
-
description: 'Match a POSIX extended regular expression over every historical version of the named files, ' +
|
|
1026
|
-
'starting at the newest version of each file.',
|
|
1027
|
-
inputSchema: z.object({
|
|
1028
|
-
pattern: z.string().min(1).describe('POSIX extended regular expression.'),
|
|
1029
|
-
files: z.array(z.string().min(1)).min(1).describe('Files to search, newest version first.'),
|
|
1030
|
-
ignore_case: flag('Case-insensitive match (-i).'),
|
|
1031
|
-
count: flag('Print the number of matching files only (-c).'),
|
|
1032
|
-
files_with_matches: flag('Print one artifact hash per matching file instead of the lines (-l).'),
|
|
1033
|
-
once: flag('Stop at the first match (--once).'),
|
|
1034
|
-
invert_match: flag('Show only files without a match (-v).'),
|
|
1035
|
-
no_messages: flag('Suppress messages about unreadable files (-s).'),
|
|
1036
|
-
verbose: flag('Report each file as it is analysed (--verbose).'),
|
|
1037
|
-
workspace: workspaceParam,
|
|
1038
|
-
}),
|
|
1039
|
-
annotations: { readOnlyHint: true },
|
|
1040
|
-
}, async ({ pattern, files, ignore_case, count, files_with_matches, once, invert_match, no_messages, verbose, workspace, }) => {
|
|
1041
|
-
const args = ['grep'];
|
|
1042
|
-
if (ignore_case)
|
|
1043
|
-
args.push('-i');
|
|
1044
|
-
if (count)
|
|
1045
|
-
args.push('-c');
|
|
1046
|
-
if (files_with_matches)
|
|
1047
|
-
args.push('-l');
|
|
1048
|
-
if (once)
|
|
1049
|
-
args.push('--once');
|
|
1050
|
-
if (invert_match)
|
|
1051
|
-
args.push('-v');
|
|
1052
|
-
if (no_messages)
|
|
1053
|
-
args.push('-s');
|
|
1054
|
-
if (verbose)
|
|
1055
|
-
args.push('--verbose');
|
|
1056
|
-
args.push(pattern, ...files);
|
|
1057
|
-
return renderOutcome(await runFossil(args, { workspace }), { emptyText: 'No matches.' });
|
|
1058
|
-
});
|
|
1059
|
-
server.registerTool('fossil_whatis', {
|
|
1060
|
-
title: 'What is',
|
|
1061
|
-
description: 'Resolve a name (tag, branch, hash prefix, or with file: the content hash) to its artifact hash and role.',
|
|
1062
|
-
inputSchema: z.object({
|
|
1063
|
-
name: z.string().min(1).describe('Symbol to resolve: tag, branch, hash prefix or filename.'),
|
|
1064
|
-
file: flag('Treat name as a file whose content hash is looked up (-f).'),
|
|
1065
|
-
type: z.enum(['ci', 't', 'w', 'g', 'e']).optional().describe('Only match this artifact type (--type).'),
|
|
1066
|
-
verbose: flag('Include the internal record id (-v).'),
|
|
1067
|
-
workspace: workspaceParam,
|
|
1068
|
-
}),
|
|
1069
|
-
annotations: { readOnlyHint: true },
|
|
1070
|
-
}, async ({ name, file, type, verbose, workspace }) => {
|
|
1071
|
-
const args = ['whatis'];
|
|
1072
|
-
if (file)
|
|
1073
|
-
args.push('-f');
|
|
1074
|
-
pushOption(args, '--type', type);
|
|
1075
|
-
if (verbose)
|
|
1076
|
-
args.push('-v');
|
|
1077
|
-
args.push(name);
|
|
1078
|
-
return renderOutcome(await runFossil(args, { workspace }));
|
|
1079
|
-
});
|
|
1080
1003
|
server.registerTool('fossil_merge_base', {
|
|
1081
1004
|
title: 'Merge base',
|
|
1082
1005
|
description: 'Find the common ancestor check-in of two or more versions, as a hypothetical merge would.',
|
|
@@ -1153,68 +1076,6 @@ export function registerVersionControlTools(server) {
|
|
|
1153
1076
|
}, async ({ all, workspace }) => renderOutcome(await runFossil(all ? ['unpublished', '--all'] : ['unpublished'], { workspace }), {
|
|
1154
1077
|
emptyText: 'No unpublished artifacts.',
|
|
1155
1078
|
}));
|
|
1156
|
-
server.registerTool('fossil_ignore_from_gitignore', {
|
|
1157
|
-
title: 'Ignore glob from .gitignore',
|
|
1158
|
-
description: 'Convert a .gitignore file into the ignore-glob patterns Fossil matches against check-out paths, ' +
|
|
1159
|
-
'and optionally write them to .fossil-settings/ignore-glob.',
|
|
1160
|
-
inputSchema: z.object({
|
|
1161
|
-
source: z.string().min(1).default('.gitignore').describe('File to convert, relative to the workspace.'),
|
|
1162
|
-
write: flag('Write the patterns to .fossil-settings/ignore-glob.'),
|
|
1163
|
-
overwrite: flag('Replace an existing .fossil-settings/ignore-glob.'),
|
|
1164
|
-
workspace: workspaceParam,
|
|
1165
|
-
}),
|
|
1166
|
-
}, async ({ source, write, overwrite, workspace }) => {
|
|
1167
|
-
const root = resolveWorkspace(workspace);
|
|
1168
|
-
const sourcePath = path.resolve(root, source);
|
|
1169
|
-
const relative = path.relative(root, sourcePath);
|
|
1170
|
-
if (relative.startsWith('..') || path.isAbsolute(relative)) {
|
|
1171
|
-
return {
|
|
1172
|
-
content: [{ type: 'text', text: `ERROR: \`source\` must stay inside the workspace (${root}).` }],
|
|
1173
|
-
isError: true,
|
|
1174
|
-
};
|
|
1175
|
-
}
|
|
1176
|
-
let content;
|
|
1177
|
-
try {
|
|
1178
|
-
content = await readFile(sourcePath, 'utf8');
|
|
1179
|
-
}
|
|
1180
|
-
catch (error) {
|
|
1181
|
-
const code = error.code ?? 'unknown error';
|
|
1182
|
-
return {
|
|
1183
|
-
content: [{ type: 'text', text: `ERROR: cannot read ${relative}: ${code}.` }],
|
|
1184
|
-
isError: true,
|
|
1185
|
-
};
|
|
1186
|
-
}
|
|
1187
|
-
const directory = path.dirname(relative);
|
|
1188
|
-
const conversion = convertGitignore(content, { prefix: directory === '.' ? '' : directory });
|
|
1189
|
-
const lines = [
|
|
1190
|
-
`Converted ${conversion.lineCount} rules from ${relative} into ${conversion.patterns.length} ignore-glob patterns.`,
|
|
1191
|
-
'',
|
|
1192
|
-
...conversion.patterns,
|
|
1193
|
-
];
|
|
1194
|
-
if (conversion.warnings.length > 0) {
|
|
1195
|
-
lines.push('', ...conversion.warnings.map((warning) => `NOTE: ${warning}.`));
|
|
1196
|
-
}
|
|
1197
|
-
if (!write)
|
|
1198
|
-
return { content: [{ type: 'text', text: lines.join('\n') }] };
|
|
1199
|
-
const settingsDir = path.join(root, '.fossil-settings');
|
|
1200
|
-
const target = path.join(settingsDir, 'ignore-glob');
|
|
1201
|
-
const exists = await stat(target).then(() => true, () => false);
|
|
1202
|
-
if (exists && !overwrite) {
|
|
1203
|
-
return {
|
|
1204
|
-
content: [
|
|
1205
|
-
{
|
|
1206
|
-
type: 'text',
|
|
1207
|
-
text: 'ERROR: .fossil-settings/ignore-glob already exists; pass `overwrite: true` to replace it.',
|
|
1208
|
-
},
|
|
1209
|
-
],
|
|
1210
|
-
isError: true,
|
|
1211
|
-
};
|
|
1212
|
-
}
|
|
1213
|
-
await mkdir(settingsDir, { recursive: true });
|
|
1214
|
-
await writeFile(target, renderGlobFile(conversion), 'utf8');
|
|
1215
|
-
lines.splice(1, 0, 'Wrote .fossil-settings/ignore-glob.');
|
|
1216
|
-
return { content: [{ type: 'text', text: lines.join('\n') }] };
|
|
1217
|
-
});
|
|
1218
1079
|
server.registerTool('fossil_ls', {
|
|
1219
1080
|
title: 'List files',
|
|
1220
1081
|
description: 'List the files of the check-out, or of a given check-in, optionally limited to some paths and enriched with age, status or time ordering.',
|
|
@@ -1245,43 +1106,6 @@ export function registerVersionControlTools(server) {
|
|
|
1245
1106
|
args.push(...paths);
|
|
1246
1107
|
return renderOutcome(await runFossil(args, { workspace }));
|
|
1247
1108
|
});
|
|
1248
|
-
server.registerTool('fossil_search', {
|
|
1249
|
-
title: 'Search timeline',
|
|
1250
|
-
description: 'Search check-in and other timeline comments for every given word and print the best matches.',
|
|
1251
|
-
inputSchema: z.object({
|
|
1252
|
-
pattern: z.string().min(1).describe('Words to look for; all of them must match.'),
|
|
1253
|
-
all: flag('Print every match instead of only the best scoring ones (--all).'),
|
|
1254
|
-
limit: z.number().int().min(1).optional().describe('Maximum number of matches (-n).'),
|
|
1255
|
-
width: z.number().int().min(0).optional().describe('Output width in columns; 0 means no wrapping (-W).'),
|
|
1256
|
-
workspace: workspaceParam,
|
|
1257
|
-
}),
|
|
1258
|
-
annotations: { readOnlyHint: true },
|
|
1259
|
-
}, async ({ pattern, all, limit, width, workspace }) => {
|
|
1260
|
-
const args = ['search'];
|
|
1261
|
-
if (all)
|
|
1262
|
-
args.push('-a');
|
|
1263
|
-
if (limit !== undefined)
|
|
1264
|
-
args.push('-n', String(limit));
|
|
1265
|
-
if (width !== undefined)
|
|
1266
|
-
args.push('-W', String(width));
|
|
1267
|
-
args.push(pattern);
|
|
1268
|
-
const outcome = await runFossil(args, { workspace });
|
|
1269
|
-
// fossil reports an empty result set as "+++ no more data (0) +++".
|
|
1270
|
-
if (outcome.ok && /^\+{3} no more data \(0\) \+{3}$/.test(outcome.stdout.trim())) {
|
|
1271
|
-
return { content: [{ type: 'text', text: 'No matches.' }] };
|
|
1272
|
-
}
|
|
1273
|
-
return renderOutcome(outcome, { emptyText: 'No matches.' });
|
|
1274
|
-
});
|
|
1275
|
-
server.registerTool('fossil_artifact', {
|
|
1276
|
-
title: 'Artifact content',
|
|
1277
|
-
description: 'Print the raw content of an artifact by its hash, such as the manifest of a check-in or the blob of a file version.',
|
|
1278
|
-
inputSchema: z.object({
|
|
1279
|
-
artifact: z.string().min(1).describe('Artifact hash, or a unique prefix of it.'),
|
|
1280
|
-
repository: repoOptionParam,
|
|
1281
|
-
workspace: workspaceParam,
|
|
1282
|
-
}),
|
|
1283
|
-
annotations: { readOnlyHint: true },
|
|
1284
|
-
}, async ({ artifact, repository, workspace }) => renderOutcome(await runFossil(repository ? ['artifact', '-R', repository, artifact] : ['artifact', artifact], { workspace })));
|
|
1285
1109
|
server.registerTool('fossil_describe', {
|
|
1286
1110
|
title: 'Describe version',
|
|
1287
1111
|
description: 'Describe a version as the closest non-propagating tag, the commit count since it and the short hash, or just the hash when no tag applies.',
|
|
@@ -1586,58 +1410,4 @@ export function registerVersionControlTools(server) {
|
|
|
1586
1410
|
}
|
|
1587
1411
|
return renderOutcome(await runFossil(args, { workspace }));
|
|
1588
1412
|
});
|
|
1589
|
-
server.registerTool('fossil_sql', {
|
|
1590
|
-
title: 'SQL query',
|
|
1591
|
-
description: 'Run a read-only query against the repository database and return the rows as a table. Pass `limit` inside the SQL, e.g. `SELECT ... LIMIT 20`.',
|
|
1592
|
-
inputSchema: z.object({
|
|
1593
|
-
query: z.string().min(1).describe('SQL statement, e.g. "SELECT name FROM blob LIMIT 5".'),
|
|
1594
|
-
repository: z
|
|
1595
|
-
.string()
|
|
1596
|
-
.min(1)
|
|
1597
|
-
.optional()
|
|
1598
|
-
.describe('Repository database file, e.g. `repos/app.fossil`, to query instead of the one of the check-out (-R).'),
|
|
1599
|
-
database: z
|
|
1600
|
-
.string()
|
|
1601
|
-
.min(1)
|
|
1602
|
-
.optional()
|
|
1603
|
-
.describe('Standalone SQLite file to query in place of a repository (--no-repository), e.g. a chat archive.'),
|
|
1604
|
-
workspace: workspaceParam,
|
|
1605
|
-
}),
|
|
1606
|
-
annotations: { readOnlyHint: true },
|
|
1607
|
-
}, async ({ query, repository, database, workspace }) => {
|
|
1608
|
-
const trimmed = query.trim().replace(/;+\s*$/, '');
|
|
1609
|
-
if (!/^(select|with|pragma|explain)\b/i.test(trimmed)) {
|
|
1610
|
-
return {
|
|
1611
|
-
isError: true,
|
|
1612
|
-
content: [
|
|
1613
|
-
{
|
|
1614
|
-
type: 'text',
|
|
1615
|
-
text: 'ERROR: the query must start with SELECT, WITH, PRAGMA or EXPLAIN.',
|
|
1616
|
-
},
|
|
1617
|
-
],
|
|
1618
|
-
};
|
|
1619
|
-
}
|
|
1620
|
-
const result = await runSql(trimmed, { workspace, readonly: true, repository, database });
|
|
1621
|
-
if (!result.ok)
|
|
1622
|
-
return { isError: true, content: [{ type: 'text', text: result.error }] };
|
|
1623
|
-
if (result.rows.length === 0)
|
|
1624
|
-
return { content: [{ type: 'text', text: 'No rows.' }] };
|
|
1625
|
-
const columns = Object.keys(result.rows[0] ?? {});
|
|
1626
|
-
const cell = (value) => {
|
|
1627
|
-
if (value === null || value === undefined)
|
|
1628
|
-
return 'NULL';
|
|
1629
|
-
if (typeof value === 'object')
|
|
1630
|
-
return JSON.stringify(value);
|
|
1631
|
-
return String(value);
|
|
1632
|
-
};
|
|
1633
|
-
const lines = [columns.join('\t'), ...result.rows.map((row) => columns.map((column) => cell(row[column])).join('\t'))];
|
|
1634
|
-
return {
|
|
1635
|
-
content: [
|
|
1636
|
-
{
|
|
1637
|
-
type: 'text',
|
|
1638
|
-
text: truncateOutput(`${lines.join('\n')}\n\n${result.rows.length} row(s).`),
|
|
1639
|
-
},
|
|
1640
|
-
],
|
|
1641
|
-
};
|
|
1642
|
-
});
|
|
1643
1413
|
}
|
package/docs/README.md
CHANGED
|
@@ -1,16 +1,17 @@
|
|
|
1
1
|
# 文件索引
|
|
2
2
|
|
|
3
3
|
按能力分冊,每冊包含:能力概覽表、通用約定、逐工具的參數表與真實 argv/輸出、典型流程、已知邊界、原始碼位置。
|
|
4
|
-
所有內容在 fossil 2.21 + `@stellar_ai/mcp_fossil_scm@0.2.
|
|
4
|
+
所有內容在 fossil 2.21 + `@stellar_ai/mcp_fossil_scm@0.2.2` 上實測。
|
|
5
5
|
|
|
6
6
|
| 文件 | 能力 | `-c` | 工具數 |
|
|
7
7
|
| --- | --- | --- | --- |
|
|
8
8
|
| [admin.md](./admin.md) | 倉庫管理 | `a` | 11 |
|
|
9
|
-
| [
|
|
10
|
-
| [
|
|
9
|
+
| [utils.md](./utils.md) | 通用工具:cat / grep / whatis / search / artifact / sql / .gitignore 轉換 | `u` | 7 |
|
|
10
|
+
| [vcs.md](./vcs.md) | 版本控制:status / diff / commit / branch / blame / … | `v` | 33 |
|
|
11
11
|
| [tickets.md](./tickets.md) | 工單 | `t` | 4 |
|
|
12
|
-
| [wiki.md](./wiki.md) | Wiki 頁面 | `w` | 3 |
|
|
13
12
|
| [chat.md](./chat.md) | 聊天室 | `c` | 4 |
|
|
13
|
+
| [forum.md](./forum.md) | 論壇 | `f` | 3 |
|
|
14
|
+
| [wiki.md](./wiki.md) | Wiki 頁面 | `w` | 3 |
|
|
14
15
|
| [prompts.md](./prompts.md) | MCP 提示(`prompts/list` / `prompts/get`) | — | 8 |
|
|
15
16
|
|
|
16
17
|
合計 65 個工具;`-c All` 啟用全部。
|
|
@@ -19,7 +20,7 @@
|
|
|
19
20
|
|
|
20
21
|
1. [admin.md](./admin.md) §2 —— `workspace` 與 `repository` 兩個概念,所有能力共用,先看這裡。
|
|
21
22
|
2. [prompts.md](./prompts.md) —— 內建的 MCP 提示,把常用的多步流程寫成一段指示。
|
|
22
|
-
3. 然後按需跳到具體能力分冊。VCS 與內容類能力(`v/f/
|
|
23
|
+
3. 然後按需跳到具體能力分冊。VCS 與內容類能力(`v/t/c/f/w`)以 check-out 為前提;`fossil_cat`、`fossil_artifact`、`fossil_sql`、`fossil_rebuild` 與部分 VCS 只讀工具可用 `repository` 直接讀倉庫檔。
|
|
23
24
|
|
|
24
25
|
## 約定速查
|
|
25
26
|
|
package/docs/admin.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
# Admin 能力(`-c a`)說明
|
|
2
2
|
|
|
3
3
|
本文件對應 `src/tools/admin.ts`(實現)與 `src/core/fossil.ts`(執行器),描述 `fossil-scm` 在
|
|
4
|
-
`-c a`(Admin)能力下暴露的 **
|
|
4
|
+
`-c a`(Admin)能力下暴露的 **12 個工具**、它們的確切行為、成功/失敗輸出形態,以及當前已知的邊界問題。
|
|
5
5
|
|
|
6
|
-
適用於 `@stellar_ai/mcp_fossil_scm@0.2.
|
|
6
|
+
適用於 `@stellar_ai/mcp_fossil_scm@0.2.2` 及之後。
|
|
7
7
|
|
|
8
8
|
> 執行要求:Node.js >= 20。包內是編譯後的 `dist/**/*.js`(無 source map、無 `.d.ts`)。
|
|
9
9
|
|
|
@@ -22,8 +22,8 @@
|
|
|
22
22
|
| `fossil_push` | 把本地可分享的變更送到遠端倉庫 |
|
|
23
23
|
| `fossil_pull` | 把遠端倉庫的可分享變更拉回本地 |
|
|
24
24
|
| `fossil_sync` | 與遠端倉庫雙向交換可分享的變更 |
|
|
25
|
-
| `fossil_rebuild` | 重建倉庫資料庫 |
|
|
26
25
|
| `fossil_config` | 匯出 / 匯入 / 合併 / 拉取 / 推送 / 重設設定區 |
|
|
26
|
+
| `fossil_rebuild` | 重建倉庫資料庫 |
|
|
27
27
|
|
|
28
28
|
`fossil_close`、`fossil_rebuild` 標記 destructive;`fossil_push`、`fossil_pull`、`fossil_sync`、`fossil_config` 標記 openWorld;`fossil_close`、`fossil_settings` 標記 idempotent。
|
|
29
29
|
|
|
@@ -506,7 +506,48 @@ fossil 用 `\r` 覆寫同一行進度,因此 `Round-trips:` 可能連續出現
|
|
|
506
506
|
|
|
507
507
|
---
|
|
508
508
|
|
|
509
|
-
### 3.8 `
|
|
509
|
+
### 3.8 `fossil_config`
|
|
510
|
+
|
|
511
|
+
```bash
|
|
512
|
+
fossil config export <area> <file>
|
|
513
|
+
fossil config import|merge <file>
|
|
514
|
+
fossil config pull|push <area> [<url>] [--overwrite]
|
|
515
|
+
fossil config reset <area>
|
|
516
|
+
```
|
|
517
|
+
|
|
518
|
+
| 參數 | 類型 | 必填/預設 | 說明 |
|
|
519
|
+
| --- | --- | --- | --- |
|
|
520
|
+
| `action` | enum | **必填** | `export` / `import` / `merge` / `pull` / `push` / `reset` |
|
|
521
|
+
| `area` | enum | `export` / `pull` / `push` / `reset` 時必填 | `all` / `email` / `interwiki` / `project` / `shun` / `skin` / `ticket` / `user` / `alias` / `subscriber` |
|
|
522
|
+
| `file` | string | `export` / `import` / `merge` 時必填 | 要寫出或讀入的檔案 |
|
|
523
|
+
| `url` | string | 預設遠端 | `pull`/`push` 的來源或目的 |
|
|
524
|
+
| `repository` | string | check-out 的倉庫 | 直接指定要設定哪個倉庫檔(`-R`) |
|
|
525
|
+
| `overwrite` | boolean | `false` | `pull` 時以遠端內容覆蓋本地設定(`--overwrite`) |
|
|
526
|
+
| `workspace` | string | 見 §2.1 | — |
|
|
527
|
+
|
|
528
|
+
缺少 `area` 或 `file` 時工具直接報錯:
|
|
529
|
+
|
|
530
|
+
```
|
|
531
|
+
ERROR: `export` requires `file`.
|
|
532
|
+
ERROR: `reset` requires `area`.
|
|
533
|
+
```
|
|
534
|
+
|
|
535
|
+
真實輸出(`action: 'export'`、`area: 'ticket'`):
|
|
536
|
+
|
|
537
|
+
```
|
|
538
|
+
$ fossil config export ticket /tmp/ticket-config.txt
|
|
539
|
+
(無輸出,exit 0)
|
|
540
|
+
$ head -3 /tmp/ticket-config.txt
|
|
541
|
+
# The "ticket" configuration exported from
|
|
542
|
+
# repository "/tmp/pw/repo.fossil"
|
|
543
|
+
# on 2026-11-17 02:53:53
|
|
544
|
+
```
|
|
545
|
+
|
|
546
|
+
`pull` / `push` 走 600s 網路超時,其餘動作走一般超時。
|
|
547
|
+
|
|
548
|
+
---
|
|
549
|
+
|
|
550
|
+
### 3.9 `fossil_rebuild`
|
|
510
551
|
|
|
511
552
|
```bash
|
|
512
553
|
fossil rebuild [--ifneeded] [--compress] [--compress-only] [--vacuum] [--stats]
|
|
@@ -546,45 +587,6 @@ $ fossil rebuild --compress --quiet
|
|
|
546
587
|
Extra delta compression... none found
|
|
547
588
|
```
|
|
548
589
|
|
|
549
|
-
### 3.9 `fossil_config`
|
|
550
|
-
|
|
551
|
-
```bash
|
|
552
|
-
fossil config export <area> <file>
|
|
553
|
-
fossil config import|merge <file>
|
|
554
|
-
fossil config pull|push <area> [<url>] [--overwrite]
|
|
555
|
-
fossil config reset <area>
|
|
556
|
-
```
|
|
557
|
-
|
|
558
|
-
| 參數 | 類型 | 必填/預設 | 說明 |
|
|
559
|
-
| --- | --- | --- | --- |
|
|
560
|
-
| `action` | enum | **必填** | `export` / `import` / `merge` / `pull` / `push` / `reset` |
|
|
561
|
-
| `area` | enum | `export` / `pull` / `push` / `reset` 時必填 | `all` / `email` / `interwiki` / `project` / `shun` / `skin` / `ticket` / `user` / `alias` / `subscriber` |
|
|
562
|
-
| `file` | string | `export` / `import` / `merge` 時必填 | 要寫出或讀入的檔案 |
|
|
563
|
-
| `url` | string | 預設遠端 | `pull`/`push` 的來源或目的 |
|
|
564
|
-
| `repository` | string | check-out 的倉庫 | 直接指定要設定哪個倉庫檔(`-R`) |
|
|
565
|
-
| `overwrite` | boolean | `false` | `pull` 時以遠端內容覆蓋本地設定(`--overwrite`) |
|
|
566
|
-
| `workspace` | string | 見 §2.1 | — |
|
|
567
|
-
|
|
568
|
-
缺少 `area` 或 `file` 時工具直接報錯:
|
|
569
|
-
|
|
570
|
-
```
|
|
571
|
-
ERROR: `export` requires `file`.
|
|
572
|
-
ERROR: `reset` requires `area`.
|
|
573
|
-
```
|
|
574
|
-
|
|
575
|
-
真實輸出(`action: 'export'`、`area: 'ticket'`):
|
|
576
|
-
|
|
577
|
-
```
|
|
578
|
-
$ fossil config export ticket /tmp/ticket-config.txt
|
|
579
|
-
(無輸出,exit 0)
|
|
580
|
-
$ head -3 /tmp/ticket-config.txt
|
|
581
|
-
# The "ticket" configuration exported from
|
|
582
|
-
# repository "/tmp/pw/repo.fossil"
|
|
583
|
-
# on 2026-11-17 02:53:53
|
|
584
|
-
```
|
|
585
|
-
|
|
586
|
-
`pull` / `push` 走 600s 網路超時,其餘動作走一般超時。
|
|
587
|
-
|
|
588
590
|
## 4. 典型流程
|
|
589
591
|
|
|
590
592
|
```text
|
package/docs/chat.md
CHANGED
package/docs/forum.md
CHANGED