@gwdn/nexus-mcp 0.7.0

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

@@ -0,0 +1,226 @@
+/**
+ * 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

@@ -0,0 +1,81 @@
+/**
+ * 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/nexus-api.ts

@@ -0,0 +1,127 @@
+/**
+ * Nexus API client for MCP server context.
+ *
+ * Replaces direct Supabase access with HTTP calls to the Nexus API.
+ * All operations go through /api/mcp/* endpoints, authenticated
+ * via the NEXUS_PRIVATE_TOKEN (nxs_pat_*) Bearer token.
+ */
+
+let _baseUrl: string | null = null
+let _token: string | null = null
+
+/**
+ * Reset the cached API configuration. Used by E2E tests to switch
+ * from mocked env vars to real credentials.
+ */
+export function resetApiConfig(): void {
+  _baseUrl = null
+  _token = null
+}
+
+function getConfig(): { baseUrl: string; token: string } {
+  if (_baseUrl && _token) return { baseUrl: _baseUrl, token: _token }
+
+  const url = process.env.NEXUS_API_URL ?? process.env.NEXUS_URL
+  const token = process.env.NEXUS_PRIVATE_TOKEN
+
+  if (!url) {
+    throw new Error(
+      'MCP: Missing NEXUS_API_URL. Set the base URL of the Nexus app (e.g. https://nexus.gatewarden.eu).',
+    )
+  }
+  if (!token) {
+    throw new Error(
+      'MCP: Missing NEXUS_PRIVATE_TOKEN. The MCP server requires a valid nxs_pat_* token.',
+    )
+  }
+
+  // Normalize: strip trailing slash
+  _baseUrl = url.replace(/\/$/, '')
+  _token = token.trim()
+
+  return { baseUrl: _baseUrl, token: _token }
+}
+
+export interface NexusApiResponse<T = unknown> {
+  ok: boolean
+  status: number
+  data: T | null
+  error: string | null
+}
+
+/** Default HTTP timeout in milliseconds (30 seconds). */
+const DEFAULT_TIMEOUT_MS = 30_000
+
+/**
+ * Make an authenticated request to the Nexus API.
+ */
+export async function nexusApi<T = unknown>(
+  path: string,
+  options: {
+    method?: 'GET' | 'POST' | 'PATCH' | 'DELETE'
+    body?: unknown
+    timeoutMs?: number
+  } = {},
+): Promise<NexusApiResponse<T>> {
+  const { baseUrl, token } = getConfig()
+  const method = options.method ?? 'GET'
+  const url = `${baseUrl}${path}`
+
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+    'Content-Type': 'application/json',
+  }
+
+  try {
+    const fetchOpts: RequestInit = {
+      method,
+      headers,
+      signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    }
+    if (options.body !== undefined) {
+      fetchOpts.body = JSON.stringify(options.body)
+    }
+
+    const response = await fetch(url, fetchOpts)
+    const data = (await response.json()) as T & { error?: string }
+
+    if (!response.ok) {
+      return {
+        ok: false,
+        status: response.status,
+        data: null,
+        error:
+          (data as Record<string, unknown>)?.error as string ??
+          `HTTP ${response.status}`,
+      }
+    }
+
+    return { ok: true, status: response.status, data, error: null }
+  } catch (err) {
+    return {
+      ok: false,
+      status: 0,
+      data: null,
+      error: err instanceof Error ? err.message : 'Unknown fetch error',
+    }
+  }
+}
+
+/**
+ * Convenience: POST to a Nexus MCP endpoint.
+ */
+export async function nexusPost<T = unknown>(
+  path: string,
+  body: unknown,
+): Promise<NexusApiResponse<T>> {
+  return nexusApi<T>(path, { method: 'POST', body })
+}
+
+/**
+ * Convenience: GET from a Nexus MCP endpoint.
+ */
+export async function nexusGet<T = unknown>(
+  path: string,
+): Promise<NexusApiResponse<T>> {
+  return nexusApi<T>(path, { method: 'GET' })
+}