@prmichaelsen/remember-mcp 3.19.3 → 4.0.0

package/src/tools/admin-inspect-memory.ts

@@ -0,0 +1,86 @@
+/**
+ * remember_admin_inspect_memory tool
+ * Fetches a raw memory object by UUID using the Firestore index for collection resolution.
+ */
+
+import { handleToolError } from '../utils/error-handler.js';
+import { createDebugLogger } from '../utils/debug.js';
+import type { AuthContext } from '../types/auth.js';
+import { isAdmin, adminPermissionError } from '../utils/admin.js';
+import { getWeaviateClient } from '../weaviate/client.js';
+import { MemoryIndexService, createLogger } from '@prmichaelsen/remember-core';
+
+const indexService = new MemoryIndexService(createLogger('info'));
+
+export const adminInspectMemoryTool = {
+  name: 'remember_admin_inspect_memory',
+  description: `[Admin] Fetch a raw memory object by UUID — all fields including internal metadata.
+
+  Uses the Firestore index to resolve which collection the memory lives in.
+  Optionally includes the vector embedding.
+  Requires admin access (ADMIN_USER_IDS).`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      memory_id: {
+        type: 'string',
+        description: 'Memory UUID',
+      },
+      include_vector: {
+        type: 'boolean',
+        description: 'Include the vector embedding in the response. Default: false',
+      },
+    },
+    required: ['memory_id'],
+  },
+};
+
+export interface AdminInspectMemoryArgs {
+  memory_id: string;
+  include_vector?: boolean;
+}
+
+export async function handleAdminInspectMemory(
+  args: AdminInspectMemoryArgs,
+  userId: string,
+  _authContext?: AuthContext
+): Promise<string> {
+  const debug = createDebugLogger({ tool: 'remember_admin_inspect_memory', userId, operation: 'inspect memory' });
+  try {
+    if (!isAdmin(userId)) {
+      return JSON.stringify(adminPermissionError());
+    }
+
+    debug.info('Tool invoked', { memory_id: args.memory_id, include_vector: args.include_vector });
+
+    // Resolve collection from index
+    const collectionName = await indexService.lookup(args.memory_id);
+    if (!collectionName) {
+      return JSON.stringify({ error: `Memory not found in index: ${args.memory_id}` });
+    }
+
+    // Fetch raw object from Weaviate
+    const client = getWeaviateClient();
+    const collection = client.collections.get(collectionName);
+    const result = await collection.query.fetchObjectById(args.memory_id, {
+      includeVector: args.include_vector ?? false,
+    });
+
+    if (!result) {
+      return JSON.stringify({
+        error: `Memory indexed in ${collectionName} but not found in Weaviate: ${args.memory_id}`,
+        collection_name: collectionName,
+      });
+    }
+
+    return JSON.stringify({
+      id: result.uuid,
+      collection_name: collectionName,
+      properties: result.properties,
+      vectors: args.include_vector ? result.vectors : undefined,
+      metadata: result.metadata,
+    }, null, 2);
+  } catch (error) {
+    return handleToolError(error, { toolName: 'remember_admin_inspect_memory', userId, operation: 'inspect memory' });
+  }
+}

package/src/tools/admin-inspect-user.spec.ts

