@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.
@@ -3,7 +3,7 @@ import { z } from 'zod';
3
3
  import { NETWORK_TIMEOUT_MS } from '../config.js';
4
4
  import { renderOutcome, resolveWorkspace, runFossil, truncateOutput } from '../core/fossil.js';
5
5
  import { asNumber, asString, runSql } from '../core/sql.js';
6
- import { clean, cwdParam, flag, pushOption } from './common.js';
6
+ import { clean, workspaceParam, flag, pushOption } from './common.js';
7
7
  /** Formats the `mtime` column of the chat table (unix seconds). */
8
8
  function formatTime(value) {
9
9
  const seconds = asNumber(value, 0);
@@ -32,13 +32,13 @@ export function registerChatTools(server) {
32
32
  description: 'Show the URL of the chatroom on the default remote (or on --remote).',
33
33
  inputSchema: z.object({
34
34
  remote: z.string().min(1).optional().describe('Use this remote URL instead of the default remote.'),
35
- cwd: cwdParam,
35
+ workspace: workspaceParam,
36
36
  }),
37
37
  annotations: { readOnlyHint: true },
38
- }, async ({ remote, cwd }) => {
38
+ }, async ({ remote, workspace }) => {
39
39
  const args = ['chat', 'url'];
40
40
  pushOption(args, '--remote', remote);
41
- return renderOutcome(await runFossil(args, { cwd }));
41
+ return renderOutcome(await runFossil(args, { workspace }));
42
42
  });
43
43
  server.registerTool('fossil_chat_send', {
44
44
  title: 'Send chat message',
@@ -53,10 +53,10 @@ export function registerChatTools(server) {
53
53
  .optional()
54
54
  .describe('Send the attachment under this name (--as). Requires file.'),
55
55
  remote: z.string().min(1).optional().describe('Chat server URL to use instead of the default remote.'),
56
- cwd: cwdParam,
56
+ workspace: workspaceParam,
57
57
  }),
58
- }, async ({ message, file, attachment_name, remote, cwd }) => {
59
- const workspaceDir = resolveWorkspace(cwd);
58
+ }, async ({ message, file, attachment_name, remote, workspace }) => {
59
+ const workspaceDir = resolveWorkspace(workspace);
60
60
  const attachment = clean(file);
61
61
  if (attachment_name && !attachment) {
62
62
  return { content: [{ type: 'text', text: "ERROR: 'attachment_name' requires 'file'." }], isError: true };
@@ -67,7 +67,7 @@ export function registerChatTools(server) {
67
67
  pushOption(args, '--as', attachment_name);
68
68
  }
69
69
  pushOption(args, '--remote', remote);
70
- return renderOutcome(await runFossil(args, { cwd, timeoutMs: NETWORK_TIMEOUT_MS }), {
70
+ return renderOutcome(await runFossil(args, { workspace, timeoutMs: NETWORK_TIMEOUT_MS }), {
71
71
  note: 'Message sent to the chatroom.',
72
72
  });
73
73
  });
@@ -83,17 +83,17 @@ export function registerChatTools(server) {
83
83
  .optional()
84
84
  .describe('Store the CHAT table in this database file instead of the clone (--out, workspace relative).'),
85
85
  remote: z.string().min(1).optional().describe('Chat server URL to use instead of the default remote.'),
86
- cwd: cwdParam,
86
+ workspace: workspaceParam,
87
87
  }),
88
- }, async ({ all, out, remote, cwd }) => {
88
+ }, async ({ all, out, remote, workspace }) => {
89
89
  const args = ['chat', 'pull'];
90
90
  if (all)
91
91
  args.push('--all');
92
92
  const archivePath = clean(out);
93
93
  if (archivePath)
94
- args.push('--out', path.resolve(resolveWorkspace(cwd), archivePath));
94
+ args.push('--out', path.resolve(resolveWorkspace(workspace), archivePath));
95
95
  pushOption(args, '--remote', remote);
96
- return renderOutcome(await runFossil(args, { cwd, timeoutMs: NETWORK_TIMEOUT_MS }), {
96
+ return renderOutcome(await runFossil(args, { workspace, timeoutMs: NETWORK_TIMEOUT_MS }), {
97
97
  note: 'Chat history pulled into the local clone.',
98
98
  });
99
99
  });
@@ -108,15 +108,15 @@ export function registerChatTools(server) {
108
108
  .min(1)
109
109
  .optional()
110
110
  .describe('Chat archive database file created by `fossil_chat_pull --out` (workspace relative).'),
111
- cwd: cwdParam,
111
+ workspace: workspaceParam,
112
112
  }),
