| 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__ | ||