@gwdn/nexus-mcp 0.8.4 → 0.8.6

package/dist/machine-id.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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"
+ */
+/**
+ * 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 declare function getMachineId(): string | null;
+/** Reset cached machine ID (for testing). */
+export declare function resetMachineId(): void;
+//# sourceMappingURL=machine-id.d.ts.map

package/dist/machine-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-id.d.ts","sourceRoot":"","sources":["../src/machine-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH;;;GAGG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CA4B5C;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/dist/machine-id.js

@@ -0,0 +1,52 @@
+/**
+ * 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 = 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() {
+    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() {
+    _cachedId = null;
+}
+//# sourceMappingURL=machine-id.js.map

package/dist/machine-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-id.js","sourceRoot":"","sources":["../src/machine-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAC5E,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,CAAA;AACtD,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAA;AAErD,IAAI,SAAS,GAAkB,IAAI,CAAA;AAEnC;;;GAGG;AACH,MAAM,UAAU,YAAY;IAC1B,IAAI,SAAS;QAAE,OAAO,SAAS,CAAA;IAE/B,IAAI,CAAC;QACH,uBAAuB;QACvB,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAA;YACnD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAA;YACzD,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACf,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;gBACpB,OAAO,SAAS,CAAA;YAClB,CAAC;QACH,CAAC;QAED,0BAA0B;QAC1B,MAAM,EAAE,GAAG,UAAU,EAAE,CAAA;QACvB,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QAC1C,aAAa,CACX,YAAY,EACZ,iGAAiG,EAAE,KAAK,EACxG,OAAO,CACR,CAAA;QACD,SAAS,GAAG,EAAE,CAAA;QACd,OAAO,SAAS,CAAA;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,oDAAoD;QACpD,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,cAAc;IAC5B,SAAS,GAAG,IAAI,CAAA;AAClB,CAAC"}

package/dist/nexus-api.d.ts

@@ -22,6 +22,7 @@ export interface NexusApiResponse<T = unknown> {
 export declare function nexusApi<T = unknown>(path: string, options?: {
     method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
     body?: unknown;
+    headers?: Record<string, string>;
     timeoutMs?: number;
 }): Promise<NexusApiResponse<T>>;
 /**

package/dist/nexus-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nexus-api.d.ts","sourceRoot":"","sources":["../src/nexus-api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;GAGG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAGrC;AA0BD,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC3C,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB;AAKD;;GAEG;AACH,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;IAC5C,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACd,GACL,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CA2C9B;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAE9B;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAE9B"}
+{"version":3,"file":"nexus-api.d.ts","sourceRoot":"","sources":["../src/nexus-api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH;;;GAGG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAIrC;AA0BD,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC3C,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB;AAKD;;GAEG;AACH,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;IAC5C,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,SAAS,CAAC,EAAE,MAAM,CAAA;CACd,GACL,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CA6C9B;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAE9B;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAE9B"}

package/dist/nexus-api.js

@@ -5,8 +5,17 @@
  * All operations go through /api/mcp/* endpoints, authenticated
  * via the NEXUS_PRIVATE_TOKEN (nxs_pat_*) Bearer token.
  */
+import { getMachineId } from './machine-id.js';
 let _baseUrl = null;
 let _token = null;