@@ -0,0 +1,130 @@
+/**
+ * Tests for admin user inspection tools.
+ */
+
+const mockPreferencesGet = jest.fn();
+const mockGetGhostConfig = jest.fn();
+const mockQueryDocuments = jest.fn();
+
+jest.mock('../core-services.js', () => ({
+  createCoreServices: () => ({
+    preferences: { getPreferences: mockPreferencesGet },
+  }),
+}));
+
+jest.mock('../services/ghost-config.service.js', () => ({
+  getGhostConfig: mockGetGhostConfig,
+}));
+
+jest.mock('../firestore/init.js', () => ({
+  queryDocuments: mockQueryDocuments,
+}));
+
+import {
+  handleAdminInspectUserPreferences,
+  handleAdminInspectUserGhostConfigs,
+  handleAdminInspectUserEscalationRecords,
+  handleAdminInspectUserApiTokens,
+} from './admin-inspect-user.js';
+
+describe('admin user inspection tools', () => {
+  const originalEnv = process.env.ADMIN_USER_IDS;
+
+  beforeEach(() => {
+    process.env.ADMIN_USER_IDS = 'admin_user';
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.ADMIN_USER_IDS = originalEnv;
+    } else {
+      delete process.env.ADMIN_USER_IDS;
+    }
+  });
+
+  describe('remember_admin_inspect_user_preferences', () => {
+    it('returns preferences for admin user', async () => {
+      mockPreferencesGet.mockResolvedValue({ templates: { auto_suggest: true } });
+      const result = await handleAdminInspectUserPreferences({ user_id: 'target' }, 'admin_user');
+      const parsed = JSON.parse(result);
+      expect(parsed.user_id).toBe('target');
+      expect(parsed.preferences.templates.auto_suggest).toBe(true);
+    });
+
+    it('returns permission error for non-admin', async () => {
+      const result = await handleAdminInspectUserPreferences({ user_id: 'target' }, 'regular_user');
+      const parsed = JSON.parse(result);
+      expect(parsed.isError).toBe(true);
+    });
+  });
+
+  describe('remember_admin_inspect_user_ghost_configs', () => {
+    it('returns ghost config for admin user', async () => {
+      mockGetGhostConfig.mockResolvedValue({ enabled: true, trust_mode: 'query' });
+      const result = await handleAdminInspectUserGhostConfigs({ user_id: 'target' }, 'admin_user');
+      const parsed = JSON.parse(result);
+      expect(parsed.user_id).toBe('target');
+      expect(parsed.ghost_config.enabled).toBe(true);
+    });
+
+    it('returns permission error for non-admin', async () => {
+      const result = await handleAdminInspectUserGhostConfigs({ user_id: 'target' }, 'regular_user');
+      const parsed = JSON.parse(result);
+      expect(parsed.isError).toBe(true);
+    });
+  });
+
+  describe('remember_admin_inspect_user_escalation_records', () => {
+    it('returns escalation records for admin user', async () => {
+      mockQueryDocuments.mockResolvedValue([
+        { id: 'esc-1', data: { accessor_id: 'user2', attempts: 3 } },
+      ]);
+      const result = await handleAdminInspectUserEscalationRecords({ user_id: 'target' }, 'admin_user');
+      const parsed = JSON.parse(result);
+      expect(parsed.user_id).toBe('target');
+      expect(parsed.escalation_records).toHaveLength(1);
+      expect(parsed.escalation_records[0].accessor_id).toBe('user2');
+    });
+
+    it('returns empty array for user with no records', async () => {
+      mockQueryDocuments.mockResolvedValue([]);
+      const result = await handleAdminInspectUserEscalationRecords({ user_id: 'target' }, 'admin_user');
+      const parsed = JSON.parse(result);
+      expect(parsed.escalation_records).toEqual([]);
+    });
+
+    it('returns permission error for non-admin', async () => {
+      const result = await handleAdminInspectUserEscalationRecords({ user_id: 'target' }, 'regular_user');
+      const parsed = JSON.parse(result);
+      expect(parsed.isError).toBe(true);
+    });
+  });
+
+  describe('remember_admin_inspect_user_api_tokens', () => {
+    it('returns token metadata without hashes', async () => {
+      mockQueryDocuments.mockResolvedValue([
+        { id: 'tok-1', data: { name: 'MacBook', token_hash: 'secret_hash', created_at: '2026-01-01' } },
+      ]);
+      const result = await handleAdminInspectUserApiTokens({ user_id: 'target' }, 'admin_user');
+      const parsed = JSON.parse(result);
+      expect(parsed.user_id).toBe('target');
+      expect(parsed.api_tokens).toHaveLength(1);
+      expect(parsed.api_tokens[0].name).toBe('MacBook');
+      expect(parsed.api_tokens[0].token_hash).toBeUndefined();
+    });
+
+    it('returns empty array for user with no tokens', async () => {
+      mockQueryDocuments.mockResolvedValue([]);
+      const result = await handleAdminInspectUserApiTokens({ user_id: 'target' }, 'admin_user');
+      const parsed = JSON.parse(result);
+      expect(parsed.api_tokens).toEqual([]);
+    });
+
+    it('returns permission error for non-admin', async () => {
+      const result = await handleAdminInspectUserApiTokens({ user_id: 'target' }, 'regular_user');
+      const parsed = JSON.parse(result);
+      expect(parsed.isError).toBe(true);
+    });
+  });
+});

