memory-journal-mcp 6.1.2 → 6.2.1

package/test-server/tool-reference.md

@@ -1,231 +0,0 @@
-# Tool Reference
-
-Complete reference of all **61 tools** organized by 10 tool groups + codemode. Each group automatically includes Code Mode (`mj_execute_code`) for token-efficient operations.
-
-> **3 tool shortcuts** (`starter`, `essential`, `readonly`) provide curated subsets for common use cases.
->
-> Use [Tool Filtering](#️-tool-filtering) to select the groups you need. See [Code Mode](#-recommended-code-mode-maximum-token-savings) for the `mj.*` API that exposes every tool below through sandboxed JavaScript.
-
----
-
-## codemode (1 tool)
-
-Sandboxed JavaScript execution that exposes all 10 tool groups through the `mj.*` API.
-
-| Tool              | Description                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mj_execute_code` | Execute JavaScript in a sandboxed environment with access to all journal tools via the `mj.*` API. Enables multi-step workflows in a single call, reducing token usage by 70-90%. API groups: `mj.core.*`, `mj.search.*`, `mj.analytics.*`, `mj.relationships.*`, `mj.export.*`, `mj.admin.*`, `mj.github.*`, `mj.backup.*`, `mj.team.*`. Use `mj.help()` for method listing. Returns the last expression value. |
-
----
-
-## core (6 tools + Code Mode)
-
-Entry lifecycle — create, retrieve, tags, and test.
-
-| Tool                   | Description                                                                        |
-| ---------------------- | ---------------------------------------------------------------------------------- |
-| `create_entry`         | Create a new journal entry with context and tags (v2.1.0: GitHub Actions support). |
-| `get_entry_by_id`      | Get a specific journal entry by ID with full details.                              |
-| `get_recent_entries`   | Get recent journal entries.                                                        |
-| `create_entry_minimal` | Minimal entry creation without context or tags.                                    |
-| `test_simple`          | Simple test tool that just returns a message.                                      |
-| `list_tags`            | List all available tags.                                                           |
-
----
-
-## search (4 tools + Code Mode)
-
-Full-text, date-range, and semantic/vector search.
-
-| Tool                     | Description                                                                                                                                                                                                    |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `search_entries`         | Full-text search journal entries using FTS5 (supports phrases `"exact match"`, prefix `auth*`, boolean `NOT`/`OR`/`AND`, ranked by relevance). Optional filters for GitHub Projects, Issues, PRs, and Actions. |
-| `search_by_date_range`   | Search journal entries within a date range with optional filters.                                                                                                                                              |
-| `semantic_search`        | Perform semantic/vector search on journal entries using AI embeddings.                                                                                                                                         |
-| `get_vector_index_stats` | Get statistics about the semantic search vector index.                                                                                                                                                         |
-
----
-
-## analytics (2 tools + Code Mode)
-
-Statistics, cross-project insights, and analytics.
-
-| Tool                         | Description                                                                 |
-| ---------------------------- | --------------------------------------------------------------------------- |
-| `get_statistics`             | Get journal statistics and analytics (Phase 2: includes project breakdown). |
-| `get_cross_project_insights` | Analyze patterns across all GitHub Projects tracked in journal entries.     |
-
----
-
-## relationships (2 tools + Code Mode)
-
-Link entries and visualize knowledge graphs.
-
-| Tool                      | Description                                                      |
-| ------------------------- | ---------------------------------------------------------------- |
-| `link_entries`            | Create a relationship between two journal entries.               |
-| `visualize_relationships` | Generate a Mermaid diagram visualization of entry relationships. |
-
----
-
-## export (1 tool + Code Mode)
-
-Export journal data in multiple formats.
-
-| Tool             | Description                                        |
-| ---------------- | -------------------------------------------------- |
-| `export_entries` | Export journal entries to JSON or Markdown format. |
-
----
-
-## admin (5 tools + Code Mode)
-
-Entry mutations, vector index management, and tag maintenance.
-
-| Tool                   | Description                                                                                                                          |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `update_entry`         | Update an existing journal entry.                                                                                                    |
-| `delete_entry`         | Delete a journal entry (soft delete with timestamp).                                                                                 |
-| `merge_tags`           | Merge one tag into another to consolidate similar tags (e.g., merge "phase-2" into "phase2"). The source tag is deleted after merge. |
-| `rebuild_vector_index` | Rebuild the semantic search vector index from all existing entries.                                                                  |
-| `add_to_vector_index`  | Add a specific entry to the semantic search vector index.                                                                            |
-
----
-
-## github (16 tools + Code Mode)
-
-GitHub integration — Issues, PRs, context, Kanban boards, Milestones, Insights, issue lifecycle, and Copilot Reviews.
-
-| Tool                             | Description                                                                                                                               |
-| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `get_github_issues`              | List issues from a GitHub repository. Leave `owner`/`repo` empty to auto-detect from the current git repository.                          |
-| `get_github_prs`                 | List pull requests from a GitHub repository. Leave `owner`/`repo` empty to auto-detect from the current git repository.                   |
-| `get_github_issue`               | Get detailed information about a specific GitHub issue. Leave `owner`/`repo` empty to auto-detect from the current git repository.        |
-| `get_github_pr`                  | Get detailed information about a specific GitHub pull request. Leave `owner`/`repo` empty to auto-detect from the current git repository. |
-| `get_github_context`             | Get current repository context including branch, open issues, and open PRs. Only counts OPEN items (closed items excluded).               |
-| `get_kanban_board`               | View a GitHub Project v2 as a Kanban board with items grouped by Status column. Returns all columns with their items.                     |
-| `move_kanban_item`               | Move a Kanban item to a different status column. Requires the project board to have a Status field.                                       |
-| `create_github_issue_with_entry` | Create a GitHub issue AND automatically create a linked journal entry documenting the issue creation.                                     |
-| `close_github_issue_with_entry`  | Close a GitHub issue AND create a journal entry documenting the resolution.                                                               |
-| `get_github_milestones`          | List GitHub milestones for the repository with completion percentages and due dates.                                                      |
-| `get_github_milestone`           | Get detailed information about a specific GitHub milestone including progress and linked issue counts.                                    |
-| `create_github_milestone`        | Create a new GitHub milestone for tracking progress toward a project goal.                                                                |
-| `update_github_milestone`        | Update a GitHub milestone (title, description, due date, or state). Use state "closed" to close a completed milestone.                    |
-| `delete_github_milestone`        | Permanently delete a GitHub milestone. Issues assigned to the milestone will be un-assigned but not deleted.                              |
-| `get_repo_insights`              | Get repository insights: stars, forks, traffic (clones/views), referrers, and popular paths. Use "sections" to control token usage.       |
-| `get_copilot_reviews`            | Get Copilot's code review findings for a pull request. Returns review state and file-level comments with paths and line numbers.          |
-
----
-
-## backup (4 tools + Code Mode)
-
-Database backup, restore, and retention management.
-
-| Tool              | Description                                                                                                                              |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `backup_journal`  | Create a timestamped backup of the journal database. Backups are stored in the `backups/` directory.                                     |
-| `list_backups`    | List all available backup files with their sizes and creation dates.                                                                     |
-| `restore_backup`  | Restore the journal database from a backup file. WARNING: This replaces all current data. An automatic backup is created before restore. |
-| `cleanup_backups` | Delete old backup files, keeping only the most recent N backups. Use `list_backups` to preview before cleanup.                           |
-
----
-
-## team (20 tools + Code Mode)
-
-Team collaboration with a separate shared database. Requires `TEAM_DB_PATH`.
-
-### Core
-
-| Tool                   | Description                                                                                     |
-| ---------------------- | ----------------------------------------------------------------------------------------------- |
-| `team_create_entry`    | Create an entry in the team database for sharing with collaborators.                            |
-| `team_get_entry_by_id` | Get a specific team entry by ID with full details including relationships and importance score. |
-| `team_get_recent`      | Get recent entries from the team database.                                                      |
-| `team_list_tags`       | List all tags used in the team database with usage counts.                                      |
-
-### Search
-
-| Tool                        | Description                                                                            |
-| --------------------------- | -------------------------------------------------------------------------------------- |
-| `team_search`               | Search entries in the team database by text and/or tags.                               |
-| `team_search_by_date_range` | Search team entries within a date range with optional filters for entry type and tags. |
-
-### Admin
-
-| Tool                | Description                                                |
-| ------------------- | ---------------------------------------------------------- |
-| `team_update_entry` | Update a team entry (content, type, or tags).              |
-| `team_delete_entry` | Soft-delete a team entry (marks as deleted, preservable).  |
-| `team_merge_tags`   | Merge a source tag into a target tag in the team database. |
-
-### Analytics
-
-| Tool                              | Description                                                                                              |
-| --------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `team_get_statistics`             | Get statistics for the team database including entry counts, types, top tags, and contributor breakdown. |
-| `team_get_cross_project_insights` | Analyze patterns across all GitHub Projects tracked in team entries. Requires TEAM_DB_PATH.              |
-
-### Relationships
-
-| Tool                           | Description                                                            |
-| ------------------------------ | ---------------------------------------------------------------------- |
-| `team_link_entries`            | Create a relationship between two team entries.                        |
-| `team_visualize_relationships` | Generate a Mermaid diagram showing relationships between team entries. |
-
-### Export
-
-| Tool                  | Description                                                                                     |
-| --------------------- | ----------------------------------------------------------------------------------------------- |
-| `team_export_entries` | Export team entries in JSON or Markdown format with optional date range, type, and tag filters. |
-
-### Backup
-
-| Tool                | Description                                            |
-| ------------------- | ------------------------------------------------------ |
-| `team_backup`       | Create a timestamped backup of the team database.      |
-| `team_list_backups` | List all available backup files for the team database. |
-
-### Vector
-
-| Tool                          | Description                                                                                               |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `team_semantic_search`        | Perform semantic/vector search on team entries using AI embeddings. Requires TEAM_DB_PATH.                |
-| `team_get_vector_index_stats` | Get statistics about the team vector search index (item count, model, dimensions). Requires TEAM_DB_PATH. |
-| `team_rebuild_vector_index`   | Rebuild the team semantic search vector index from all existing team entries. Requires TEAM_DB_PATH.      |
-| `team_add_to_vector_index`    | Add a specific team entry to the semantic search vector index. Requires TEAM_DB_PATH.                     |
-
----
-
-## ⚙️ Tool Filtering
-
-Control which tools are exposed via `MEMORY_JOURNAL_MCP_TOOL_FILTER` (or CLI: `--tool-filter`):
-
-| Filter               | Tools | Use Case                 |
-| -------------------- | ----- | ------------------------ |
-| `full`               | 61    | All tools (default)      |
-| `starter`            | ~11   | Core + search + codemode |
-| `essential`          | ~7    | Minimal footprint        |
-| `readonly`           | ~15   | Disable all mutations    |
-| `-github`            | 45    | Exclude a group          |
-| `-github,-analytics` | 43    | Exclude multiple groups  |
-
-**Filter Syntax:** `shortcut` or `group` or `tool_name` (whitelist mode) · `-group` (disable group) · `-tool` (disable tool) · `+tool` (re-enable after group disable)
-
-**Custom Selection:** List individual tool names to create your own whitelist: `--tool-filter "create_entry,search_entries,semantic_search"`
-
-**Groups:** `core`, `search`, `analytics`, `relationships`, `export`, `admin`, `github`, `backup`, `team`, `codemode`
-
----
-
-## 🌟 Recommended: Code Mode (Maximum Token Savings)
-
-Code Mode (`mj_execute_code`) dramatically reduces token usage (70–90%) and is included by default in all presets.
-
-Code executes in a **sandboxed VM context** with:
-
-- **Static code validation** — blocked patterns include `require()`, `process`, `eval()`, and filesystem access
-- **Rate limiting** — 60 executions per minute per client
-- **Hard timeouts** — configurable execution limit (default 30s)
-- **Full API access** — all 10 tool groups available via `mj.*`
-
-**API Groups:** `mj.core.*`, `mj.search.*`, `mj.analytics.*`, `mj.relationships.*`, `mj.export.*`, `mj.admin.*`, `mj.github.*`, `mj.backup.*`, `mj.team.*`

package/tests/README.md

@@ -1,54 +0,0 @@
-# Memory Journal MCP - Vitest Suite (Unit/Integration)
-
-> **⚠️ AI AGENT INSTRUCTIONS:** Read these rules before creating, modifying, or running tests in this directory.
-
-## 📌 Framework & Purpose
-
-- **Framework:** Vitest (`vitest.config.ts`)
-- **Execution Environment:** Node.js
-- **Purpose:** Fast, isolated unit testing and database/handler integration testing.
-- **Not for:** Core HTTP transport/SSE protocol testing (see `tests/e2e/README.md`).
-
-## 🚨 AI Agent Testing Rules
-
-### 1. Meaningful Tests ONLY
-
-- **DO NOT** write tests just to boost coverage metrics.
-- Focus on testing logic boundaries, error handling, input validation, and expected success paths.
-- We require high-quality, meaningful assertions. Never use `expect(true).toBe(true)` or `continue-on-error` patterns.
-
-### 2. Execution Protocol
-
-- **Targeted Runs:** NEVER run the entire test suite when working on a specific file. Run targeted tests to save time and token context.
-  - ✅ `npx vitest run path/to/file.test.ts`
-  - ❌ `npx vitest` (Unless explicitly asked for a full suite run)
-- **Output Limits:** When running tests via standard terminal commands, use `OutputCharacterCount: ≥10000` to ensure you see the summary line.
-- **Assertion:** Never assume a test passed if the output is truncated. You MUST verify the final summary line (`✓ 1 passed`).
-
-### 3. File Naming & Structure
-
-- Test files must mirror the source directory structure.
-- Naming convention: `<source-filename>.test.ts` (e.g., `src/foo/bar.ts` → `tests/foo/bar.test.ts`).
-- **Never** use PascalCase or camelCase. Use `kebab-case`.
-
-### 4. Error Assertions (Structured Errors)
-
-- The Memory Journal MCP server uses a strict **Structured Error Pattern**. Tools NEVER throw raw exceptions to the client. They return:
-  `{ success: false, error: '...', code: '...', category: '...', suggestion: '...' }`.
-- When testing tool handlers, **assert the structured response**, do not expect the tool to `.toThrow()`.
-
-## 📂 Directory Structure Reference
-
-| Directory     | Tests What                                                      |
-| ------------- | --------------------------------------------------------------- |
-| `auth/`       | OAuth 2.1 middleware, token validation, scopes                  |
-| `codemode/`   | Sandbox security, API bridge, worker lifecycle                  |
-| `database/`   | SQLite adapter, entry CRUD, search, tags, backup                |
-| `handlers/`   | Tool handlers, resource handlers, prompt handlers (Integration) |
-| `security/`   | Input validation, SQL injection, path traversal                 |
-| `transports/` | HTTP transport, rate limiting, session behavior                 |
-| `vector/`     | Vector search manager, semantic embedding logic                 |
-
----
-
-_For a complete code map and directory breakdown, see `test-server/code-map.md`._

package/tests/auth/auth-context.test.ts

@@ -1,162 +0,0 @@
-/**
- * memory-journal-mcp — Auth Context Unit Tests
- *
- * Tests for AsyncLocalStorage-based per-request auth context.
- */
-
-import { describe, it, expect, vi, afterEach } from 'vitest'
-import {
-    getAuthContext,
-    setAuthContext,
-    withAuthContext,
-    isAuthenticated,
-    getAuthenticatedScopes,
-} from '../../src/auth/auth-context.js'
-
-describe('auth-context', () => {
-    afterEach(() => {
-        vi.restoreAllMocks()
-    })
-
-    describe('getAuthContext', () => {
-        it('should return undefined when no context is set', () => {
-            // Outside of any AsyncLocalStorage run, should be undefined
-            const ctx = getAuthContext()
-            expect(ctx).toBeUndefined()
-        })
-    })
-
-    describe('withAuthContext', () => {
-        it('should run callback with context', () => {
-            const context = {
-                authenticated: true as const,
-                claims: {
-                    sub: 'user-1',
-                    scopes: ['read', 'write'],
-                    exp: Math.floor(Date.now() / 1000) + 3600,
-                    iat: Math.floor(Date.now() / 1000),
-                },
-                token: 'test-token',
-            }
-
-            const result = withAuthContext(context, () => {
-                const ctx = getAuthContext()
-                return ctx?.claims?.sub
-            })
-
-            expect(result).toBe('user-1')
-        })
-
-        it('should isolate context between calls', () => {
-            const context1 = {
-                authenticated: true as const,
-                claims: {
-                    sub: 'user-1',
-                    scopes: ['read'],
-                    exp: 0,
-                    iat: 0,
-                },
-                token: 'token-1',
-            }
-
-            const context2 = {
-                authenticated: true as const,
-                claims: {
-                    sub: 'user-2',
-                    scopes: ['admin'],
-                    exp: 0,
-                    iat: 0,
-                },
-                token: 'token-2',
-            }
-
-            withAuthContext(context1, () => {
-                const ctx1 = getAuthContext()
-                expect(ctx1?.claims?.sub).toBe('user-1')
-
-                // Nested context should override
-                withAuthContext(context2, () => {
-                    const ctx2 = getAuthContext()
-                    expect(ctx2?.claims?.sub).toBe('user-2')
-                })
-
-                // Back to original context
-                const ctxAfter = getAuthContext()
-                expect(ctxAfter?.claims?.sub).toBe('user-1')
-            })
-        })
-    })
-
-    describe('setAuthContext', () => {
-        it('should set and return context', () => {
-            const context = {
-                authenticated: true as const,
-                claims: {
-                    sub: 'user-1',
-                    scopes: ['read'],
-                    exp: 0,
-                    iat: 0,
-                },
-                token: 'test-token',
-            }
-
-            // setAuthContext sets the context for checking later
-            // This function uses enterWith which replaces the current store
-            setAuthContext(context)
-
-            const ctx = getAuthContext()
-            expect(ctx?.authenticated).toBe(true)
-            expect(ctx?.claims?.sub).toBe('user-1')
-        })
-    })
-
-    describe('isAuthenticated', () => {
-        it('should return false when no context', () => {
-            expect(isAuthenticated()).toBe(false)
-        })
-
-        it('should return true when authenticated context is set', () => {
-            const context = {
-                authenticated: true as const,
-                claims: {
-                    sub: 'user-1',
-                    scopes: ['read'],
-                    exp: 0,
-                    iat: 0,
-                },
-                token: 'test-token',
-            }
-
-            const result = withAuthContext(context, () => {
-                return isAuthenticated()
-            })
-
-            expect(result).toBe(true)
-        })
-    })
-
-    describe('getAuthenticatedScopes', () => {
-        it('should return empty array when no context', () => {
-            expect(getAuthenticatedScopes()).toEqual([])
-        })
-
-        it('should return scopes from authenticated context', () => {
-            const context = {
-                authenticated: true as const,
-                claims: {
-                    sub: 'user-1',
-                    scopes: ['read', 'write'],
-                    exp: 0,
-                    iat: 0,
-                },
-                token: 'test-token',
-            }
-
-            const result = withAuthContext(context, () => {
-                return getAuthenticatedScopes()
-            })
-
-            expect(result).toEqual(['read', 'write'])
-        })
-    })
-})