mcp-memory-bucket 0.2.2 → 0.3.0

package/dist/src/skills/tools.js

@@ -12,6 +12,35 @@ export function registerSkillTools(mcp, repo) {
         const items = repo.list(query, root);
         return { content: [{ type: 'text', text: JSON.stringify(items, null, 2) }] };
     });
+    mcp.tool('skill_search', 'Full-text search over skill description/body/tags (grep/find-like, ranked by relevance) — unlike skill_list\'s substring metadata filter, this searches the full markdown body. `query` is raw SQLite FTS5 MATCH syntax: bare words, "exact phrases", prefix* wildcards, AND/OR/NOT boolean operators; hyphenated/punctuated terms must be quoted, e.g. "blue-green". Can be combined with status/owner/tag filters. Returns ranked hits with a highlighted snippet, not the full body — call skill_get on a hit\'s name for that.', {
+        query: z.string().describe('FTS5 match expression, e.g. `deploy AND rollback` or `"blue green"`'),
+        status: z.enum(SKILL_STATUS).optional(),
+        owner: z.string().optional(),
+        tag: z.string().optional(),
+        limit: z.number().int().positive().max(100).optional(),
+        offset: z.number().int().nonnegative().optional(),
+        ...(multiRoot ? { root: z.string().optional().describe(`filter to one root: ${rootNames}`) } : {}),
+    }, async ({ query, status, owner, tag, limit, offset, root }) => {
+        try {
+            const hits = repo.search(query, { root, status, owner, tag, limit, offset });
+            return { content: [{ type: 'text', text: JSON.stringify(hits, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+    mcp.tool('skill_bulk_update', 'Applies the same frontmatter change to many skills at once by name — e.g. add/remove a tag across a batch found via skill_search, or flip status for a group. add_tags/remove_tags merge or subtract per-skill; owner/status/extends overwrite uniformly when provided. Body is never touched. Returns per-name success/failure so one bad name doesn\'t abort the batch.', {
+        names: z.array(z.string()).min(1),
+        add_tags: z.array(z.string()).optional(),
+        remove_tags: z.array(z.string()).optional(),
+        owner: z.string().nullable().optional(),
+        status: z.enum(SKILL_STATUS).optional(),
+        extends: z.string().nullable().optional(),
+        deprecated: z.boolean().optional().describe('marks skills as deprecated (or un-deprecates when false) — independent of status'),
+    }, async ({ names, add_tags, remove_tags, owner, status, extends: extendsId, deprecated }) => {
+        const results = repo.bulkUpdate(names, { add_tags, remove_tags, owner, status, extends: extendsId, deprecated });
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
     mcp.tool('skill_get', 'Fetches a single skill by name, including its full markdown body.', { name: z.string() }, async ({ name }) => {
         const doc = repo.get(name);
         if (!doc) {
@@ -19,6 +48,10 @@ export function registerSkillTools(mcp, repo) {
         }
         return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
     });
+    mcp.tool('skill_bulk_get', 'Fetches many skills by name in one call, including full markdown bodies — e.g. hydrating a batch of skill_search hits. Missing names are simply omitted from the result, not errors.', { names: z.array(z.string()).min(1) }, async ({ names }) => {
+        const docs = repo.bulkGet(names);
+        return { content: [{ type: 'text', text: JSON.stringify(docs, null, 2) }] };
+    });
     mcp.tool('skill_create', `Creates a new skill as <root>/[folder/]<name>/SKILL.md, per the agentskills.io open standard — a folder containing SKILL.md, optionally alongside scripts/references/assets subfolders you create separately on disk. ${AUTHORING_SKILL_HINT}`, {
         name: z.string().describe(SKILL_NAME_DESCRIPTION),
         description: z
@@ -44,6 +77,39 @@ export function registerSkillTools(mcp, repo) {
             return { content: [{ type: 'text', text: err.message }], isError: true };
         }
     });
+    const skillEntrySchema = z.object({
+        name: z.string().describe(SKILL_NAME_DESCRIPTION),
+        description: z.string().max(1024).describe('required by spec: what the skill does AND when to use it'),
+        body: z.string().describe('markdown body of SKILL.md'),
+        license: z.string().optional(),
+        compatibility: z.string().max(500).optional(),
+        owner: z.string().optional(),
+        status: z.enum(SKILL_STATUS).optional(),
+        tags: z.array(z.string()).optional(),
+        trigger_phrases: z.array(z.string()).optional(),
+        extends: z.string().optional(),
+        folder: z.string().optional(),
+        ...(multiRoot ? { root: z.string().describe(`which configured skill root to write into: ${rootNames}`) } : {}),
+    });
+    mcp.tool('skill_bulk_create', `Creates many skills in one call — each entry is the same shape as skill_create's args. Returns per-name success/failure so one bad entry (duplicate name, invalid name, existing directory) doesn't abort the rest of the batch. ${AUTHORING_SKILL_HINT}`, { entries: z.array(skillEntrySchema).min(1) }, async ({ entries }) => {
+        const results = repo.bulkCreate(entries.map((e) => ({
+            frontmatter: {
+                name: e.name,
+                description: e.description,
+                license: e.license,
+                compatibility: e.compatibility,
+                owner: e.owner,
+                status: e.status,
+                tags: e.tags,
+                trigger_phrases: e.trigger_phrases,
+                extends: e.extends,
+            },
+            body: e.body,
+            folder: e.folder,
+            root: e.root,
+        })));
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
     mcp.tool('skill_update', `Edits an existing skill in place — frontmatter fields and/or body. Only provided fields change. Use skill_rename to change the name/folder. ${AUTHORING_SKILL_HINT}`, {
         name: z.string(),
         description: z.string().max(1024).optional(),
@@ -55,6 +121,7 @@ export function registerSkillTools(mcp, repo) {
         tags: z.array(z.string()).optional(),
         trigger_phrases: z.array(z.string()).optional(),
         extends: z.string().optional(),
+        deprecated: z.boolean().optional().describe('marks the skill as deprecated (or un-deprecates when false) — independent of status'),
     }, async ({ name, body, ...frontmatterFields }) => {
         try {
             const doc = repo.update(name, frontmatterFields, body);
@@ -85,4 +152,8 @@ export function registerSkillTools(mcp, repo) {
             return { content: [{ type: 'text', text: err.message }], isError: true };
         }
     });
+    mcp.tool('skill_bulk_delete', 'Hard-deletes many skills by name in one call — e.g. cleaning up a batch found via skill_search/skill_list. No tombstone. Returns per-name success/failure so one bad name doesn\'t abort the rest of the batch.', { names: z.array(z.string()).min(1) }, async ({ names }) => {
+        const results = repo.bulkDelete(names);
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
 }

package/dist/src/store/db.js

@@ -13,6 +13,8 @@ export function openCache(dbPath) {
       extends TEXT,
       source_path TEXT NOT NULL UNIQUE, -- path to SKILL.md
       root TEXT NOT NULL DEFAULT '',  -- name of the configured root this file lives under
+      deprecated INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT,
       body TEXT NOT NULL,
       mtime_ms INTEGER NOT NULL
     );
@@ -28,6 +30,8 @@ export function openCache(dbPath) {
       related_to TEXT,
       source_path TEXT NOT NULL UNIQUE,
       root TEXT NOT NULL DEFAULT '',  -- name of the configured root this file lives under
+      deprecated INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT,
       body TEXT NOT NULL,
       mtime_ms INTEGER NOT NULL
     );
@@ -43,17 +47,26 @@ export function openCache(dbPath) {
       tokenize = 'porter unicode61'
     );
   `);
-    addRootColumnIfMissing(db, 'skills');
-    addRootColumnIfMissing(db, 'memory_docs');
+    ensureColumns(db, 'skills', [
+        ['root', "TEXT NOT NULL DEFAULT ''"],
+        ['deprecated', 'INTEGER NOT NULL DEFAULT 0'],
+        ['created_at', 'TEXT'],
+    ]);
+    ensureColumns(db, 'memory_docs', [
+        ['root', "TEXT NOT NULL DEFAULT ''"],
+        ['deprecated', 'INTEGER NOT NULL DEFAULT 0'],
+        ['created_at', 'TEXT'],
+    ]);
     backfillSearchIndex(db);
     return db;
 }
-/** Migration for cache files created before the `root` column existed. */
-function addRootColumnIfMissing(db, table) {
-    const columns = db.prepare(`PRAGMA table_info(${table})`).all();
-    if (columns.some((c) => c.name === 'root'))
-        return;
-    db.exec(`ALTER TABLE ${table} ADD COLUMN root TEXT NOT NULL DEFAULT ''`);
+/** Migration for cache files created before a given column existed. Safe to call every startup. */
+function ensureColumns(db, table, columns) {
+    const existing = new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((c) => c.name));
+    for (const [name, ddlType] of columns) {
+        if (!existing.has(name))
+            db.exec(`ALTER TABLE ${table} ADD COLUMN ${name} ${ddlType}`);
+    }
 }
 /** One-time backfill for existing rows the first time search_index is introduced into a cache file. */
 function backfillSearchIndex(db) {

package/dist/src/store/search.js

@@ -0,0 +1,60 @@
+/** A quoted FTS5 syntax error, translated into something an agent can act on without seeing raw SQLite internals. */
+export class SearchQueryError extends Error {
+    constructor(query, cause) {
+        super(`invalid search query "${query}": ${cause.message}. ` +
+            `FTS5 syntax notes: hyphenated/punctuated words must be quoted (e.g. "blue-green"), ` +
+            `bare words are AND'd by default, use OR/NOT for other logic, "exact phrase" for phrases, and prefix* for prefix matching.`);
+        this.name = 'SearchQueryError';
+    }
+}
+/**
+ * Full-text search over the shared FTS5 index, optionally scoped to one ref_table.
+ * `query` is passed through as raw FTS5 MATCH syntax — supports `AND`/`OR`/`NOT`,
+ * `"exact phrases"`, and `prefix*` — so callers get grep-like power for free.
+ * Ranked by bm25() (lower is better, so we negate for a "higher is better" score).
+ * Throws SearchQueryError on malformed FTS5 syntax instead of a raw SQLite error.
+ */
+export function searchIndex(db, query, opts = {}) {
+    const { table, limit = 20, offset = 0 } = opts;
+    try {
+        const rows = db
+            .prepare(`SELECT ref_table, ref_id,
+                snippet(search_index, 3, '<<', '>>', '…', 20) AS snippet,
+                -bm25(search_index) AS score
+         FROM search_index
+         WHERE search_index MATCH ? ${table ? 'AND ref_table = ?' : ''}
+         ORDER BY bm25(search_index)
+         LIMIT ? OFFSET ?`)
+            .all(...(table ? [query, table, limit, offset] : [query, limit, offset]));
+        return rows;
+    }
+    catch (err) {
+        throw new SearchQueryError(query, err);
+    }
+}
+/**
+ * Full-text search across BOTH skills and memory docs in one ranked list —
+ * for the common case of "find where I put X" when the caller doesn't know
+ * which bucket it landed in. No metadata filters (doc_type/status/tag differ
+ * per table); use skill_search/memory_search directly when filtering by those.
+ */
+export function searchCombined(db, query, limit = 20, offset = 0) {
+    try {
+        return db
+            .prepare(`SELECT ref_table, ref_id AS id,
+                COALESCE(s.description, m.description) AS description,
+                COALESCE(s.root, m.root) AS root,
+                snippet(search_index, 3, '<<', '>>', '…', 20) AS snippet,
+                -bm25(search_index) AS score
+         FROM search_index
+         LEFT JOIN skills s ON search_index.ref_table = 'skills' AND s.id = search_index.ref_id
+         LEFT JOIN memory_docs m ON search_index.ref_table = 'memory_docs' AND m.id = search_index.ref_id
+         WHERE search_index MATCH ?
+         ORDER BY bm25(search_index)
+         LIMIT ? OFFSET ?`)
+            .all(query, limit, offset);
+    }
+    catch (err) {
+        throw new SearchQueryError(query, err);
+    }
+}

package/dist/src/store/sync.js

@@ -3,8 +3,8 @@ import path from 'node:path';
 import chokidar, {} from 'chokidar';
 import { readMarkdownFile } from './markdown-file.js';
 import { flattenTags } from './db.js';
-const skillColumns = ['id', 'description', 'owner', 'status', 'tags', 'trigger_phrases', 'extends'];
-const memoryColumns = ['id', 'key', 'key_type', 'description', 'doc_type', 'tags', 'status', 'related_to'];
+const skillColumns = ['id', 'description', 'owner', 'status', 'tags', 'trigger_phrases', 'extends', 'deprecated', 'created_at'];
+const memoryColumns = ['id', 'key', 'key_type', 'description', 'doc_type', 'tags', 'status', 'related_to', 'deprecated', 'created_at'];
 export function skillSyncSpec(sources) {
     return {
         table: 'skills',
@@ -20,6 +20,8 @@ export function skillSyncSpec(sources) {
             tags: JSON.stringify(fm.tags ?? []),
             trigger_phrases: JSON.stringify(fm.trigger_phrases ?? []),
             extends: fm.metadata?.extends ?? null,
+            deprecated: fm.deprecated ? 1 : 0,
+            created_at: fm.created_at ?? null,
         }),
     };
 }
@@ -39,6 +41,8 @@ export function memorySyncSpec(sources) {
             tags: JSON.stringify(fm.tags ?? []),
             status: fm.status ?? 'active',
             related_to: fm.related_to ?? null,
+            deprecated: fm.deprecated ? 1 : 0,
+            created_at: fm.created_at ?? null,
         }),
     };
 }

package/dist/src/web/routes.js

@@ -23,6 +23,8 @@ function queryEntries(db, req) {
     const keyTypes = asArray(req.query.key_type);
     const roots = asArray(req.query.root);
     const q = req.query.q?.trim();
+    const deprecatedParam = req.query.deprecated;
+    const deprecated = deprecatedParam === '0' || deprecatedParam === '1' ? deprecatedParam : undefined;
     const matchedIds = q
         ? matchSearch(db, q)
         : null;
@@ -31,10 +33,10 @@ function queryEntries(db, req) {
     }
     const results = [];
     if (type === 'skill' || type === 'all') {
-        results.push(...queryTable(db, 'skills', { tags, statuses, owners, docTypes: [], keyTypes: [], roots }, matchedIds?.skills));
+        results.push(...queryTable(db, 'skills', { tags, statuses, owners, docTypes: [], keyTypes: [], roots, deprecated }, matchedIds?.skills));
     }
     if (type === 'memory' || type === 'all') {
-        results.push(...queryTable(db, 'memory_docs', { tags, statuses, owners: [], docTypes, keyTypes, roots }, matchedIds?.memory_docs));
+        results.push(...queryTable(db, 'memory_docs', { tags, statuses, owners: [], docTypes, keyTypes, roots, deprecated }, matchedIds?.memory_docs));
     }
     const sort = req.query.sort ?? 'mtime_desc';
     results.sort((a, b) => {
@@ -42,6 +44,15 @@ function queryEntries(db, req) {
             return a.mtime_ms - b.mtime_ms;
         if (sort === 'name_asc')
             return a.name.localeCompare(b.name);
+        if (sort === 'created_at_asc') {
+            if (!a.created_at && !b.created_at)
+                return 0;
+            if (!a.created_at)
+                return 1; // missing created_at sorts last
+            if (!b.created_at)
+                return -1;
+            return a.created_at.localeCompare(b.created_at);
+        }
         return b.mtime_ms - a.mtime_ms; // mtime_desc, default
     });
     return results;
@@ -74,13 +85,17 @@ function queryTable(db, table, filters, restrictToIds) {
         where += ` AND root IN (${filters.roots.map(() => '?').join(', ')})`;
         params.push(...filters.roots);
     }
+    if (filters.deprecated !== undefined) {
+        where += ` AND deprecated = ?`;
+        params.push(filters.deprecated === '1' ? 1 : 0);
+    }
     if (restrictToIds) {
         where += ` AND id IN (${[...restrictToIds].map(() => '?').join(', ')})`;
         params.push(...restrictToIds);
     }
     if (table === 'skills') {
         const rows = db
-            .prepare(`SELECT id, description, owner, status, tags, root, mtime_ms FROM skills WHERE ${where}`)
+            .prepare(`SELECT id, description, owner, status, tags, root, mtime_ms, deprecated, created_at FROM skills WHERE ${where}`)
             .all(...params);
         return rows.map((r) => ({
             _table: 'skills',
@@ -94,10 +109,12 @@ function queryTable(db, table, filters, restrictToIds) {
             key_type: null,
             root: r.root,
             mtime_ms: r.mtime_ms,
+            deprecated: !!r.deprecated,
+            created_at: r.created_at,
         }));
     }
     const rows = db
-        .prepare(`SELECT id, key, description, doc_type, key_type, status, tags, root, mtime_ms FROM memory_docs WHERE ${where}`)
+        .prepare(`SELECT id, key, description, doc_type, key_type, status, tags, root, mtime_ms, deprecated, created_at FROM memory_docs WHERE ${where}`)
         .all(...params);
     return rows.map((r) => ({
         _table: 'memory_docs',
@@ -111,6 +128,8 @@ function queryTable(db, table, filters, restrictToIds) {
         key_type: r.key_type,
         root: r.root,
         mtime_ms: r.mtime_ms,
+        deprecated: !!r.deprecated,
+        created_at: r.created_at,
     }));
 }
 /** Runs the FTS5 query once and buckets matching ids by source table. */
@@ -219,6 +238,81 @@ export function buildWebRouter(db, config, skillRepo, memoryRepo) {
         const trigger_phrases = row.trigger_phrases ? JSON.parse(row.trigger_phrases) : undefined;
         res.json({ ...row, tags, trigger_phrases });
     });
+    router.patch('/api/entries/:table/:id/deprecated', (req, res) => {
+        const { table, id } = req.params;
+        const { deprecated } = req.body;
+        if (table !== 'skills' && table !== 'memory_docs') {
+            res.status(400).json({ error: 'table must be "skills" or "memory_docs"' });
+            return;
+        }
+        if (!id) {
+            res.status(400).json({ error: 'id is required' });
+            return;
+        }
+        if (typeof deprecated !== 'boolean') {
+            res.status(400).json({ error: 'body must be { deprecated: boolean }' });
+            return;
+        }
+        try {
+            if (table === 'skills')
+                skillRepo.update(id, { deprecated });
+            else
+                memoryRepo.update(id, { deprecated });
+            res.json({ id, deprecated });
+        }
+        catch (err) {
+            res.status(404).json({ error: err.message });
+        }
+    });
+    router.post('/api/entries/:table/bulk/deprecated', (req, res) => {
+        const { table } = req.params;
+        const { ids, deprecated } = req.body;
+        if (table !== 'skills' && table !== 'memory_docs') {
+            res.status(400).json({ error: 'table must be "skills" or "memory_docs"' });
+            return;
+        }
+        if (!Array.isArray(ids) || ids.length === 0 || typeof deprecated !== 'boolean') {
+            res.status(400).json({ error: 'body must be { ids: string[], deprecated: boolean }' });
+            return;
+        }
+        const results = table === 'skills' ? skillRepo.bulkUpdate(ids, { deprecated }) : memoryRepo.bulkUpdate(ids, { deprecated });
+        res.json({ results });
+    });
+    router.delete('/api/entries/:table/:id', (req, res) => {
+        const { table, id } = req.params;
+        if (table !== 'skills' && table !== 'memory_docs') {
+            res.status(400).json({ error: 'table must be "skills" or "memory_docs"' });
+            return;
+        }
+        if (!id) {
+            res.status(400).json({ error: 'id is required' });
+            return;
+        }
+        try {
+            if (table === 'skills')
+                skillRepo.delete(id);
+            else
+                memoryRepo.delete(id);
+            res.json({ deleted: id });
+        }
+        catch (err) {
+            res.status(404).json({ error: err.message });
+        }
+    });
+    router.post('/api/entries/:table/bulk/delete', (req, res) => {
+        const { table } = req.params;
+        const { ids } = req.body;
+        if (table !== 'skills' && table !== 'memory_docs') {
+            res.status(400).json({ error: 'table must be "skills" or "memory_docs"' });
+            return;
+        }
+        if (!Array.isArray(ids) || ids.length === 0) {
+            res.status(400).json({ error: 'body must be { ids: string[] }' });
+            return;
+        }
+        const results = table === 'skills' ? skillRepo.bulkDelete(ids) : memoryRepo.bulkDelete(ids);
+        res.json({ results });
+    });
     router.get('/api/facets', (req, res) => {
         const type = req.query.type ?? 'all';
         res.json(buildFacets(db, type));

package/dist/src/web/ui-tool.js

@@ -1,5 +1,5 @@
 export function registerUiTool(mcp, port) {
-    mcp.tool('bucket_open_ui', 'Returns the URL for the mem-bucket web viewer — a read-only browser UI for searching/filtering skills and memory docs by tag, status, owner, and fulltext. Not for editing; use the skill_*/memory_* tools for that.', {}, async () => {
+    mcp.tool('bucket_open_ui', 'Returns the URL for the mem-bucket web viewer — a browser UI for searching/filtering skills and memory docs by tag, status, owner, deprecated flag, and fulltext, sorting by creation date, and marking items deprecated or deleting them (single or bulk). For anything beyond that, use the skill_*/memory_* tools instead.', {}, async () => {
         const url = `http://localhost:${port}/`;
         return { content: [{ type: 'text', text: url }] };
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-memory-bucket",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "MCP server exposing skill_* (reusable coding patterns) and memory_* (point-in-time working context) tools over a markdown+frontmatter source, cached into SQLite at runtime.",
   "repository": {