+let _machineId = null;
+// Eagerly resolve machine ID (sync, cached after first call)
+try {
+    _machineId = getMachineId();
+}
+catch {
+    // machine_id is optional enrichment — never block startup
+}
 /**
  * Reset the cached API configuration. Used by E2E tests to switch
  * from mocked env vars to real credentials.
@@ -14,6 +23,7 @@ let _token = null;
 export function resetApiConfig() {
     _baseUrl = null;
     _token = null;
+    _machineId = getMachineId();
 }
 function getConfig() {
     if (_baseUrl && _token)
@@ -43,6 +53,8 @@ export async function nexusApi(path, options = {}) {
     const headers = {
         Authorization: `Bearer ${token}`,
         'Content-Type': 'application/json',
+        ...(_machineId ? { 'X-Nexus-Machine-Id': _machineId } : {}),
+        ...(options.headers ?? {}),
     };
     try {
         const fetchOpts = {

package/dist/nexus-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"nexus-api.js","sourceRoot":"","sources":["../src/nexus-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"nexus-api.js","sourceRoot":"","sources":["../src/nexus-api.ts"],"names":[],"mappings":"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"}

package/dist/tools/append-session-entry.d.ts

@@ -21,6 +21,8 @@ export declare const appendSessionEntrySchema: {
         handoff_recorded: "handoff_recorded";
         note: "note";
         correction: "correction";
+        security_scan: "security_scan";
+        performance_scan: "performance_scan";
     }>;
     summary: z.ZodString;
     linked_entity_type: z.ZodOptional<z.ZodString>;

package/dist/tools/append-session-entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"append-session-entry.d.ts","sourceRoot":"","sources":["../../src/tools/append-session-entry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;CAwCpC,CAAA;AAED,KAAK,sBAAsB,GAAG;IAC5B,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB;;;;;;;;;;;;GA8CpE"}
+{"version":3,"file":"append-session-entry.d.ts","sourceRoot":"","sources":["../../src/tools/append-session-entry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;CA0CpC,CAAA;AAED,KAAK,sBAAsB,GAAG;IAC5B,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB;;;;;;;;;;;;GA8CpE"}

package/dist/tools/append-session-entry.js

@@ -23,6 +23,8 @@ export const appendSessionEntrySchema = {
         'handoff_recorded',
         'note',
         'correction',
+        'security_scan',
+        'performance_scan',
     ])
         .describe('Type of session entry'),
     summary: z.string().max(100_000).describe('Entry content / summary text'),

package/dist/tools/append-session-entry.js.map

@@ -1 +1 @@
-{"version":3,"file":"append-session-entry.js","sourceRoot":"","sources":["../../src/tools/append-session-entry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"append-session-entry.js","sourceRoot":"","sources":["../../src/tools/append-session-entry.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gwdn/nexus-mcp",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "MCP server for the Nexus platform",
   "type": "module",
   "main": "dist/server.js",

package/src/__tests__/machine-id.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Tests for src/machine-id.ts
+ *
+ * Covers:
+ * - Reading existing machine.toml
+ * - Generating new machine ID when file doesn't exist
+ * - Caching behavior
+ * - Graceful failure on I/O errors
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+// Mock fs and os modules
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+  mkdirSync: vi.fn(),
+  readFileSync: vi.fn(),
+  writeFileSync: vi.fn(),
+}))
+
+vi.mock('node:os', () => ({
+  homedir: vi.fn(() => '/mock-home'),
+}))
+
+const EXPECTED_TOML_PATH = join('/mock-home', '.config', 'nexus', 'machine.toml')
+
+describe('machine-id', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.restoreAllMocks()
+    vi.mocked(homedir).mockReturnValue('/mock-home')
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('should read machine_id from existing machine.toml', async () => {
+    vi.mocked(existsSync).mockReturnValue(true)
+    vi.mocked(readFileSync).mockReturnValue(
+      '# Nexus persistent machine identifier\nmachine_id = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"\n',
+    )
+
+    const { getMachineId, resetMachineId } = await import('../machine-id.js')
+    resetMachineId()
+    const id = getMachineId()
+
+    expect(id).toBe('aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee')
+    expect(existsSync).toHaveBeenCalledWith(EXPECTED_TOML_PATH)
+    expect(readFileSync).toHaveBeenCalledWith(EXPECTED_TOML_PATH, 'utf-8')
+  })
+
+  it('should generate and persist machine_id when file does not exist', async () => {
+    vi.mocked(existsSync).mockReturnValue(false)
+
+    const { getMachineId, resetMachineId } = await import('../machine-id.js')
+    resetMachineId()
+    const id = getMachineId()
+
+    expect(id).toBeDefined()
+    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/)
+    expect(mkdirSync).toHaveBeenCalledWith(
+      join('/mock-home', '.config', 'nexus'),
+      { recursive: true },
+    )
+    expect(writeFileSync).toHaveBeenCalledWith(
+      EXPECTED_TOML_PATH,
+      expect.stringContaining(`machine_id = "${id}"`),
+      'utf-8',
+    )
+  })
+
+  it('should cache the machine_id after first read', async () => {
+    vi.mocked(existsSync).mockReturnValue(true)
+    vi.mocked(readFileSync).mockReturnValue('machine_id = "cached-id-1234"\n')
+
+    const { getMachineId, resetMachineId } = await import('../machine-id.js')
+    resetMachineId()
+
+    const callsBefore = vi.mocked(readFileSync).mock.calls.length
+    const id1 = getMachineId()
+    const id2 = getMachineId()
+
+    expect(id1).toBe('cached-id-1234')
+    expect(id1).toBe(id2)
+    // readFileSync should only be called once more after reset (cached on second call)
+    expect(vi.mocked(readFileSync).mock.calls.length - callsBefore).toBe(1)
+  })
+
+  it('should return null on I/O error', async () => {
+    vi.mocked(existsSync).mockImplementation(() => {
+      throw new Error('Permission denied')
+    })
+
+    const { getMachineId, resetMachineId } = await import('../machine-id.js')
+    resetMachineId()
+    const id = getMachineId()
+
+    expect(id).toBeNull()
+  })
+
+  it('should generate new ID if toml exists but has no machine_id line', async () => {
+    vi.mocked(existsSync).mockReturnValue(true)
+    vi.mocked(readFileSync).mockReturnValue('# empty config\n')
+
+    const { getMachineId, resetMachineId } = await import('../machine-id.js')
+    resetMachineId()
+    const id = getMachineId()
+
+    expect(id).toBeDefined()
+    expect(id).toMatch(/^[0-9a-f]{8}-/)
+    expect(writeFileSync).toHaveBeenCalled()
+  })
+
+  it('should resetMachineId clear the cache', async () => {
+    vi.mocked(existsSync).mockReturnValue(true)
+    vi.mocked(readFileSync)
+      .mockReturnValueOnce('machine_id = "first-id"\n')
+      .mockReturnValueOnce('machine_id = "second-id"\n')
+
+    const { getMachineId, resetMachineId } = await import('../machine-id.js')
+    resetMachineId()
+
+    const id1 = getMachineId()
+    expect(id1).toBe('first-id')
+
+    resetMachineId()
+    const id2 = getMachineId()
+    expect(id2).toBe('second-id')
+
+    expect(id1).not.toBe(id2)
+  })
+})

package/src/__tests__/nexus-api.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Tests for src/nexus-api.ts
+ *
+ * Covers:
+ * - X-Nexus-Machine-Id header is sent automatically when machine_id is available
+ * - Custom headers parameter is forwarded
+ * - nexusPost convenience works correctly
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Mock machine-id module before importing nexus-api
+vi.mock('../machine-id.js', () => ({
+  getMachineId: vi.fn(() => 'test-machine-uuid-1234'),
+  resetMachineId: vi.fn(),
+}))
+
+describe('nexus-api: header injection', () => {
+  let nexusApi: typeof import('../nexus-api.js').nexusApi
+  let nexusPost: typeof import('../nexus-api.js').nexusPost
+  let fetchSpy: ReturnType<typeof vi.fn>
+
+  beforeEach(async () => {
+    vi.resetModules()
+
+    process.env.NEXUS_API_URL = 'https://test.nexus.example.com'
+    process.env.NEXUS_PRIVATE_TOKEN = 'nxs_pat_test-token-for-header-tests-abc'
+
+    fetchSpy = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ action: 'test' }),
+    })
+    vi.stubGlobal('fetch', fetchSpy)
+
+    const mod = await import('../nexus-api.js')
+    nexusApi = mod.nexusApi
+    nexusPost = mod.nexusPost
+    mod.resetApiConfig()
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('should include X-Nexus-Machine-Id header in requests', async () => {
+    await nexusApi('/api/mcp/sessions', { method: 'POST', body: { action: 'test' } })
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1)
+    const [, opts] = fetchSpy.mock.calls[0]
+    expect(opts.headers['X-Nexus-Machine-Id']).toBe('test-machine-uuid-1234')
+  })
+
+  it('should include Authorization and Content-Type headers', async () => {
+    await nexusApi('/api/mcp/sessions')
+
+    const [, opts] = fetchSpy.mock.calls[0]
+    expect(opts.headers['Authorization']).toBe(
+      'Bearer nxs_pat_test-token-for-header-tests-abc',
+    )
+    expect(opts.headers['Content-Type']).toBe('application/json')
+  })
+
+  it('should merge custom headers with defaults', async () => {
+    await nexusApi('/api/mcp/sessions', {
+      method: 'POST',
+      body: { action: 'test' },
+      headers: { 'X-Nexus-Toolstack': 'opencode v0.3.0' },
+    })
+
+    const [, opts] = fetchSpy.mock.calls[0]
+    expect(opts.headers['X-Nexus-Machine-Id']).toBe('test-machine-uuid-1234')
+    expect(opts.headers['X-Nexus-Toolstack']).toBe('opencode v0.3.0')
+  })
+
+  it('should allow custom headers to override machine-id', async () => {
+    await nexusApi('/api/mcp/sessions', {
+      headers: { 'X-Nexus-Machine-Id': 'override-id' },
+    })
+
+    const [, opts] = fetchSpy.mock.calls[0]
+    expect(opts.headers['X-Nexus-Machine-Id']).toBe('override-id')
+  })
+
+  it('nexusPost should also include machine-id header', async () => {
+    await nexusPost('/api/mcp/sessions', { action: 'session_create' })
+
+    const [, opts] = fetchSpy.mock.calls[0]
+    expect(opts.headers['X-Nexus-Machine-Id']).toBe('test-machine-uuid-1234')
+    expect(opts.method).toBe('POST')
+  })
+})
+
+describe('nexus-api: no machine-id available', () => {
+  beforeEach(async () => {
+    vi.resetModules()
+    // Re-mock with null return
+    vi.doMock('../machine-id.js', () => ({
+      getMachineId: vi.fn(() => null),
+      resetMachineId: vi.fn(),
+    }))
+
+    process.env.NEXUS_API_URL = 'https://test.nexus.example.com'
+    process.env.NEXUS_PRIVATE_TOKEN = 'nxs_pat_test-token-no-machine-id-abcde'
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('should not include X-Nexus-Machine-Id header when machine_id is null', async () => {
+    const fetchSpy = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ action: 'test' }),
+    })
+    vi.stubGlobal('fetch', fetchSpy)
+
+    const mod = await import('../nexus-api.js')
+    mod.resetApiConfig()
+
+    await mod.nexusApi('/api/mcp/sessions')
+
+    const [, opts] = fetchSpy.mock.calls[0]
+    expect(opts.headers).not.toHaveProperty('X-Nexus-Machine-Id')
+  })
+})

package/src/machine-id.ts

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

package/src/nexus-api.ts

@@ -6,8 +6,18 @@
  * via the NEXUS_PRIVATE_TOKEN (nxs_pat_*) Bearer token.
  */
 
