mcp-memory-keeper 0.10.2 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-02-06
+
+### Added
+
+- **Selective Tool Filtering via Profiles** (#29)
+  - Control which tools are exposed to reduce context window usage (~10-15K tokens saved with minimal profile)
+  - Three built-in profiles: `minimal` (8 tools), `standard` (22 tools), `full` (38 tools, default)
+  - `TOOL_PROFILE` environment variable to select active profile at startup
+  - `TOOL_PROFILE_CONFIG` environment variable to specify custom config file path
+  - Custom profile definitions via `~/.mcp-memory-keeper/config.json`
+  - Config file profiles take precedence over built-in defaults
+  - Helpful error messages when disabled tools are called, with guidance on enabling them
+  - Startup logging shows active profile, tool count, and source
+  - Example config file included in `examples/config.json`
+
+### Technical
+
+- New `src/utils/tool-profiles.ts` module with `ALL_TOOL_NAMES` source of truth
+- `ToolName` union type for compile-time safety
+- Deep config validation (guards against malformed JSON, null values, non-array profiles, non-string elements)
+- Drift-detection integration test verifies `ALL_TOOL_NAMES` stays in sync with `index.ts` tool definitions
+- Defense-in-depth: both `ListTools` filtering and `CallTool` guard for disabled tools
+- 100% backwards compatible — no env var + no config = all 38 tools (existing behavior unchanged)
+- All 1185 tests passing across Node.js 20, 22, and 24
+
+## [0.11.0] - 2025-12-10
+
+### Breaking Changes
+
+- **Node.js 18 support dropped** - Minimum required Node.js version is now 20.0.0
+  - Node.js 18 reached End-of-Life on April 30, 2025
+  - Users on Node.js 18 must upgrade to Node.js 20 or later
+  - Existing installations will continue working until updated
+
+### Fixed
+
+- **Installation fails on Node.js 24 (#28)** - Updated `better-sqlite3` dependency
+  - Upgraded from `^11.10.0` to `^12.1.0` to support Node.js 24 (LTS "Krypton")
+  - Prebuilt binaries now available for Node.js 20, 22, and 24
+  - Resolves `gyp ERR!` build failures on Node.js 24
+
 ## [0.10.2] - 2025-09-16
 
 ### Fixed
@@ -450,7 +491,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Security**: Security updates
 - **Technical**: Internal improvements
 
-[Unreleased]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.10.0...HEAD
+[Unreleased]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.11.0...v0.12.0
+[0.11.0]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.10.2...v0.11.0
+[0.10.2]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.10.1...v0.10.2
+[0.10.1]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.10.0...v0.10.1
 [0.10.0]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.8.4...v0.9.0
 [0.8.4]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.8.3...v0.8.4

package/README.md

@@ -213,6 +213,92 @@ export MCP_MAX_ITEMS=50             # Fewer items per response
 export MCP_CHARS_PER_TOKEN=3.0      # More conservative estimation (optional)
 ```
 
+#### Tool Profiles
+
+By default, all 38 tools are exposed. To reduce context overhead in your AI assistant, you can activate a tool profile that limits which tools are available.
+
+**Quick usage:**
+
+```bash
+# Essential tools only (8 tools)
+TOOL_PROFILE=minimal npx mcp-memory-keeper
+
+# Standard workflow set (22 tools)
+TOOL_PROFILE=standard npx mcp-memory-keeper
+
+# All tools (default)
+TOOL_PROFILE=full npx mcp-memory-keeper
+```
+
+**Built-in profiles:**
+
+| Profile    | Tools | Description                                                    |
+| ---------- | ----- | -------------------------------------------------------------- |
+| `minimal`  | 8     | Core persistence: save, get, search, status, checkpoint        |
+| `standard` | 22    | Daily workflow: core + git, batch ops, channels, export/import |
+| `full`     | 38    | All tools (default, backwards compatible)                      |
+
+**Custom profiles via config file:**
+
+Create `~/.mcp-memory-keeper/config.json` to define or override profiles:
+
+```json
+{
+  "profiles": {
+    "my_workflow": [
+      "context_session_start",
+      "context_save",
+      "context_get",
+      "context_search",
+      "context_checkpoint",
+      "context_restore_checkpoint",
+      "context_diff",
+      "context_timeline"
+    ]
+  }
+}
+```
+
+Then activate it: `TOOL_PROFILE=my_workflow npx mcp-memory-keeper`
+
+Config file profiles take precedence over built-in defaults with the same name.
+
+**Profile resolution precedence:**
+
+| `TOOL_PROFILE` | Config file has profile? | Built-in exists? | Result                           |
+| -------------- | ------------------------ | ---------------- | -------------------------------- |
+| Set            | Yes                      | —                | Uses config file definition      |
+| Set            | No                       | Yes              | Uses built-in definition         |
+| Set            | No                       | No               | Warning + falls back to `full`   |
+| Not set        | —                        | —                | Uses built-in `full` (all tools) |
+
+**Environment variables:**
+
+| Variable              | Description                                                               |
+| --------------------- | ------------------------------------------------------------------------- |
+| `TOOL_PROFILE`        | Profile name to activate (e.g., `minimal`, `standard`, `full`, or custom) |
+| `TOOL_PROFILE_CONFIG` | Override config file path (default: `~/.mcp-memory-keeper/config.json`)   |
+
+> Note: Profile resolution happens once at server startup. Changes to the env var or config file take effect on the next server restart.
+
+**Claude Code / Claude Desktop configuration:**
+
+```json
+{
+  "mcpServers": {
+    "memory-keeper": {
+      "command": "npx",
+      "args": ["mcp-memory-keeper"],
+      "env": {
+        "TOOL_PROFILE": "minimal"
+      }
+    }
+  }
+}
+```
+
+See `examples/config.json` for a complete example config file.
+
 ### Claude Code (CLI)
 
 #### Configuration Scopes

package/dist/__tests__/integration/git-integration.test.js

@@ -58,6 +58,9 @@ describe('Git Integration Tests', () => {
         await git.init();
         await git.addConfig('user.name', 'Test User');
         await git.addConfig('user.email', 'test@example.com');
+        // Use repo-local hooks directory to prevent global hooks from interfering
+        const localHooksDir = path.join(tempRepoPath, '.git', 'hooks');
+        await git.addConfig('core.hooksPath', localHooksDir);
         // Create initial commit
         fs.writeFileSync(path.join(tempRepoPath, 'README.md'), '# Test Repo');
         await git.add('.');

package/dist/__tests__/integration/issue-token-limit-channel-query.test.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Test for token limit issue with channel queries
+ *
+ * Reproduces the bug where context_get with limit: 50 still exceeds token limits
+ * when querying a channel with large items.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const database_js_1 = require("../../utils/database.js");
+const RepositoryManager_js_1 = require("../../repositories/RepositoryManager.js");
+const token_limits_js_1 = require("../../utils/token-limits.js");
+(0, globals_1.describe)('Token Limit with Channel Query Bug', () => {
+    let dbManager;
+    let repositories;
+    let sessionId;
+    (0, globals_1.beforeEach)(() => {
+        dbManager = new database_js_1.DatabaseManager({ filename: ':memory:' });
+        repositories = new RepositoryManager_js_1.RepositoryManager(dbManager);
+        const session = repositories.sessions.create({
+            name: 'Test Session',
+            defaultChannel: 'test-channel',
+        });
+        sessionId = session.id;
+    });
+    (0, globals_1.afterEach)(() => {
+        dbManager.close();
+    });
+    (0, globals_1.it)('should enforce token limits even when limit parameter is provided', () => {
+        // Create 50 large context items (each ~1000 chars)
+        const largeValue = 'x'.repeat(1000);
+        for (let i = 0; i < 50; i++) {
+            repositories.contexts.save(sessionId, {
+                key: `large-item-${i}`,
+                value: largeValue,
+                channel: 'outbound-call-center',
+                priority: 'normal',
+            });
+        }
+        // Query with limit: 50
+        const result = repositories.contexts.queryEnhanced({
+            sessionId,
+            channel: 'outbound-call-center',
+            limit: 50,
+            sort: 'updated_desc',
+            includeMetadata: false,
+        });
+        (0, globals_1.expect)(result.items.length).toBe(50);
+        // Check if response would exceed token limit
+        const tokenConfig = (0, token_limits_js_1.getTokenConfig)();
+        const { exceedsLimit, safeItemCount } = (0, token_limits_js_1.checkTokenLimit)(result.items, false, tokenConfig);
+        // Build the actual response structure
+        const response = {
+            items: result.items,
+            pagination: {
+                total: result.totalCount,
+                returned: result.items.length,
+                offset: 0,
+                hasMore: false,
+                nextOffset: null,
+                truncated: false,
+                truncatedCount: 0,
+            },
+        };
+        const responseJson = JSON.stringify(response, null, 2);
+        const actualTokens = Math.ceil(responseJson.length / tokenConfig.charsPerToken);
+        // The bug: even with limit: 50, the response can exceed token limits
+        if (actualTokens > tokenConfig.mcpMaxTokens) {
+            // BUG REPRODUCED: The response exceeds token limits
+            // Verify that checkTokenLimit correctly detected the issue
+            (0, globals_1.expect)(exceedsLimit).toBe(true);
+            (0, globals_1.expect)(safeItemCount).toBeLessThan(50);
+            (0, globals_1.expect)(actualTokens).toBeGreaterThan(tokenConfig.mcpMaxTokens);
+        }
+    });
+    (0, globals_1.it)('should respect token limits over user-provided limit parameter', () => {
+        // Create 100 large context items (each ~800 chars)
+        const largeValue = 'y'.repeat(800);
+        for (let i = 0; i < 100; i++) {
+            repositories.contexts.save(sessionId, {
+                key: `item-${i}`,
+                value: largeValue,
+                channel: 'test-channel',
+                priority: 'normal',
+            });
+        }
+        // Query with limit: 50 (user expectation)
+        const result = repositories.contexts.queryEnhanced({
+            sessionId,
+            channel: 'test-channel',
+            limit: 50,
+            sort: 'created_desc',
+            includeMetadata: false,
+        });
+        // Simulate the context_get handler logic
+        const tokenConfig = (0, token_limits_js_1.getTokenConfig)();
+        const { exceedsLimit, safeItemCount } = (0, token_limits_js_1.checkTokenLimit)(result.items, false, tokenConfig);
+        let actualItems = result.items;
+        let wasTruncated = false;
+        if (exceedsLimit && safeItemCount < result.items.length) {
+            actualItems = result.items.slice(0, safeItemCount);
+            wasTruncated = true;
+        }
+        // Build response
+        const response = {
+            items: actualItems,
+            pagination: {
+                total: result.totalCount,
+                returned: actualItems.length,
+                offset: 0,
+                hasMore: wasTruncated || actualItems.length < result.totalCount,
+                nextOffset: wasTruncated ? actualItems.length : null,
+                truncated: wasTruncated,
+                truncatedCount: wasTruncated ? result.items.length - actualItems.length : 0,
+            },
+        };
+        const responseJson = JSON.stringify(response, null, 2);
+        const actualTokens = Math.ceil(responseJson.length / tokenConfig.charsPerToken);
+        // Verify token limit is not exceeded
+        (0, globals_1.expect)(actualTokens).toBeLessThanOrEqual(tokenConfig.mcpMaxTokens);
+        // Verify truncation occurred if needed
+        if (exceedsLimit) {
+            (0, globals_1.expect)(wasTruncated).toBe(true);
+            (0, globals_1.expect)(actualItems.length).toBeLessThan(50);
+            (0, globals_1.expect)(actualItems.length).toBe(safeItemCount);
+        }
+    });
+});

package/dist/__tests__/integration/project-directory.test.js

@@ -55,6 +55,9 @@ describe('Project Directory Feature Tests', () => {
         await git.init();
         await git.addConfig('user.name', 'Test User');
         await git.addConfig('user.email', 'test@example.com');
+        // Use repo-local hooks directory to prevent global hooks from interfering
+        const localHooksDir = path.join(tempProjectPath, '.git', 'hooks');
+        await git.addConfig('core.hooksPath', localHooksDir);
         // Create initial commit
         fs.writeFileSync(path.join(tempProjectPath, 'README.md'), '# Test Project');
         await git.add('.');
@@ -242,6 +245,9 @@ describe('Project Directory Feature Tests', () => {
             // Configure git for this test to avoid CI failures
             await git.addConfig('user.name', 'Test User');
             await git.addConfig('user.email', 'test@example.com');
+            // Use repo-local hooks directory to prevent global hooks from interfering
+            const localHooksDir = path.join(pathWithSpaces, '.git', 'hooks');
+            await git.addConfig('core.hooksPath', localHooksDir);
             try {
                 fs.writeFileSync(path.join(pathWithSpaces, 'test.txt'), 'content');
                 await git.add('.');

package/dist/__tests__/integration/tool-profiles-integration.test.js

@@ -0,0 +1,150 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const tool_profiles_1 = require("../../utils/tool-profiles");
+/**
+ * Drift-detection: extract tool names from the ListToolsRequestSchema handler
+ * in src/index.ts to verify ALL_TOOL_NAMES stays in sync with actual tool definitions.
+ */
+function extractToolNamesFromIndexTs() {
+    const indexPath = path.join(__dirname, '..', '..', 'index.ts');
+    const src = fs.readFileSync(indexPath, 'utf-8');
+    // Find the allTools array: starts after "const allTools" and ends at the matching "];"
+    // We look for tool name strings inside the ListToolsRequestSchema handler
+    const toolNameRegex = /^\s+name:\s+'(context_[a-z_]+)'/gm;
+    const names = [];
+    let match;
+    // Only capture tool names outside of block comments (skip commented-out tools)
+    // Split by block comment boundaries and only scan non-comment sections
+    const sections = src.split(/\/\*[\s\S]*?\*\//);
+    for (const section of sections) {
+        toolNameRegex.lastIndex = 0;
+        while ((match = toolNameRegex.exec(section)) !== null) {
+            names.push(match[1]);
+        }
+    }
+    return names;
+}
+(0, globals_1.describe)('Tool Profile Integration Tests', () => {
+    const originalEnv = process.env.TOOL_PROFILE;
+    afterEach(() => {
+        if (originalEnv !== undefined) {
+            process.env.TOOL_PROFILE = originalEnv;
+        }
+        else {
+            delete process.env.TOOL_PROFILE;
+        }
+    });
+    (0, globals_1.describe)('Drift detection: ALL_TOOL_NAMES vs index.ts', () => {
+        (0, globals_1.it)('ALL_TOOL_NAMES should match active tools defined in index.ts', () => {
+            const indexToolNames = extractToolNamesFromIndexTs();
+            const allToolNamesArray = [...tool_profiles_1.ALL_TOOL_NAMES];
+            // Same count
+            (0, globals_1.expect)(allToolNamesArray.length).toBe(indexToolNames.length);
+            // Same set of names
+            (0, globals_1.expect)(new Set(allToolNamesArray)).toEqual(new Set(indexToolNames));
+        });
+        (0, globals_1.it)('should not include commented-out tools', () => {
+            // context_share and context_get_shared are commented out in index.ts
+            (0, globals_1.expect)(tool_profiles_1.ALL_TOOL_NAMES_SET.has('context_share')).toBe(false);
+            (0, globals_1.expect)(tool_profiles_1.ALL_TOOL_NAMES_SET.has('context_get_shared')).toBe(false);
+        });
+    });
+    (0, globals_1.describe)('Profile filtering behavior', () => {
+        (0, globals_1.it)('minimal profile should include core tools and exclude advanced tools', () => {
+            process.env.TOOL_PROFILE = 'minimal';
+            const profile = (0, tool_profiles_1.resolveActiveProfile)('/nonexistent/config.json');
+            // Core tools present
+            (0, globals_1.expect)(profile.tools.has('context_save')).toBe(true);
+            (0, globals_1.expect)(profile.tools.has('context_get')).toBe(true);
+            (0, globals_1.expect)(profile.tools.has('context_search')).toBe(true);
+            (0, globals_1.expect)(profile.tools.has('context_checkpoint')).toBe(true);
+            // Advanced tools absent
+            (0, globals_1.expect)(profile.tools.has('context_analyze')).toBe(false);
+            (0, globals_1.expect)(profile.tools.has('context_visualize')).toBe(false);
+            (0, globals_1.expect)(profile.tools.has('context_delegate')).toBe(false);
+            (0, globals_1.expect)(profile.tools.has('context_semantic_search')).toBe(false);
+        });
+        (0, globals_1.it)('default (no env var) should expose all tools with backwards-compatible behavior', () => {
+            delete process.env.TOOL_PROFILE;
+            const profile = (0, tool_profiles_1.resolveActiveProfile)('/nonexistent/config.json');
+            (0, globals_1.expect)(profile.tools.size).toBe(tool_profiles_1.ALL_TOOL_NAMES.length);
+            (0, globals_1.expect)(profile.profileName).toBe('full');
+            (0, globals_1.expect)(profile.source).toBe('default');
+            (0, globals_1.expect)(profile.warnings).toHaveLength(0);
+        });
+    });
+    (0, globals_1.describe)('CallTool guard behavior', () => {
+        (0, globals_1.it)('disabled tool should be in ALL_TOOL_NAMES_SET but not in profile tools', () => {
+            process.env.TOOL_PROFILE = 'minimal';
+            const profile = (0, tool_profiles_1.resolveActiveProfile)('/nonexistent/config.json');
+            const disabledTool = 'context_analyze';
+            // The guard logic: known tool that is not enabled
+            const isKnown = tool_profiles_1.ALL_TOOL_NAMES_SET.has(disabledTool);
+            const isEnabled = profile.tools.has(disabledTool);
+            (0, globals_1.expect)(isKnown).toBe(true);
+            (0, globals_1.expect)(isEnabled).toBe(false);
+            // In index.ts: isKnown && !isEnabled → return isError: true
+        });
+        (0, globals_1.it)('unknown tool should not be in ALL_TOOL_NAMES_SET (falls through to default switch)', () => {
+            const unknownTool = 'non_existent_tool';
+            (0, globals_1.expect)(tool_profiles_1.ALL_TOOL_NAMES_SET.has(unknownTool)).toBe(false);
+            // In index.ts: !isKnown → falls through to default: throw new Error()
+        });
+        (0, globals_1.it)('enabled tool should pass both checks', () => {
+            process.env.TOOL_PROFILE = 'minimal';
+            const profile = (0, tool_profiles_1.resolveActiveProfile)('/nonexistent/config.json');
+            const enabledTool = 'context_save';
+            const isKnown = tool_profiles_1.ALL_TOOL_NAMES_SET.has(enabledTool);
+            const isEnabled = profile.tools.has(enabledTool);
+            (0, globals_1.expect)(isKnown).toBe(true);
+            (0, globals_1.expect)(isEnabled).toBe(true);
+            // In index.ts: isKnown && isEnabled → guard does not fire, proceeds to switch
+        });
+    });
+    (0, globals_1.describe)('TOOL_PROFILE_CONFIG support', () => {
+        (0, globals_1.it)('resolveActiveProfile accepts custom config path (used by TOOL_PROFILE_CONFIG)', () => {
+            // This tests the mechanism that index.ts uses:
+            // resolveActiveProfile(process.env.TOOL_PROFILE_CONFIG)
+            const result = (0, tool_profiles_1.resolveActiveProfile)('/nonexistent/custom/path/config.json');
+            // Missing file → no config → falls back to built-in 'full'
+            (0, globals_1.expect)(result.profileName).toBe('full');
+            (0, globals_1.expect)(result.tools.size).toBe(38);
+        });
+    });
+});

package/dist/__tests__/utils/project-directory-messages.test.js

@@ -123,6 +123,9 @@ Tip: Initialize git with 'git init' to enable git tracking features.`;
             await git.init();
             await git.addConfig('user.name', 'Test User');
             await git.addConfig('user.email', 'test@example.com');
+            // Use repo-local hooks directory to prevent global hooks from interfering
+            const localHooksDir = path.join(tempRepoPath, '.git', 'hooks');
+            await git.addConfig('core.hooksPath', localHooksDir);
         });
         afterEach(() => {
             fs.rmSync(tempRepoPath, { recursive: true, force: true });