@gwdn/nexus-mcp 0.8.6 → 0.8.8

package/src/__tests__/server.test.ts

@@ -1,251 +0,0 @@
-/**
- * Tests for MCP server.ts integration:
- * - withIdentity wrapper
- * - Tool registration count (regression guard)
- * - Schema export verification
- */
-
-import { readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-
-// We test the withIdentity pattern and schema exports without
-// starting the full server (which needs stdio transport).
-
-describe('MCP Server: withIdentity wrapper', () => {
-  beforeEach(() => {
-    vi.resetModules()
-    vi.restoreAllMocks()
-  })
-
-  it('should inject user_id from identity into handler args', async () => {
-    // Recreate the withIdentity function inline (same logic as server.ts)
-    // with a simple mock identity
-    const mockIdentity = {
-      userId: 'injected-user-id',
-      email: 'test@example.com',
-      displayName: 'Test',
-      isPlatformAdmin: true,
-    }
-
-    function withIdentity(
-      handler: (args: Record<string, unknown>) => Promise<unknown>,
-    ) {
-      return async (args: Record<string, unknown>) => {
-        return handler({ ...args, user_id: mockIdentity.userId })
-      }
-    }
-
-    const mockHandler = vi.fn().mockResolvedValue({ content: [] })
-    const wrapped = withIdentity(mockHandler)
-
-    await wrapped({ project_id: 'test-project', title: 'Test' })
-
-    expect(mockHandler).toHaveBeenCalledWith({
-      project_id: 'test-project',
-      title: 'Test',
-      user_id: 'injected-user-id',
-    })
-  })
-
-  it('should override any user_id passed by the caller', async () => {
-    const mockIdentity = {
-      userId: 'real-user-id',
-      email: 'real@example.com',
-      displayName: 'Real User',
-      isPlatformAdmin: false,
-    }
-
-    function withIdentity(
-      handler: (args: Record<string, unknown>) => Promise<unknown>,
-    ) {
-      return async (args: Record<string, unknown>) => {
-        return handler({ ...args, user_id: mockIdentity.userId })
-      }
-    }
-
-    const mockHandler = vi.fn().mockResolvedValue({ content: [] })
-    const wrapped = withIdentity(mockHandler)
-
-    // Caller tries to inject a different user_id
-    await wrapped({ project_id: 'test', user_id: 'attacker-user-id' })
-
-    // The real identity should override the attacker's
-    expect(mockHandler).toHaveBeenCalledWith(
-      expect.objectContaining({ user_id: 'real-user-id' }),
-    )
-  })
-})
-
-describe('MCP Server: Schema exports', () => {
-  const EXPECTED_TOOL_COUNT = 48
-
-  it('should register exactly 48 tools in server.ts', () => {
-    // Static analysis: count server.tool( calls in server.ts as a regression guard.
-    // If you add or remove a tool, update EXPECTED_TOOL_COUNT above.
-    const serverSource = readFileSync(
-      resolve(__dirname, '../server.ts'),
-      'utf-8',
-    )
-    const matches = serverSource.match(/server\.tool\(/g) || []
-    expect(matches.length).toBe(EXPECTED_TOOL_COUNT)
-  })
-
-  it('should export valid schemas from all tool modules', async () => {
-    // Verify each tool module exports the expected schema + handler
-
-    const searchKnowledge = await import('../tools/search-knowledge.js')
-    expect(searchKnowledge.searchKnowledgeSchema).toBeDefined()
-    expect(searchKnowledge.searchKnowledgeSchema.query).toBeDefined()
-    expect(searchKnowledge.searchKnowledgeSchema.project_id).toBeDefined()
-    expect(typeof searchKnowledge.searchKnowledge).toBe('function')
-
-    const getProjectMemory = await import('../tools/get-project-memory.js')
-    expect(getProjectMemory.getProjectMemorySchema).toBeDefined()
-    expect(typeof getProjectMemory.getProjectMemory).toBe('function')
-
-    const getDocument = await import('../tools/get-document.js')
-    expect(getDocument.getDocumentSchema).toBeDefined()
-    expect(typeof getDocument.getDocument).toBe('function')
-
-    const getRelated = await import('../tools/get-related-entities.js')
-    expect(getRelated.getRelatedEntitiesSchema).toBeDefined()
-    expect(typeof getRelated.getRelatedEntities).toBe('function')
-
-    const createTask = await import('../tools/create-task.js')
-    expect(createTask.createTaskSchema).toBeDefined()
-    expect(createTask.createTaskSchema.project_id).toBeDefined()
-    expect(createTask.createTaskSchema.title).toBeDefined()
-    expect(typeof createTask.createTask).toBe('function')
-
-    const updateTaskStatus = await import('../tools/update-task-status.js')
-    expect(updateTaskStatus.updateTaskStatusSchema).toBeDefined()
-    expect(updateTaskStatus.updateTaskStatusSchema.task_id).toBeDefined()
-    expect(updateTaskStatus.updateTaskStatusSchema.status).toBeDefined()
-    expect(typeof updateTaskStatus.updateTaskStatus).toBe('function')
-
-    const addTaskNote = await import('../tools/add-task-note.js')
-    expect(addTaskNote.addTaskNoteSchema).toBeDefined()
-    expect(addTaskNote.addTaskNoteSchema.task_id).toBeDefined()
-    expect(addTaskNote.addTaskNoteSchema.note).toBeDefined()
-    expect(typeof addTaskNote.addTaskNote).toBe('function')
-
-    const ingestDoc = await import('../tools/ingest-document.js')
-    expect(ingestDoc.ingestDocumentSchema).toBeDefined()
-    expect(ingestDoc.ingestDocumentSchema.project_id).toBeDefined()
-    expect(ingestDoc.ingestDocumentSchema.body).toBeDefined()
-    expect(typeof ingestDoc.ingestDocument).toBe('function')
-
-    const sessions = await import('../tools/sessions.js')
-    expect(sessions.createSessionSchema).toBeDefined()
-    expect(sessions.closeSessionSchema).toBeDefined()
-    expect(sessions.listOpenSessionsSchema).toBeDefined()
-    expect(typeof sessions.createSession).toBe('function')
-    expect(typeof sessions.closeSession).toBe('function')
-    expect(typeof sessions.listOpenSessions).toBe('function')
-
-    const appendEntry = await import('../tools/append-session-entry.js')
-    expect(appendEntry.appendSessionEntrySchema).toBeDefined()
-    expect(appendEntry.appendSessionEntrySchema.metadata).toBeDefined()
-    expect(typeof appendEntry.appendSessionEntry).toBe('function')
-
-    const letters = await import('../tools/letters.js')
-    expect(letters.createLetterSchema).toBeDefined()
-    expect(letters.replyLetterSchema).toBeDefined()
-    expect(typeof letters.createLetter).toBe('function')
-    expect(typeof letters.replyLetter).toBe('function')
-
-    const letterInbox = await import('../tools/letter-inbox.js')
-    expect(letterInbox.listInboxSchema).toBeDefined()
-    expect(letterInbox.listInboxSchema.project_id).toBeDefined()
-    expect(letterInbox.listOutboxSchema).toBeDefined()
-    expect(letterInbox.listOutboxSchema.project_id).toBeDefined()
-    expect(letterInbox.acknowledgeLetterSchema).toBeDefined()
-    expect(letterInbox.acknowledgeLetterSchema.letter_id).toBeDefined()
-    expect(typeof letterInbox.listInbox).toBe('function')
-    expect(typeof letterInbox.listOutbox).toBe('function')
-    expect(typeof letterInbox.acknowledgeLetter).toBe('function')
-
-    const comments = await import('../tools/decision-comments.js')
-    expect(comments.addDecisionCommentSchema).toBeDefined()
-    expect(comments.listDecisionCommentsSchema).toBeDefined()
-    expect(typeof comments.addDecisionComment).toBe('function')
-    expect(typeof comments.listDecisionComments).toBe('function')
-
-    const governance = await import('../tools/governance.js')
-    expect(governance.createAdrDraftSchema).toBeDefined()
-    expect(governance.submitAdrReviewSchema).toBeDefined()
-    expect(governance.recordAdrDecisionSchema).toBeDefined()
-    expect(typeof governance.createAdrDraft).toBe('function')
-    expect(typeof governance.submitAdrReview).toBe('function')
-    expect(typeof governance.recordAdrDecision).toBe('function')
-
-    const skills = await import('../tools/skills.js')
-    expect(skills.skListSchema).toBeDefined()
-    expect(skills.skGetSchema).toBeDefined()
-    expect(skills.skGetSchema.skill_id).toBeDefined()
-    expect(skills.skCreateSchema).toBeDefined()
-    expect(skills.skCreateSchema.skill_id).toBeDefined()
-    expect(skills.skCreateSchema.name).toBeDefined()
-    expect(skills.skCreateSchema.body).toBeDefined()
-    expect(skills.skUpdateSchema).toBeDefined()
-    expect(skills.skUpdateSchema.skill_id).toBeDefined()
-    expect(skills.skActivateSchema).toBeDefined()
-    expect(skills.skActivateSchema.skill_id).toBeDefined()
-    expect(skills.skActivateSchema.status).toBeDefined()
-    expect(typeof skills.skList).toBe('function')
-    expect(typeof skills.skGet).toBe('function')
-    expect(typeof skills.skCreate).toBe('function')
-    expect(typeof skills.skUpdate).toBe('function')
-    expect(typeof skills.skActivate).toBe('function')
-
-    // project-list module
-    const projectList = await import('../tools/project-list.js')
-    expect(projectList.projectListSchema).toBeDefined()
-    expect(typeof projectList.projectList).toBe('function')
-
-    // skill-assign module (sk_assign, sk_unassign, sk_export)
-    const skillAssign = await import('../tools/skill-assign.js')
-    expect(skillAssign.skAssignSchema).toBeDefined()
-    expect(skillAssign.skAssignSchema.project_id).toBeDefined()
-    expect(skillAssign.skAssignSchema.skill_id).toBeDefined()
-    expect(skillAssign.skUnassignSchema).toBeDefined()
-    expect(skillAssign.skUnassignSchema.project_id).toBeDefined()
-    expect(skillAssign.skExportSchema).toBeDefined()
-    expect(skillAssign.skExportSchema.project_id).toBeDefined()
-    expect(typeof skillAssign.skAssign).toBe('function')
-    expect(typeof skillAssign.skUnassign).toBe('function')
-    expect(typeof skillAssign.skExport).toBe('function')
-
-    // reviews module (rv_list, rv_get, rv_create, rv_decide, rv_comment)
-    const reviews = await import('../tools/reviews.js')
-    expect(reviews.rvListSchema).toBeDefined()
-    expect(reviews.rvGetSchema).toBeDefined()
-    expect(reviews.rvCreateSchema).toBeDefined()
-    expect(reviews.rvCreateSchema.entity_type).toBeDefined()
-    expect(reviews.rvCreateSchema.entity_id).toBeDefined()
-    expect(reviews.rvDecideSchema).toBeDefined()
-    expect(reviews.rvDecideSchema.review_id).toBeDefined()
-    expect(reviews.rvDecideSchema.transition).toBeDefined()
-    expect(reviews.rvCommentSchema).toBeDefined()
-    expect(reviews.rvCommentSchema.review_id).toBeDefined()
-    expect(reviews.rvCommentSchema.body).toBeDefined()
-    expect(typeof reviews.rvList).toBe('function')
-    expect(typeof reviews.rvGet).toBe('function')
-    expect(typeof reviews.rvCreate).toBe('function')
-    expect(typeof reviews.rvDecide).toBe('function')
-    expect(typeof reviews.rvComment).toBe('function')
-
-    // list-tasks module (task_list)
-    const listTasks = await import('../tools/list-tasks.js')
-    expect(listTasks.listTasksSchema).toBeDefined()
-    expect(listTasks.listTasksSchema.project_id).toBeDefined()
-    expect(typeof listTasks.listTasks).toBe('function')
-
-    // list-documents module (doc_list)
-    const listDocuments = await import('../tools/list-documents.js')
-    expect(listDocuments.listDocumentsSchema).toBeDefined()
-    expect(listDocuments.listDocumentsSchema.project_id).toBeDefined()
-    expect(typeof listDocuments.listDocuments).toBe('function')
-  })
-})

package/src/__tests__/setup.ts

@@ -1,15 +0,0 @@
-/**
- * Global test setup for MCP server tests.
- *
- * Sets environment variables needed for the Nexus API client.
- */
-
-import { vi } from 'vitest'
-
-// Mock environment variables for Nexus API client
-process.env.NEXUS_API_URL = 'https://test.nexus.example.com'
-process.env.NEXUS_PRIVATE_TOKEN =
-  'nxs_pat_test-token-for-unit-tests-1234567890abc'
-
-// Suppress console.error from MCP tools during tests
-vi.spyOn(console, 'error').mockImplementation(() => {})

package/src/__tests__/task-list-and-doc-list.test.ts

@@ -1,226 +0,0 @@
-/**
- * Tests for task_list and doc_list tools.
- */
-
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { mockApiError, mockApiSuccess, parseToolResponse, TEST_IDS } from './helpers'
-
-vi.mock('../nexus-api.js', () => ({
-  nexusPost: vi.fn(),
-}))
-
-import { nexusPost } from '../nexus-api.js'
-
-// ---------------------------------------------------------------------------
-// task_list
-// ---------------------------------------------------------------------------
-
-describe('task_list', () => {
-  beforeEach(() => {
-    vi.restoreAllMocks()
-  })
-
-  it('should list tasks for a project', async () => {
-    vi.mocked(nexusPost).mockResolvedValue(
-      mockApiSuccess({
-        action: 'task_list',
-        project_id: TEST_IDS.projectId,
-        count: 2,
-        tasks: [
-          {
-            id: TEST_IDS.taskId,
-            title: 'Implement feature',
-            status: 'open',
-            priority: 'high',
-          },
-          {
-            id: TEST_IDS.noteId,
-            title: 'Fix bug',
-            status: 'in_progress',
-            priority: 'normal',
-          },
-        ],
-      }),
-    )
-
-    const { listTasks } = await import('../tools/list-tasks.js')
-    const result = await listTasks({
-      project_id: TEST_IDS.projectId,
-      user_id: TEST_IDS.userId,
-    })
-
-    expect(result.isError).toBeUndefined()
-    const parsed = parseToolResponse(result)
-    expect(parsed.action).toBe('task_list')
-    expect(parsed.count).toBe(2)
-    expect(parsed.tasks).toHaveLength(2)
-  })
-
-  it('should pass status_filter to API', async () => {
-    vi.mocked(nexusPost).mockResolvedValue(
-      mockApiSuccess({
-        action: 'task_list',
-        project_id: TEST_IDS.projectId,
-        count: 1,
-        tasks: [
-          { id: TEST_IDS.taskId, title: 'Open task', status: 'open' },
-        ],
-      }),
-    )
-
-    const { listTasks } = await import('../tools/list-tasks.js')
-    await listTasks({
-      project_id: TEST_IDS.projectId,
-      status_filter: ['open', 'in_progress'],
-      user_id: TEST_IDS.userId,
-    })
-
-    expect(vi.mocked(nexusPost)).toHaveBeenCalledWith('/api/mcp/tasks', {
-      action: 'task_list',
-      project_id: TEST_IDS.projectId,
-      status_filter: ['open', 'in_progress'],
-      limit: 50,
-    })
-  })
-
-  it('should return error on API failure', async () => {
-    vi.mocked(nexusPost).mockResolvedValue(mockApiError('Project not found', 404))
-
-    const { listTasks } = await import('../tools/list-tasks.js')
-    const result = await listTasks({
-      project_id: TEST_IDS.projectId,
-      user_id: TEST_IDS.userId,
-    })
-
-    expect(result.isError).toBe(true)
-  })
-
-  it('should handle empty task list', async () => {
-    vi.mocked(nexusPost).mockResolvedValue(
-      mockApiSuccess({
-        action: 'task_list',
-        project_id: TEST_IDS.projectId,
-        count: 0,
-        tasks: [],
-      }),
-    )
-
-    const { listTasks } = await import('../tools/list-tasks.js')
-    const result = await listTasks({
-      project_id: TEST_IDS.projectId,
-      user_id: TEST_IDS.userId,
-    })
-
-    expect(result.isError).toBeUndefined()
-    const parsed = parseToolResponse(result)
-    expect(parsed.count).toBe(0)
-    expect(parsed.tasks).toHaveLength(0)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// doc_list
-// ---------------------------------------------------------------------------
-
-describe('doc_list', () => {
-  beforeEach(() => {
-    vi.restoreAllMocks()
-  })
-
-  it('should list documents for a project', async () => {
-    vi.mocked(nexusPost).mockResolvedValue(
-      mockApiSuccess({
-        action: 'doc_list',
-        project_id: TEST_IDS.projectId,
-        count: 2,
-        documents: [
-          {
-            id: TEST_IDS.documentId,
-            title: 'Research Findings',
-            source: 'agent:app-agent',
-            classification: 'unclassified',
-          },
-          {
-            id: TEST_IDS.noteId,
-            title: 'E2E Test Plan',
-            source: 'mcp',
-            classification: 'unclassified',
-          },
-        ],
-      }),
-    )
-
-    const { listDocuments } = await import('../tools/list-documents.js')
-    const result = await listDocuments({
-      project_id: TEST_IDS.projectId,
-      user_id: TEST_IDS.userId,
-    })
-
-    expect(result.isError).toBeUndefined()
-    const parsed = parseToolResponse(result)
-    expect(parsed.action).toBe('doc_list')
-    expect(parsed.count).toBe(2)
-    expect(parsed.documents).toHaveLength(2)
-  })
-
-  it('should pass source filter to API', async () => {
-    vi.mocked(nexusPost).mockResolvedValue(
-      mockApiSuccess({
-        action: 'doc_list',
-        project_id: TEST_IDS.projectId,
-        count: 1,
-        documents: [
-          { id: TEST_IDS.documentId, title: 'Agent doc', source: 'agent:app-agent' },
-        ],
-      }),
-    )
-
-    const { listDocuments } = await import('../tools/list-documents.js')
-    await listDocuments({
-      project_id: TEST_IDS.projectId,
-      source: 'agent:app-agent',
-      user_id: TEST_IDS.userId,
-    })
-
-    expect(vi.mocked(nexusPost)).toHaveBeenCalledWith('/api/mcp/documents', {
-      action: 'doc_list',
-      project_id: TEST_IDS.projectId,
-      source: 'agent:app-agent',
-      limit: 50,
-    })
-  })
-
-  it('should return error on API failure', async () => {
-    vi.mocked(nexusPost).mockResolvedValue(mockApiError('No access to this project', 403))
-
-    const { listDocuments } = await import('../tools/list-documents.js')
-    const result = await listDocuments({
-      project_id: TEST_IDS.projectId,
-      user_id: TEST_IDS.userId,
-    })
-
-    expect(result.isError).toBe(true)
-  })
-
-  it('should handle empty document list', async () => {
-    vi.mocked(nexusPost).mockResolvedValue(
-      mockApiSuccess({
-        action: 'doc_list',
-        project_id: TEST_IDS.projectId,
-        count: 0,
-        documents: [],
-      }),
-    )
-
-    const { listDocuments } = await import('../tools/list-documents.js')
-    const result = await listDocuments({
-      project_id: TEST_IDS.projectId,
-      user_id: TEST_IDS.userId,
-    })
-
-    expect(result.isError).toBeUndefined()
-    const parsed = parseToolResponse(result)
-    expect(parsed.count).toBe(0)
-    expect(parsed.documents).toHaveLength(0)
-  })
-})

package/src/auth.ts

@@ -1,81 +0,0 @@
-/**
- * MCP Authentication Layer
- *
- * Resolves the NEXUS_PRIVATE_TOKEN environment variable at server startup
- * to a verified user identity by calling the Nexus API identity endpoint.
- *
- * Flow:
- *   1. Read NEXUS_PRIVATE_TOKEN from process.env
- *   2. Call GET /api/mcp/identity with Bearer token
- *   3. Cache resolved identity for the lifetime of the MCP process
- */
-
-import { nexusGet } from './nexus-api.js'
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface McpIdentity {
-  userId: string
-  email: string | null
-  displayName: string | null
-  isPlatformAdmin: boolean
-  isPlatformOwner: boolean
-  tenantId: string | null
-  memberships: Array<{ project_id: string; role: string }>
-  agentAssignments: Array<{
-    project_id: string
-    agent_id: string
-    agent_owner: string
-  }>
-}
-
-// Module-level cache: resolved once at startup
-let _identity: McpIdentity | null = null
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve the MCP server identity from NEXUS_PRIVATE_TOKEN.
- * Called once at server startup. Caches the result.
- * Throws if no valid token is available.
- */
-export async function initIdentity(): Promise<McpIdentity> {
-  if (_identity) return _identity
-
-  const rawToken = process.env.NEXUS_PRIVATE_TOKEN
-  if (!rawToken) {
-    throw new Error(
-      'MCP: NEXUS_PRIVATE_TOKEN is not set. The MCP server requires a valid nxs_pat_* token.',
-    )
-  }
-
-  const result = await nexusGet<McpIdentity>('/api/mcp/identity')
-
-  if (!result.ok || !result.data) {
-    throw new Error(
-      `MCP: Identity resolution failed: ${result.error ?? 'Unknown error'}. Check that the token is valid, not expired, and not revoked.`,
-    )
-  }
-
-  _identity = result.data
-
-  console.error(
-    `[nexus-mcp] Identity resolved: ${_identity.displayName ?? _identity.email ?? _identity.userId} (admin=${_identity.isPlatformAdmin}, owner=${_identity.isPlatformOwner})`,
-  )
-
-  return _identity
-}
-
-/**
- * Get the cached MCP identity. Must call initIdentity() first.
- */
-export function getIdentity(): McpIdentity {
-  if (!_identity) {
-    throw new Error('MCP: Identity not initialized. Call initIdentity() first.')
-  }
-  return _identity
-}

package/src/machine-id.ts

@@ -1,60 +0,0 @@
-/**
- * Machine ID module for Nexus MCP server.
- *
- * Reads or generates a persistent machine identifier stored at
- * ~/.config/nexus/machine.toml. This ID is sent as X-Nexus-Machine-Id
- * header with every API request so session entries can be attributed
- * to a specific machine.
- *
- * Format of machine.toml:
- *   machine_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
- */
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-import { randomUUID } from 'node:crypto'
-
-const CONFIG_DIR = join(homedir(), '.config', 'nexus')
-const MACHINE_TOML = join(CONFIG_DIR, 'machine.toml')
-
-let _cachedId: string | null = null
-
-/**
- * Get the persistent machine ID, creating one if it doesn't exist.
- * Returns null only if file I/O fails (e.g. read-only filesystem).
- */
-export function getMachineId(): string | null {
-  if (_cachedId) return _cachedId
-
-  try {
-    // Try to read existing
-    if (existsSync(MACHINE_TOML)) {
-      const content = readFileSync(MACHINE_TOML, 'utf-8')
-      const match = content.match(/machine_id\s*=\s*"([^"]+)"/)
-      if (match?.[1]) {
-        _cachedId = match[1]
-        return _cachedId
-      }
-    }
-
-    // Generate new machine ID
-    const id = randomUUID()
-    mkdirSync(CONFIG_DIR, { recursive: true })
-    writeFileSync(
-      MACHINE_TOML,
-      `# Nexus persistent machine identifier\n# Generated automatically — do not edit\nmachine_id = "${id}"\n`,
-      'utf-8',
-    )
-    _cachedId = id
-    return _cachedId
-  } catch {
-    // Silently fail — machine_id is optional enrichment
-    return null
-  }
-}
-
-/** Reset cached machine ID (for testing). */
-export function resetMachineId(): void {
-  _cachedId = null
-}