@gwdn/nexus-mcp 0.8.1 → 0.8.3

package/README.md

@@ -78,6 +78,31 @@ src/
   __tests__/         # Unit tests (112) and E2E integration tests (34)
 ```
 
+## Known Issues
+
+### npx cache prevents version upgrade
+
+When using `npx` to run the MCP server, npm caches the resolved package in
+`~/.npm/_npx/`. Subsequent invocations may continue to use the cached
+(outdated) version even after a new release is published — especially in
+terminals that were started before the update.
+
+**Symptoms:** MCP tools report an older version, or new tools/fixes are missing.
+
+**Fix:** Before starting OpenCode, clear stale npx caches:
+
+```bash
+find ~/.npm/_npx -path "*/node_modules/@gwdn/nexus-mcp/package.json" \
+  -exec node -e "if(require('{}').version!=='0.8.1') console.log(require('path').resolve('{}','../../..'))" \; \
+  | xargs rm -rf
+```
+
+Then start OpenCode normally. npx will fetch the latest version into a fresh
+cache entry.
+
+> **Tip:** To avoid this entirely, pin `@latest` in your MCP config args:
+> `["--yes", "@gwdn/nexus-mcp@latest"]`
+
 ## Related
 
 - [nexus](https://github.com/gwnexus/nexus-hub) — Backend + Frontend (Next.js/Supabase/Netlify)

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

@@ -26,6 +26,7 @@ export declare const appendSessionEntrySchema: {
     linked_entity_type: z.ZodOptional<z.ZodString>;
     linked_entity_id: z.ZodOptional<z.ZodString>;
     agent_id: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodString>;
 };
 type AppendSessionEntryArgs = {
     session_id: string;
@@ -35,6 +36,7 @@ type AppendSessionEntryArgs = {
     linked_entity_id?: string;
     user_id: string;
     agent_id?: string;
+    metadata?: string;
 };
 export declare function appendSessionEntry(args: AppendSessionEntryArgs): Promise<{
     content: {

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;;;;;;;;;;;;;;;;;;;;CAgCpC,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;CAClB,CAAA;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB;;;;;;;;;;;;GA4BpE"}
+{"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"}

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

@@ -37,8 +37,31 @@ export const appendSessionEntrySchema = {
         .optional()
         .describe('UUID of the linked entity'),
     agent_id: z.string().max(200).optional().describe('Agent identifier if applicable'),
+    metadata: z
+        .string()
+        .max(10_000)
+        .optional()
+        .describe('JSON string of metadata to merge into the session entry. ' +
+        'Example: \'{"model": "claude-opus-4", "toolstack": "opencode", "machine_id": "..."}\''),
 };
 export async function appendSessionEntry(args) {
+    let parsedMetadata;
+    if (args.metadata) {
+        try {
+            parsedMetadata = JSON.parse(args.metadata);
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ error: 'metadata must be a valid JSON string' }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
     const result = await nexusPost('/api/mcp/sessions', {
         action: 'session_append',
         session_id: args.session_id,
@@ -47,6 +70,7 @@ export async function appendSessionEntry(args) {
         agent_id: args.agent_id,
         linked_entity_type: args.linked_entity_type,
         linked_entity_id: args.linked_entity_id,
+        ...(parsedMetadata ? { metadata: parsedMetadata } : {}),
     });
     if (!result.ok) {
         return {

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":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IACnE,UAAU,EAAE,CAAC;SACV,IAAI,CAAC;QACJ,qBAAqB;QACrB,cAAc;QACd,cAAc;QACd,aAAa;QACb,gBAAgB;QAChB,gBAAgB;QAChB,mBAAmB;QACnB,aAAa;QACb,cAAc;QACd,kBAAkB;QAClB,MAAM;QACN,YAAY;KACb,CAAC;SACD,QAAQ,CAAC,uBAAuB,CAAC;IACpC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,8BAA8B,CAAC;IACzE,kBAAkB,EAAE,CAAC;SAClB,MAAM,EAAE;SACR,GAAG,CAAC,EAAE,CAAC;SACP,QAAQ,EAAE;SACV,QAAQ,CACP,6EAA6E,CAC9E;IACH,gBAAgB,EAAE,CAAC;SAChB,MAAM,EAAE;SACR,IAAI,EAAE;SACN,QAAQ,EAAE;SACV,QAAQ,CAAC,2BAA2B,CAAC;IACxC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;CACpF,CAAA;AAYD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAA4B;IACnE,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,mBAAmB,EAAE;QAClD,MAAM,EAAE,gBAAgB;QACxB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;QAC3C,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;KACxC,CAAC,CAAA;IAEF,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;iBACvD;aACF;YACD,OAAO,EAAE,IAAI;SACd,CAAA;IACH,CAAC;IAED,OAAO;QACL,OAAO,EAAE;YACP,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;SACtE;KACF,CAAA;AACH,CAAC"}
+{"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.1",
+  "version": "0.8.3",
   "description": "MCP server for the Nexus platform",
   "type": "module",
   "main": "dist/server.js",

package/src/__tests__/layer2-coordination.test.ts

@@ -206,6 +206,82 @@ describe('Layer 2: session_append', () => {
 
     expect(result.isError).toBe(true)
   })
+
+  it('should forward parsed metadata to the API', async () => {
+    vi.mocked(nexusPost).mockResolvedValue(
+      mockApiSuccess({
+        action: 'session_append',
+        entry_id: TEST_IDS.entryId,
+        session_id: TEST_IDS.sessionId,
+        entry_type: 'note',
+        project_id: TEST_IDS.projectId,
+      }),
+    )
+
+    const { appendSessionEntry } = await import('../tools/append-session-entry.js')
+    const metadata = JSON.stringify({
+      model: 'claude-opus-4',
+      toolstack: 'opencode',
+      machine_id: '00000000-0000-0000-0000-000000000001',
+    })
+    const result = await appendSessionEntry({
+      session_id: TEST_IDS.sessionId,
+      entry_type: 'note',
+      summary: 'Entry with metadata',
+      user_id: TEST_IDS.userId,
+      metadata,
+    })
+
+    expect(result.isError).toBeUndefined()
+    expect(vi.mocked(nexusPost)).toHaveBeenCalledWith(
+      '/api/mcp/sessions',
+      expect.objectContaining({
+        metadata: {
+          model: 'claude-opus-4',
+          toolstack: 'opencode',
+          machine_id: '00000000-0000-0000-0000-000000000001',
+        },
+      }),
+    )
+  })
+
+  it('should return error for invalid metadata JSON', async () => {
+    const { appendSessionEntry } = await import('../tools/append-session-entry.js')
+    const result = await appendSessionEntry({
+      session_id: TEST_IDS.sessionId,
+      entry_type: 'note',
+      summary: 'Bad metadata',
+      user_id: TEST_IDS.userId,
+      metadata: '{invalid json',
+    })
+
+    expect(result.isError).toBe(true)
+    const parsed = parseToolResponse(result)
+    expect(parsed.error).toContain('valid JSON')
+  })
+
+  it('should omit metadata key when not provided', async () => {
+    vi.mocked(nexusPost).mockResolvedValue(
+      mockApiSuccess({
+        action: 'session_append',
+        entry_id: TEST_IDS.entryId,
+        session_id: TEST_IDS.sessionId,
+        entry_type: 'note',
+        project_id: TEST_IDS.projectId,
+      }),
+    )
+
+    const { appendSessionEntry } = await import('../tools/append-session-entry.js')
+    await appendSessionEntry({
+      session_id: TEST_IDS.sessionId,
+      entry_type: 'note',
+      summary: 'No metadata',
+      user_id: TEST_IDS.userId,
+    })
+
+    const call = vi.mocked(nexusPost).mock.calls[0][1] as Record<string, unknown>
+    expect(call).not.toHaveProperty('metadata')
+  })
 })
 
 // ---------------------------------------------------------------------------

package/src/__tests__/server.test.ts

@@ -146,6 +146,7 @@ describe('MCP Server: Schema exports', () => {
 
     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')

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

@@ -41,6 +41,14 @@ export const appendSessionEntrySchema = {
     .optional()
     .describe('UUID of the linked entity'),
   agent_id: z.string().max(200).optional().describe('Agent identifier if applicable'),
+  metadata: z
+    .string()
+    .max(10_000)
+    .optional()
+    .describe(
+      'JSON string of metadata to merge into the session entry. ' +
+        'Example: \'{"model": "claude-opus-4", "toolstack": "opencode", "machine_id": "..."}\'',
+    ),
 }
 
 type AppendSessionEntryArgs = {
@@ -51,9 +59,27 @@ type AppendSessionEntryArgs = {
   linked_entity_id?: string
   user_id: string
   agent_id?: string
+  metadata?: string
 }
 
 export async function appendSessionEntry(args: AppendSessionEntryArgs) {
+  let parsedMetadata: Record<string, unknown> | undefined
+  if (args.metadata) {
+    try {
+      parsedMetadata = JSON.parse(args.metadata)
+    } catch {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify({ error: 'metadata must be a valid JSON string' }, null, 2),
+          },
+        ],
+        isError: true,
+      }
+    }
+  }
+
   const result = await nexusPost('/api/mcp/sessions', {
     action: 'session_append',
     session_id: args.session_id,
@@ -62,6 +88,7 @@ export async function appendSessionEntry(args: AppendSessionEntryArgs) {
     agent_id: args.agent_id,
     linked_entity_type: args.linked_entity_type,
     linked_entity_id: args.linked_entity_id,
+    ...(parsedMetadata ? { metadata: parsedMetadata } : {}),
   })
 
   if (!result.ok) {