+import { getMachineId } from './machine-id.js'
+
 let _baseUrl: string | null = null
 let _token: string | null = null
+let _machineId: string | null = null
+
+// Eagerly resolve machine ID (sync, cached after first call)
+try {
+  _machineId = getMachineId()
+} catch {
+  // machine_id is optional enrichment — never block startup
+}
 
 /**
  * Reset the cached API configuration. Used by E2E tests to switch
@@ -16,6 +26,7 @@ let _token: string | null = null
 export function resetApiConfig(): void {
   _baseUrl = null
   _token = null
+  _machineId = getMachineId()
 }
 
 function getConfig(): { baseUrl: string; token: string } {
@@ -60,6 +71,7 @@ export async function nexusApi<T = unknown>(
   options: {
     method?: 'GET' | 'POST' | 'PATCH' | 'DELETE'
     body?: unknown
+    headers?: Record<string, string>
     timeoutMs?: number
   } = {},
 ): Promise<NexusApiResponse<T>> {
@@ -70,6 +82,8 @@ export async function nexusApi<T = unknown>(
   const headers: Record<string, string> = {
     Authorization: `Bearer ${token}`,
     'Content-Type': 'application/json',
+    ...(_machineId ? { 'X-Nexus-Machine-Id': _machineId } : {}),
+    ...(options.headers ?? {}),
   }
 
   try {

package/src/tools/append-session-entry.ts

@@ -25,6 +25,8 @@ export const appendSessionEntrySchema = {
       'handoff_recorded',
       'note',
       'correction',
+      'security_scan',
+      'performance_scan',
     ])
     .describe('Type of session entry'),
   summary: z.string().max(100_000).describe('Entry content / summary text'),