package/src/tools/admin-inspect-user.ts

@@ -0,0 +1,148 @@
+/**
+ * Admin user inspection tools — granular Firestore data access per data type.
+ *
+ * - remember_admin_inspect_user_preferences
+ * - remember_admin_inspect_user_ghost_configs
+ * - remember_admin_inspect_user_escalation_records
+ * - remember_admin_inspect_user_api_tokens
+ */
+
+import { handleToolError } from '../utils/error-handler.js';
+import { createDebugLogger } from '../utils/debug.js';
+import type { AuthContext } from '../types/auth.js';
+import { isAdmin, adminPermissionError } from '../utils/admin.js';
+import { createCoreServices } from '../core-services.js';
+import { getGhostConfig } from '../services/ghost-config.service.js';
+import { queryDocuments } from '../firestore/init.js';
+import { BASE } from '../firestore/paths.js';
+
+// ── Tool Definitions ────────────────────────────────────────────────────
+
+const userIdSchema = {
+  type: 'object' as const,
+  properties: {
+    user_id: { type: 'string' as const, description: 'User ID to inspect' },
+  },
+  required: ['user_id'] as const,
+};
+
+export const adminInspectUserPreferencesTool = {
+  name: 'remember_admin_inspect_user_preferences',
+  description: `[Admin] Inspect a user's preferences from Firestore. Requires admin access.`,
+  inputSchema: userIdSchema,
+};
+
+export const adminInspectUserGhostConfigsTool = {
+  name: 'remember_admin_inspect_user_ghost_configs',
+  description: `[Admin] Inspect a user's ghost configurations from Firestore. Requires admin access.`,
+  inputSchema: userIdSchema,
+};
+
+export const adminInspectUserEscalationRecordsTool = {
+  name: 'remember_admin_inspect_user_escalation_records',
+  description: `[Admin] Inspect a user's trust escalation records from Firestore. Requires admin access.`,
+  inputSchema: userIdSchema,
+};
+
+export const adminInspectUserApiTokensTool = {
+  name: 'remember_admin_inspect_user_api_tokens',
+  description: `[Admin] Inspect a user's API token metadata from Firestore (no hashes). Requires admin access.`,
+  inputSchema: userIdSchema,
+};
+
+// ── Shared Types ────────────────────────────────────────────────────────
+
+export interface AdminInspectUserArgs {
+  user_id: string;
+}
+
+// ── Handlers ────────────────────────────────────────────────────────────
+
+export async function handleAdminInspectUserPreferences(
+  args: AdminInspectUserArgs,
+  userId: string,
+  _authContext?: AuthContext
+): Promise<string> {
+  const debug = createDebugLogger({ tool: 'remember_admin_inspect_user_preferences', userId, operation: 'inspect preferences' });
+  try {
+    if (!isAdmin(userId)) return JSON.stringify(adminPermissionError());
+    debug.info('Tool invoked', { target_user_id: args.user_id });
+
+    const services = createCoreServices(args.user_id);
+    const prefs = await services.preferences.getPreferences(args.user_id);
+
+    return JSON.stringify({ user_id: args.user_id, preferences: prefs }, null, 2);
+  } catch (error) {
+    return handleToolError(error, { toolName: 'remember_admin_inspect_user_preferences', userId });
+  }
+}
+
+export async function handleAdminInspectUserGhostConfigs(
+  args: AdminInspectUserArgs,
+  userId: string,
+  _authContext?: AuthContext
+): Promise<string> {
+  const debug = createDebugLogger({ tool: 'remember_admin_inspect_user_ghost_configs', userId, operation: 'inspect ghost configs' });
+  try {
+    if (!isAdmin(userId)) return JSON.stringify(adminPermissionError());
+    debug.info('Tool invoked', { target_user_id: args.user_id });
+
+    const config = await getGhostConfig(args.user_id);
+
+    return JSON.stringify({ user_id: args.user_id, ghost_config: config }, null, 2);
+  } catch (error) {
+    return handleToolError(error, { toolName: 'remember_admin_inspect_user_ghost_configs', userId });
+  }
+}
+
+export async function handleAdminInspectUserEscalationRecords(
+  args: AdminInspectUserArgs,
+  userId: string,
+  _authContext?: AuthContext
+): Promise<string> {
+  const debug = createDebugLogger({ tool: 'remember_admin_inspect_user_escalation_records', userId, operation: 'inspect escalation records' });
+  try {
+    if (!isAdmin(userId)) return JSON.stringify(adminPermissionError());
+    debug.info('Tool invoked', { target_user_id: args.user_id });
+
+    // Escalation records stored at: {BASE}.users/{user_id}/escalations
+    const collectionPath = `${BASE}.users/${args.user_id}/escalations`;
+    const records = await queryDocuments(collectionPath);
+
+    return JSON.stringify({
+      user_id: args.user_id,
+      escalation_records: records.map(r => ({ id: r.id, ...r.data })),
+    }, null, 2);
+  } catch (error) {
+    return handleToolError(error, { toolName: 'remember_admin_inspect_user_escalation_records', userId });
+  }
+}
+
+export async function handleAdminInspectUserApiTokens(
+  args: AdminInspectUserArgs,
+  userId: string,
+  _authContext?: AuthContext
+): Promise<string> {
+  const debug = createDebugLogger({ tool: 'remember_admin_inspect_user_api_tokens', userId, operation: 'inspect api tokens' });
+  try {
+    if (!isAdmin(userId)) return JSON.stringify(adminPermissionError());
+    debug.info('Tool invoked', { target_user_id: args.user_id });
+
+    // API tokens stored at: {BASE}.users/{user_id}/api_tokens
+    const collectionPath = `${BASE}.users/${args.user_id}/api_tokens`;
+    const tokens = await queryDocuments(collectionPath);
+
+    // Strip token hashes — only return metadata
+    const sanitized = tokens.map((token: any) => {
+      const { token_hash, ...metadata } = token.data;
+      return { id: token.id, ...metadata };
+    });
+
+    return JSON.stringify({
+      user_id: args.user_id,
+      api_tokens: sanitized,
+    }, null, 2);
+  } catch (error) {
+    return handleToolError(error, { toolName: 'remember_admin_inspect_user_api_tokens', userId });
+  }
+}

