KnowledgeStore/Tools/Revisioned.pm

filter: Statementstmt 60.0% 3 / 5 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 2 / 2 Podpod n/a totaltotal 71.4% 5 / 7 CC 1 SCAR 1.4
CC
1
Cov
60%
BEGIN
1.3
BEGIN
1.0
CRAP 1.1
« KnowledgeStore/Tools.pm ↑ Summary KnowledgeStore/Tools/Support.pm »
1 package MCP::Server::KnowledgeStore::Tools::Revisioned;
2 1 ▶use v5.38;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 0 ▶use Mojo::Base -strict, -signatures;
Subroutine BEGIN: called CC=1 SCAR=2.6
4  
5 our $VERSION = '0.001';
6  
7 # ABSTRACT: Generic tool set for a revisioned, taggable, project-scoped resource
8  
9 use Carp qw(croak);
10 use Mojo::JSON qw(true false);
11 use MCP::Server::KnowledgeStore::Tools::Support qw(
12 name_pattern summary author revision_property author_property
13 project_property
14 );
15  
16 my $NAME_PATTERN = name_pattern;
17  
18 # Memory and skill were two ~150-line files that differed only in
19 # whether they have `type` and `search`, and in their name. This is
20 # that shared shape, factored out - a resource registers by calling
21 # this once with its own kind and a backend, instead of writing out
22 # list/get/save/revisions/useful/tag/untag by hand.
23 sub register ($class, $server, $backend, %config) {
24 my $kind = $config{kind} or croak 'kind is required';
25 my $plural = $config{plural} // "${kind}s";
26 my $has_type = $config{type} // 0;
27 my $has_search = $config{search} // 0;
28 my $allow_purge = exists $config{allow_purge} ? $config{allow_purge} : 1;
29  
30 $server->tool(
31 name => "list_${plural}",
32 description => "List $kind entries, optionally filtered by project",
33 input_schema => {
34 type => 'object',
35 properties => project_property(),
36 additionalProperties => false,
37 },
38 code => sub ($tool, $args) {
39 my $entries = $backend->list($kind, $args->{project});
40 return $tool->structured_result(
41 { $plural => [map { summary($_) } @$entries] });
42 },
43 );
44  
45 if ($has_search) {
46 $server->tool(
47 name => "search_${plural}",
48 description =>
49 "Search across $kind frontmatter and bodies. Postgres tsvector "
50 . "picks the candidates, TF-IDF corpus vectors rank them.",
51 input_schema => {
52 type => 'object',
53 properties => {
54 query => { type => 'string', description => 'Text to search for' },
55 limit => {
56 type => 'integer',
57 minimum => 1,
58 maximum => 100,
59 default => 10,
60 description => 'Maximum number of results (default: 10)'
61 },
62 project_property()->%*,
63 },
64 required => ['query'],
65 additionalProperties => false,
66 },
67 code => sub ($tool, $args) {
68 my $hits = $backend->search($kind, $args->{query}, $args->{project},
69 $args->{limit} // 10);
70 return $tool->structured_result(
71 {
72 $plural => [
73 map {
74 {
75 summary($_)->%*,
76 matches => $_->{matches},
77 rank => $_->{rank},
78 ts_rank => $_->{ts_rank}
79 }
80 } @$hits
81 ]
82 }
83 );
84 },
85 );
86 }
87  
88  
89 $server->tool(
90 name => "get_${kind}",
91 description =>
92 "Fetch the full content of one $kind, at its current or an older revision",
93 input_schema => {
94 type => 'object',
95 properties => {
96 name => { type => 'string', pattern => $NAME_PATTERN },
97 revision_property()->%*,
98 },
99 required => ['name'],
100 additionalProperties => false,
101 },
102 code => sub ($tool, $args) {
103 my $entry = $backend->get($kind, $args->{name}, $args->{revision});
104 return $tool->text_result(
105 "No $kind named '$args->{name}'"
106 . (
107 defined $args->{revision} ? " at revision $args->{revision}" : ''
108 ),
109 1
110 ) unless $entry;
111 return $entry->{content};
112 },
113 );
114  
115 my %save_properties = (
116 name => { type => 'string', pattern => $NAME_PATTERN },
117 content => $has_type
118 ? {
119 type => 'string',
120 description =>
121 'Markdown body. Frontmatter it carries is read into metadata.',
122 }
123 : { type => 'string' },
124 description => { type => 'string' },
125 project_property()->%*,
126 author_property()->%*,
127 );
128 $save_properties{type}
129 = { type => 'string', enum => [qw(user feedback project reference)] }
130 if $has_type;
131 my @save_fields
132 = $has_type ? qw(type description project) : qw(description project);
133  
134 $server->tool(
135 name => "save_${kind}",
136 description =>
137 "Save a $kind as a new revision in the shared store. project, if "
138 . 'given, adds a project tag - it does not replace existing tags; '
139 . "use untag_${kind} to remove one.",
140 input_schema => {
141 type => 'object',
142 properties => \%save_properties,
143 required => [qw(name content), ($has_type ? 'type' : ())],
144 additionalProperties => false,
145 },
146 code => sub ($tool, $args) {
147 my $entry = $backend->save(
148 $kind, $args->{name}, $args->{content},
149 author => author($tool, $args),
150 map { defined $args->{$_} ? ($_ => $args->{$_}) : () } @save_fields
151 );
152 return $tool->structured_result(
153 { name => $entry->{name}, revision => $entry->{revision} });
154 },
155 );
156  
157 $server->tool(
158 name => "list_${kind}_revisions",
159 description => "List every saved revision of one $kind, newest first",
160 input_schema => {
161 type => 'object',
162 properties => { name => { type => 'string', pattern => $NAME_PATTERN } },
163 required => ['name'],
164 additionalProperties => false,
165 },
166 code => sub ($tool, $args) {
167 my $history = $backend->history($kind, $args->{name});
168 return $tool->text_result("No $kind named '$args->{name}'", 1)
169 unless @$history;
170 my @revisions;
171 for my $row (@$history) {
172 push @revisions,
173 {
174 revision => $row->{revision},
175 description => $row->{description},
176 created_at => "$row->{created_at}",
177 is_head => $row->{is_head} ? true : false,
178 map { defined $row->{$_} ? ($_ => $row->{$_}) : () }
179 qw(author type project),
180 };
181 }
182 return $tool->structured_result({ revisions => \@revisions });
183 },
184 );
185  
186 $server->tool(
187 name => "mark_${kind}_useful",
188 description =>
189 "Record that a $kind was useful, incrementing its useful_count",
190 input_schema => {
191 type => 'object',
192 properties => { name => { type => 'string', pattern => $NAME_PATTERN } },
193 required => ['name'],
194 additionalProperties => false,
195 },
196 code => sub ($tool, $args) {
197 my $count = eval { $backend->mark_useful($kind, $args->{name}) };
198 return $tool->text_result("No $kind named '$args->{name}'", 1)
199 unless defined $count;
200 return $tool->structured_result(
201 { name => $args->{name}, useful_count => $count });
202 },
203 );
204  
205 $server->tool(
206 name => "tag_${kind}",
207 description => "Tag a $kind as relevant to a project (additive - "
208 . 'does not remove other tags)',
209 input_schema => {
210 type => 'object',
211 properties => {
212 name => { type => 'string', pattern => $NAME_PATTERN },
213 project => { type => 'string' },
214 },
215 required => [qw(name project)],
216 additionalProperties => false,
217 },
218 code => sub ($tool, $args) {
219 eval { $backend->tag($kind, $args->{name}, $args->{project}) };
220 return $tool->text_result("No $kind named '$args->{name}'", 1) if $@;
221 return $tool->structured_result(
222 { name => $args->{name}, project => $args->{project} });
223 },
224 );
225  
226 $server->tool(
227 name => "untag_${kind}",
228 description => "Remove a project tag from a $kind",
229 input_schema => {
230 type => 'object',
231 properties => {
232 name => { type => 'string', pattern => $NAME_PATTERN },
233 project => { type => 'string' },
234 },
235 required => [qw(name project)],
236 additionalProperties => false,
237 },
238 code => sub ($tool, $args) {
239 $backend->untag($kind, $args->{name}, $args->{project});
240 return $tool->structured_result(
241 { name => $args->{name}, project => $args->{project} });
242 },
243 );
244  
245 # Archive (soft delete) an entry
246 $server->tool(
247 name => "archive_${kind}",
248 description =>
249 "Archive (soft delete) a $kind. Hides it from normal operations "
250 . 'but keeps all data and revision history for possible restoration.',
251 input_schema => {
252 type => 'object',
253 properties => {
254 name => { type => 'string', pattern => $NAME_PATTERN },
255 expected_revision => {
256 type => 'integer',
257 minimum => 1,
258 description =>
259 'Optional: verify this revision before archiving to prevent stale operations',
260 },
261 author => {
262 type => 'string',
263 description => 'Who to record as performing the archive'
264 },
265 reason =>
266 { type => 'string', description => 'Optional reason for archiving' },
267 },
268 required => [qw(name)],
269 additionalProperties => false,
270 },
271 code => sub ($tool, $args) {
272 my $author = author($tool, $args);
273 my $entry = eval {
274 $backend->archive(
275 $kind, $args->{name},
276 author => $author,
277 expected_revision => $args->{expected_revision},
278 reason => $args->{reason},
279 );
280 };
281 return $tool->text_result(
282 "No $kind named '$args->{name}' or already archived", 1)
283 if $@ && $@ =~ /no \Q$kind\E named/;
284 return $tool->text_result($@, 1) if $@;
285 return $tool->text_result("Already archived: $args->{name}", 1)
286 unless $entry;
287 return $tool->structured_result(
288 {
289 name => $entry->{name},
290 revision => $entry->{revision},
291 archived_at => "$entry->{archived_at}",
292 }
293 );
294 },
295 );
296  
297 # Restore an archived entry
298 $server->tool(
299 name => "restore_${kind}",
300 description =>
301 "Restore a previously archived $kind, making it visible again",
302 input_schema => {
303 type => 'object',
304 properties => {
305 name => { type => 'string', pattern => $NAME_PATTERN },
306 author => {
307 type => 'string',
308 description => 'Who to record as performing the restore'
309 },
310 reason =>
311 { type => 'string', description => 'Optional reason for restoring' },
312 },
313 required => [qw(name)],
314 additionalProperties => false,
315 },
316 code => sub ($tool, $args) {
317 my $author = author($tool, $args);
318 my $entry = eval {
319 $backend->restore(
320 $kind, $args->{name},
321 author => $author,
322 reason => $args->{reason}
323 );
324 };
325 return $tool->text_result($@, 1) if $@;
326 return $tool->text_result("No archived $kind named '$args->{name}'", 1)
327 unless $entry;
328 return $tool->structured_result(
329 {
330 name => $entry->{name},
331 revision => $entry->{revision},
332 }
333 );
334 },
335 );
336  
337 # Permanently purge an entry (destructive, cannot be undone)
338 $server->tool(
339 name => "purge_${kind}",
340 description => "Permanently delete a $kind and ALL its revision history. "
341 . (
342 $allow_purge
343 ? 'This is destructive and cannot be undone.'
344 : 'DISABLED on this server'
345 ),
346 input_schema => {
347 type => 'object',
348 properties => {
349 name => { type => 'string', pattern => $NAME_PATTERN },
350 expected_revision => {
351 type => 'integer',
352 minimum => 1,
353 description =>
354 'Optional: verify this revision before purging to prevent stale operations',
355 },
356 author => {
357 type => 'string',
358 description => 'Who to record as performing the purge'
359 },
360 reason => {
361 type => 'string',
362 description => 'Optional reason for permanent deletion'
363 },
364 },
365 required => [qw(name)],
366 additionalProperties => false,
367 },
368 code => sub ($tool, $args) {
369 return $tool->text_result("purge_${kind} is disabled on this server", 1)
370 unless $allow_purge;
371  
372 my $author = author($tool, $args);
373 my $result = eval {
374 $backend->purge(
375 $kind, $args->{name},
376 author => $author,
377 expected_revision => $args->{expected_revision},
378 reason => $args->{reason},
379 );
380 };
381 return $tool->text_result($@, 1) if $@;
382 return $tool->structured_result($result);
383 },
384 );
385  
386 # List archived entries
387 $server->tool(
388 name => "list_archived_${plural}",
389 description =>
390 "List archived $kind entries, optionally filtered by project",
391 input_schema => {
392 type => 'object',
393 properties => project_property(),
394 additionalProperties => false,
395 },
396 code => sub ($tool, $args) {
397 my $entries = $backend->list_archived($kind, $args->{project});
398 return $tool->structured_result(
399 { $plural => [map { summary($_) } @$entries] });
400 },
401 );
402  
403 # Add MCP Resource Templates
404 # These provide addressable reads via URIs as an alternative to get_* tools
405 if ($server->can('add_template')) {
406 my $uri_prefix = "${kind}://${plural}";
407  
408 $server->add_template(
409 uri_template => "$uri_prefix/{name}",
410 name => "${kind}_read",
411 description => "Read the current revision of a $kind by name",
412 mime_type => 'text/markdown',
413 code => sub ($template, $params, $context) {
414 my $name = $params->{name};
415 my $entry = $backend->get($kind, $name);
416 return undef unless $entry;
417 return $entry->{content};
418 },
419 );
420  
421 $server->add_template(
422 uri_template => "$uri_prefix/{name}/revisions/{revision}",
423 name => "${kind}_read_revision",
424 description =>
425 "Read a specific revision of a $kind by name and revision number",
426 mime_type => 'text/markdown',
427 code => sub ($template, $params, $context) {
428 my $name = $params->{name};
429 my $revision = $params->{revision};
430 my $entry = $backend->get($kind, $name, $revision);
431 return undef unless $entry;
432 return $entry->{content};
433 },
434 );
435 }
436  
437 return;
438 }
439  
440 1;
441  
442 __END__
« KnowledgeStore/Tools.pm ↑ Summary KnowledgeStore/Tools/Support.pm »