113
113
  annotations: { readOnlyHint: true },
114
- }, async ({ limit, database, cwd }) => {
114
+ }, async ({ limit, database, workspace }) => {
115
115
  const archive = clean(database);
116
116
  const result = await runSql(`SELECT * FROM chat ORDER BY msgid DESC LIMIT ${limit ?? 50}`, {
117
- cwd,
117
+ workspace,
118
118
  readonly: true,
119
- database: archive ? path.resolve(resolveWorkspace(cwd), archive) : undefined,
119
+ database: archive ? path.resolve(resolveWorkspace(workspace), archive) : undefined,
120
120
  });
121
121
  if (!result.ok) {
122
122
  if (/no such table/i.test(result.error)) {
@@ -1,10 +1,11 @@
1
1
  import { z } from 'zod';
2
- /** Shared `cwd` parameter accepted by every tool. */
3
- export const cwdParam = z
2
+ /** Shared `workspace` parameter accepted by every tool. */
3
+ export const workspaceParam = z
4
4
  .string()
5
5
  .min(1)
6
6
  .optional()
7
- .describe('Directory the fossil command runs in (check-out or workspace). Defaults to the server workspace.');
7
+ .describe('Directory the fossil command runs in (check-out or workspace). Defaults to the --workspace value, ' +
8
+ 'then to the process working directory.');
8
9
  /** Shared list-of-paths parameter. */
9
10
  export const filesParam = z
10
11
  .array(z.string().min(1))
@@ -1,7 +1,7 @@
1
1
  import { z } from 'zod';
2
2
  import { escapeSqlLiteral, truncateOutput } from '../core/fossil.js';
3
3
  import { asString, runSql } from '../core/sql.js';
4
- import { cwdParam } from './common.js';
4
+ import { workspaceParam } from './common.js';
5
5
  const FORUM_HASH = /^[0-9a-f]{40,64}$/i;
6
6
  function forumEventsSql(limit, search) {
7
7
  const where = [
@@ -53,8 +53,8 @@ function parseForumPost(row) {
53
53
  body,
54
54
  };
55
55
  }
56
- async function fetchPosts(cwd, limit, search) {
57
- const result = await runSql(forumEventsSql(limit, search), { cwd, readonly: true });
56
+ async function fetchPosts(workspace, limit, search) {
57
+ const result = await runSql(forumEventsSql(limit, search), { workspace, readonly: true });
58
58
  if (!result.ok)
59
59
  return { ok: false, error: result.error };
60
60
  const posts = [];
@@ -124,30 +124,33 @@ function countDescendants(root, posts) {
124
124
  }
125
125
  /** Forum tools (read-only). */
126
126
  export function registerForumTools(server) {
127
- const note = 'Forum access is read-only: Fossil 2.x has no CLI/API for creating forum posts (use the web UI).';
128
127
  server.registerTool('fossil_forum_list', {
129
128
  title: 'List forum threads',
130
- description: `List the most recent forum posts, newest first, with their thread root, author and reply count. ${note}`,
129
+ description: 'List the most recent forum posts, newest first, with their thread root, author and reply count.',
131
130
  inputSchema: z.object({
132
131
  limit: z.number().int().min(1).max(500).default(20).describe('How many forum events to scan.'),
133
- cwd: cwdParam,
132
+ workspace: workspaceParam,
134
133
  }),
135
134
  annotations: { readOnlyHint: true },
136
- }, async ({ limit, cwd }) => {
137
- const fetched = await fetchPosts(cwd, limit ?? 20);
135
+ }, async ({ limit, workspace }) => {
136
+ const fetched = await fetchPosts(workspace, limit ?? 20);
138
137
  if (!fetched.ok)
139
138
  return { content: [{ type: 'text', text: fetched.error }], isError: true };
140
139
  const { posts } = fetched;
141
140
  if (posts.length === 0) {
142
141
  return {
143
- content: [{ type: 'text', text: `No forum posts found in the last ${limit ?? 20} forum events. ${note}` }],
142
+ content: [{ type: 'text', text: `No forum posts found in the last ${limit ?? 20} forum events.` }],
144
143
  };
145
144
  }
146
145
  const byUuid = new Map(posts.map((post) => [post.uuid, post]));
147
146
  const lines = posts.map((post) => {
148
147
  const root = findRoot(post, byUuid);
149
148
  const replies = root.uuid === post.uuid ? countDescendants(root, posts) : undefined;
150
- const suffix = root.uuid === post.uuid ? (replies ? ` (${replies} replies)` : ' (thread)') : ` ↳ reply in thread ${shortHash(root.uuid)}`;
149
+ const suffix = root.uuid === post.uuid
150
+ ? replies
151
+ ? ` (${replies} ${replies === 1 ? 'reply' : 'replies'})`
152
+ : ' (thread)'
153
+ : ` ↳ reply in thread ${shortHash(root.uuid)}`;
151
154
  return `${post.at} ${shortHash(post.uuid)} ${post.user || 'unknown'} ${post.title}${suffix}`;
152
155
  });
153
156
  return { content: [{ type: 'text', text: truncateOutput(lines.join('\n')) }] };
@@ -155,16 +158,16 @@ export function registerForumTools(server) {
155
158
  server.registerTool('fossil_forum_read', {
156
159
  title: 'Read forum thread',
157
160
  description: `Print a forum thread (root post plus every reply found in the scanned window). ` +
158
- `Accepts any post hash in the thread; abbreviations work. ${note}`,
161
+ 'Accepts any post hash in the thread; abbreviations work.',
159
162
  inputSchema: z.object({
160
163
  thread: z.string().min(1).describe('Thread root hash, or the hash of any post in the thread (prefix allowed).'),
161
164
  limit: z.number().int().min(1).max(2000).default(500).describe('How many forum events to scan for replies.'),
162
- cwd: cwdParam,
165
+ workspace: workspaceParam,
163
166
  }),
164
167
  annotations: { readOnlyHint: true },
165
- }, async ({ thread, limit, cwd }) => {
168
+ }, async ({ thread, limit, workspace }) => {
166
169
  const scanLimit = limit ?? 500;
167
- const fetched = await fetchPosts(cwd, scanLimit);
170
+ const fetched = await fetchPosts(workspace, scanLimit);
168
171
  if (!fetched.ok)
169
172
  return { content: [{ type: 'text', text: fetched.error }], isError: true };
170
173
  const key = thread.trim().toLowerCase();
@@ -208,16 +211,16 @@ export function registerForumTools(server) {
208
211
  });
209
212
  server.registerTool('fossil_forum_search', {
210
213
  title: 'Search forum',
211
- description: `Case-insensitive substring search over forum post bodies and titles. ${note}`,
214
+ description: 'Case-insensitive substring search over forum post bodies and titles.',
212
215
  inputSchema: z.object({
213
216
  query: z.string().min(1).describe('Text to look for (substring, case-insensitive).'),
214
217
  limit: z.number().int().min(1).max(200).default(20).describe('Maximum matches to return.'),
215
- cwd: cwdParam,
218
+ workspace: workspaceParam,
216
219
  }),
217
220
  annotations: { readOnlyHint: true },
218
- }, async ({ query, limit, cwd }) => {
221
+ }, async ({ query, limit, workspace }) => {
219
222
  const searchLimit = limit ?? 20;
220
- const fetched = await fetchPosts(cwd, searchLimit, query);
223
+ const fetched = await fetchPosts(workspace, searchLimit, query);
221
224
  if (!fetched.ok)
222
225
  return { content: [{ type: 'text', text: fetched.error }], isError: true };
223
226
  if (fetched.posts.length === 0) {
@@ -1,6 +1,6 @@
1
1
  import { z } from 'zod';
2
2
  import { renderOutcome, runFossil, truncateOutput } from '../core/fossil.js';
3
- import { cwdParam } from './common.js';
3
+ import { flag, workspaceParam } from './common.js';
4
4
  const TICKET_FALLBACK_SQL = 'SELECT substr(tkt_uuid, 1, 10) AS id, title, status FROM ticket ORDER BY tkt_mtime DESC';
5
5
  /**
6
6
  * Ticket tools.
@@ -14,14 +14,15 @@ export function registerTicketTools(server) {
14
14
  description: 'Render a ticket report (default report 1). When the report is unavailable it falls back to a compact SQL listing.',
15
15
  inputSchema: z.object({
16
16
  report: z.string().min(1).default('1').describe('Ticket report number or name.'),
17
- cwd: cwdParam,
17
+ workspace: workspaceParam,
18
18
  }),
19
19
  annotations: { readOnlyHint: true },
20
- }, async ({ report, cwd }) => {
21
- const primary = await runFossil(['ticket', 'show', report ?? '1'], { cwd });
20
+ }, async ({ report, workspace }) => {
21
+ const primary = await runFossil(['ticket', 'show', report ?? '1'], { workspace });
22
22
  if (primary.ok)
23
23
  return renderOutcome(primary, { emptyText: 'No tickets.' });
24
- const fallback = await runFossil(['sql', '-header', '-column', TICKET_FALLBACK_SQL], { cwd });
24
+ // Read-only: the fallback only ever reads the ticket table.
25
+ const fallback = await runFossil(['sql', '--readonly', '-header', '-column', TICKET_FALLBACK_SQL], { workspace });
25
26
  if (fallback.ok && fallback.stdout.trim()) {
26
27
  return {
27
28
  content: [
@@ -35,6 +36,27 @@ export function registerTicketTools(server) {
35
36
  // Neither path worked: the original failure is the more useful message.
36
37
  return renderOutcome(primary);
37
38
  });
39
+ server.registerTool('fossil_ticket_show', {
40
+ title: 'Show ticket report',
41
+ description: "Render one ticket report with an optional WHERE filter, e.g. filter: \"status = 'Open'\". Report 0 lists every ticket column.",
42
+ inputSchema: z.object({
43
+ report: z.string().min(1).default('0').describe('Report number or title; 0 lists all ticket columns.'),
44
+ filter: z.string().min(1).optional().describe("Extra WHERE condition, e.g. \"status != 'open'\"."),
45
+ separator: z.string().min(1).optional().describe('Column separator (-l).'),
46
+ quote: flag('Encode special characters (--quote).'),
47
+ workspace: workspaceParam,
48
+ }),
49
+ annotations: { readOnlyHint: true },
50
+ }, async ({ report, filter, separator, quote, workspace }) => {
51
+ const args = ['ticket', 'show', report ?? '0'];
52
+ if (filter)
53
+ args.push(filter);
54
+ if (separator)
55
+ args.push('-l', separator);
56
+ if (quote)
57
+ args.push('-q');
58
+ return renderOutcome(await runFossil(args, { workspace }), { emptyText: 'No tickets.' });
59
+ });
38
60
  server.registerTool('fossil_ticket_create', {
39
61
  title: 'Create ticket',
40
62
  description: "Create a ticket. `additional_fields` is a flat list of field/value pairs, e.g. ['subsystem','UI','type','Bug'].",
@@ -45,9 +67,9 @@ export function registerTicketTools(server) {
45
67
  .array(z.string())
46
68
  .optional()
47
69
  .describe("Flat field/value pairs, e.g. ['subsystem','UI','priority','High']."),
48
- cwd: cwdParam,
70
+ workspace: workspaceParam,
49
71
  }),
50
- }, async ({ title, status, additional_fields, cwd }) => {
72
+ }, async ({ title, status, additional_fields, workspace }) => {
51
73
  if (additional_fields && additional_fields.length % 2 !== 0) {
52
74
  return {
53
75
  content: [
@@ -62,7 +84,7 @@ export function registerTicketTools(server) {
62
84
  const args = ['ticket', 'add', 'title', title, 'status', status ?? 'Open'];
63
85
  if (additional_fields?.length)
64
86
  args.push(...additional_fields);
65
- return renderOutcome(await runFossil(args, { cwd }), { note: 'Ticket created.' });
87
+ return renderOutcome(await runFossil(args, { workspace }), { note: 'Ticket created.' });
66
88
  });
67
89
  server.registerTool('fossil_ticket_update', {
68
90
  title: 'Update ticket',
@@ -71,10 +93,10 @@ export function registerTicketTools(server) {
71
93
  ticket_id: z.string().min(1).describe('Ticket UUID or prefix shown by the ticket list.'),
72
94
  field_name: z.string().min(1).describe('Field to change (status, subsystem, priority, comment, ...).'),
73
95
  field_value: z.string().describe('New value for the field.'),
74
- cwd: cwdParam,
96
+ workspace: workspaceParam,
75
97
  }),
76
98
  annotations: { idempotentHint: true },
77
- }, async ({ ticket_id, field_name, field_value, cwd }) => renderOutcome(await runFossil(['ticket', 'set', ticket_id, field_name, field_value], { cwd }), {
99
+ }, async ({ ticket_id, field_name, field_value, workspace }) => renderOutcome(await runFossil(['ticket', 'set', ticket_id, field_name, field_value], { workspace }), {
78
100
  note: `Ticket '${ticket_id}' updated: ${field_name} = '${field_value}'.`,
79
101
  }));
80
102
  }