package/src/tools/admin-list-collections.ts

@@ -0,0 +1,73 @@
+/**
+ * remember_admin_list_collections tool
+ * Lists all Weaviate collections with type categorization.
+ */
+
+import { handleToolError } from '../utils/error-handler.js';
+import { createDebugLogger } from '../utils/debug.js';
+import type { AuthContext } from '../types/auth.js';
+import { isAdmin, adminPermissionError } from '../utils/admin.js';
+import { getWeaviateClient } from '../weaviate/client.js';
+
+export const adminListCollectionsTool = {
+  name: 'remember_admin_list_collections',
+  description: `[Admin] List all Weaviate collections with type categorization (user, space, group).
+
+  Optionally filter by prefix (e.g. "Memory_users_", "Memory_spaces_").
+  Requires admin access (ADMIN_USER_IDS).`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      filter: {
+        type: 'string',
+        description: 'Optional prefix filter (e.g. "Memory_users_", "Memory_spaces_")',
+      },
+    },
+  },
+};
+
+export interface AdminListCollectionsArgs {
+  filter?: string;
+}
+
+function categorizeCollection(name: string): string {
+  if (name.startsWith('Memory_users_')) return 'user';
+  if (name.startsWith('Memory_spaces_')) return 'space';
+  if (name.startsWith('Memory_groups_')) return 'group';
+  if (name.startsWith('Memory_friends_')) return 'friends';
+  return 'other';
+}
+
+export async function handleAdminListCollections(
+  args: AdminListCollectionsArgs,
+  userId: string,
+  _authContext?: AuthContext
+): Promise<string> {
+  const debug = createDebugLogger({ tool: 'remember_admin_list_collections', userId, operation: 'list collections' });
+  try {
+    if (!isAdmin(userId)) {
+      return JSON.stringify(adminPermissionError());
+    }
+
+    debug.info('Tool invoked', { filter: args.filter });
+
+    const client = getWeaviateClient();
+    const allCollections = await client.collections.listAll();
+
+    let collections = allCollections.map((c: any) => ({
+      name: c.name,
+      type: categorizeCollection(c.name),
+    }));
+
+    if (args.filter) {
+      collections = collections.filter((c: any) => c.name.startsWith(args.filter!));
+    }
+
+    return JSON.stringify({
+      total: collections.length,
+      collections,
+    }, null, 2);
+  } catch (error) {
+    return handleToolError(error, { toolName: 'remember_admin_list_collections', userId, operation: 'list collections' });
+  }
+}

package/src/tools/admin-memory-inspection.spec.ts

@@ -0,0 +1,206 @@
+/**
+ * Tests for admin memory inspection tools:
+ * - remember_admin_inspect_memory
+ * - remember_admin_search_across_users
+ */
+
+// Must declare mocks before imports due to jest.mock hoisting
+const mockLookup = jest.fn();
+const mockFetchObjectById = jest.fn();
+const mockSearch = jest.fn();
+
+jest.mock('@prmichaelsen/remember-core', () => ({
+  MemoryIndexService: jest.fn().mockImplementation(() => ({
+    lookup: mockLookup,
+  })),
+  createLogger: () => ({ info: jest.fn(), debug: jest.fn(), warn: jest.fn(), error: jest.fn() }),
+}));
+
+jest.mock('../weaviate/client.js', () => ({
+  getWeaviateClient: () => ({
+    collections: {
+      get: () => ({
+        query: { fetchObjectById: mockFetchObjectById },
+      }),
+    },
+  }),
+}));
+
+jest.mock('../core-services.js', () => ({
+  createCoreServices: () => ({
+    memory: { search: mockSearch },
+  }),
+}));
+
+import { handleAdminInspectMemory } from './admin-inspect-memory.js';
+import { handleAdminSearchAcrossUsers } from './admin-search-across-users.js';
+
+describe('remember_admin_inspect_memory', () => {
+  const originalEnv = process.env.ADMIN_USER_IDS;
+
+  beforeEach(() => {
+    process.env.ADMIN_USER_IDS = 'admin_user';
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.ADMIN_USER_IDS = originalEnv;
+    } else {
+      delete process.env.ADMIN_USER_IDS;
+    }
+  });
+
+  it('returns raw memory object for admin user', async () => {
+    mockLookup.mockResolvedValue('Memory_users_abc123');
+    mockFetchObjectById.mockResolvedValue({
+      uuid: 'mem-uuid-1',
+      properties: { content: 'test memory', weight: 0.8 },
+      metadata: { creationTime: '2026-01-01' },
+    });
+
+    const result = await handleAdminInspectMemory(
+      { memory_id: 'mem-uuid-1' },
+      'admin_user'
+    );
+    const parsed = JSON.parse(result);
+    expect(parsed.id).toBe('mem-uuid-1');
+    expect(parsed.collection_name).toBe('Memory_users_abc123');
+    expect(parsed.properties.content).toBe('test memory');
+    expect(parsed.vectors).toBeUndefined();
+  });
+
+  it('includes vector when requested', async () => {
+    mockLookup.mockResolvedValue('Memory_users_abc123');
+    mockFetchObjectById.mockResolvedValue({
+      uuid: 'mem-uuid-1',
+      properties: { content: 'test' },
+      vectors: { default: [0.1, 0.2, 0.3] },
+      metadata: {},
+    });
+
+    const result = await handleAdminInspectMemory(
+      { memory_id: 'mem-uuid-1', include_vector: true },
+      'admin_user'
+    );
+    const parsed = JSON.parse(result);
+    expect(parsed.vectors).toEqual({ default: [0.1, 0.2, 0.3] });
+  });
+
+  it('returns error when memory not in index', async () => {
+    mockLookup.mockResolvedValue(null);
+
+    const result = await handleAdminInspectMemory(
+      { memory_id: 'nonexistent' },
+      'admin_user'
+    );
+    const parsed = JSON.parse(result);
+    expect(parsed.error).toContain('not found in index');
+  });
+
+  it('returns error when memory in index but not in Weaviate', async () => {
+    mockLookup.mockResolvedValue('Memory_users_abc123');
+    mockFetchObjectById.mockResolvedValue(null);
+
+    const result = await handleAdminInspectMemory(
+      { memory_id: 'orphaned-id' },
+      'admin_user'
+    );
+    const parsed = JSON.parse(result);
+    expect(parsed.error).toContain('not found in Weaviate');
+    expect(parsed.collection_name).toBe('Memory_users_abc123');
+  });
+
+  it('returns permission error for non-admin user', async () => {
+    const result = await handleAdminInspectMemory(
+      { memory_id: 'mem-uuid-1' },
+      'regular_user'
+    );
+    const parsed = JSON.parse(result);
+    expect(parsed.isError).toBe(true);
+    expect(parsed.content[0].text).toContain('Permission denied');
+  });
+});
+
+describe('remember_admin_search_across_users', () => {
+  const originalEnv = process.env.ADMIN_USER_IDS;
+
+  beforeEach(() => {
+    process.env.ADMIN_USER_IDS = 'admin_user';
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.ADMIN_USER_IDS = originalEnv;
+    } else {
+      delete process.env.ADMIN_USER_IDS;
+    }
+  });
+
+  it('searches across multiple users and includes user_id', async () => {
+    mockSearch.mockResolvedValue({
+      memories: [
+        { id: 'mem1', content: 'memory from user' },
+      ],
+    });
+
+    const result = await handleAdminSearchAcrossUsers(
+      { user_ids: ['user1', 'user2'], query: 'test' },
+      'admin_user'
+    );
+    const parsed = JSON.parse(result);
+    expect(parsed.total).toBe(2);
+    expect(parsed.results[0].user_id).toBe('user1');
+    expect(parsed.results[1].user_id).toBe('user2');
+  });
+
+  it('applies limit across merged results', async () => {
+    mockSearch.mockResolvedValue({
+      memories: [
+        { id: 'mem1', content: 'a' },
+        { id: 'mem2', content: 'b' },
+      ],
+    });
+
+    const result = await handleAdminSearchAcrossUsers(
+      { user_ids: ['user1', 'user2'], query: 'test', limit: 3 },
+      'admin_user'
+    );
+    const parsed = JSON.parse(result);
+    expect(parsed.total).toBe(3);
+  });
+
+  it('returns validation error for empty user_ids', async () => {
+    const result = await handleAdminSearchAcrossUsers(
+      { user_ids: [], query: 'test' },
+      'admin_user'
+    );
+    const parsed = JSON.parse(result);
+    expect(parsed.error).toContain('user_ids');
+  });
+
+  it('warns on failed user search', async () => {
+    mockSearch
+      .mockResolvedValueOnce({ memories: [{ id: 'mem1', content: 'ok' }] })
+      .mockRejectedValueOnce(new Error('Collection not found'));
+
+    const result = await handleAdminSearchAcrossUsers(
+      { user_ids: ['user1', 'bad_user'], query: 'test' },
+      'admin_user'
+    );
+    const parsed = JSON.parse(result);
+    expect(parsed.total).toBe(1);
+    expect(parsed.warnings).toHaveLength(1);
+    expect(parsed.warnings[0]).toContain('bad_user');
+  });
+
+  it('returns permission error for non-admin user', async () => {
+    const result = await handleAdminSearchAcrossUsers(
+      { user_ids: ['user1'], query: 'test' },
+      'regular_user'
+    );
+    const parsed = JSON.parse(result);
+    expect(parsed.isError).toBe(true);
+  });
+});