fix(mcp): link_document_to_voucher marks the inbox item handled; document lists stop misleading agents (#2170)

Three MCP feedback reports (seq 265062, 288474, 288577; three companies) hit
the same hole: link_document_to_voucher attaches the document to the
verifikat but never stamps the inbox item it came from, and both inbox read
surfaces derive "handled" from the inbox row's own link columns, never from
document_attachments.journal_entry_id. So an attached document stayed
"unprocessed" forever: agents re-saw it as missing underlag (one reporter
paged 750 rows to find the ~15 real ones), and one user read the five
leftover rows as duplicates and was about to delete the only copies of
underlag sitting on posted verifikat.

- commitLinkDocumentToVoucher and the bulk twin now stamp
  invoice_inbox_items.created_journal_entry_id, keyed on document_id, CAS on
  both link columns, 23505 tolerated (samlingsverifikat). Same shape as the
  create_voucher + inbox_item_id stamp; best-effort so inbox bookkeeping
  never rolls back a committed link.
- gnubok_list_unmatched_documents returns file_name (same embed
  list_inbox_items uses) and the extraction's page coverage, so an agent can
  tell "no total on this document" from "we read 3 of 38 pages" and does not
  have to fetch each document to learn what it is (seq 265062, 288574).
- gnubok_list_transactions_without_documents no longer echoes the column
  default "uncategorized" on rows that are booked by construction:
  list_uncategorized_transactions uses the same word for "no journal entry
  yet", and an agent read the label and tried to re-book an already-booked
  share-capital deposit (seq 288574).

No tools/list payload change: the unmatched-documents item schema is
untyped and the category field already allowed null.


Claude-Session: https://claude.ai/code/session_013yw62FMXGSzo6icFDiBwP3

Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

extensions/general/mcp-server/__tests__/list-transactions-without-documents.test.ts

@@ -76,6 +76,26 @@ describe('gnubok_list_transactions_without_documents', () => {
     expect(result.transactions[0].journal_entry_id).toBe('je-1')
   })
 
+  it('never echoes the column default "uncategorized" on rows that are booked by construction', async () => {
+    // transactions.category keeps its default when a row is booked through a
+    // manual voucher + link (link-journal-entry.ts never writes category), and
+    // gnubok_list_uncategorized_transactions uses the same word to mean "no
+    // journal entry yet". Feedback seq 288574: an agent read the label and
+    // tried to book an already-booked share-capital deposit (A-2, 1930/2081).
+    const { supabase, enqueue } = createQueuedMockSupabase()
+    enqueue(envelope([
+      { ...row('t1', 'je-1'), category: 'uncategorized' },
+      { ...row('t2', 'je-2'), category: 'office_supplies' },
+    ], 2))
+
+    const result = (await tool.execute({}, 'company-1', 'user-1', supabase as never)) as {
+      transactions: Array<{ transaction_id: string; category: string | null; journal_entry_id: string }>
+    }
+
+    expect(result.transactions[0]).toMatchObject({ transaction_id: 't1', category: null, journal_entry_id: 'je-1' })
+    expect(result.transactions[1]).toMatchObject({ transaction_id: 't2', category: 'office_supplies' })
+  })
+
   it('returns empty result when nothing matches', async () => {
     const { supabase, enqueue } = createQueuedMockSupabase()
     enqueue(envelope([], 0))

extensions/general/mcp-server/__tests__/list-unmatched-documents.test.ts

@@ -77,10 +77,12 @@ describe('gnubok_list_unmatched_documents', () => {
           email_subject: null,
           email_received_at: null,
           created_at: '2026-06-01T00:00:00Z',
+          document_attachments: { file_name: 'V82_2025-08-05_DNB-Finans.pdf' },
           extracted_data: {
             supplier: { name: 'DNB Finans', orgNumber: '5164060161' },
             invoice: { currency: 'SEK', invoiceDate: '2025-08-05', paymentReference: '9581810307' },
             totals: { total: 13428 },
+            pages: { total: 38, analyzed: 3 },
           },
         },
         {
@@ -100,7 +102,13 @@ describe('gnubok_list_unmatched_documents', () => {
     enqueue({ data: [{ document_id: 'doc-2' }], error: null })
 
     const result = (await tool.execute({ limit: 20 }, 'company-1', 'user-1', supabase as never)) as {
-      items: Array<{ inbox_item_id: string; vendor_name: string | null; amount: number | null }>
+      items: Array<{
+        inbox_item_id: string
+        vendor_name: string | null
+        amount: number | null
+        file_name: string | null
+        pages: { total: number; analyzed: number } | null
+      }>
       count: number
     }
 
@@ -108,6 +116,39 @@ describe('gnubok_list_unmatched_documents', () => {
     expect(result.items[0].inbox_item_id).toBe('inbox-1')
     expect(result.items[0].vendor_name).toBe('DNB Finans')
     expect(result.items[0].amount).toBe(13428)
+    // The original file name and the page coverage of the extraction travel
+    // with the row (feedback seq 265062 / 288574): the agent must not have to
+    // fetch every document to learn what it is, and amount: null on a
+    // sliced 38-page PDF is not a fact about the file.
+    expect(result.items[0].file_name).toBe('V82_2025-08-05_DNB-Finans.pdf')
+    expect(result.items[0].pages).toEqual({ total: 38, analyzed: 3 })
+  })
+
+  it('tolerates the embed coming back as an array and a document with no page info', async () => {
+    const { supabase, enqueue } = createQueuedMockSupabase()
+    enqueue({
+      data: [
+        {
+          id: 'inbox-3',
+          document_id: 'doc-3',
+          source: 'email',
+          email_from: 'a@b.se',
+          email_subject: 'Kvitto',
+          email_received_at: '2026-06-02T00:00:00Z',
+          created_at: '2026-06-02T00:00:00Z',
+          document_attachments: [{ file_name: 'kvitto.jpg' }],
+          extracted_data: { totals: { total: 99 } },
+        },
+      ],
+      error: null,
+    })
+    enqueue({ data: [], error: null })
+
+    const result = (await tool.execute({ limit: 20 }, 'company-1', 'user-1', supabase as never)) as {
+      items: Array<{ file_name: string | null; pages: unknown }>
+    }
+    expect(result.items[0].file_name).toBe('kvitto.jpg')
+    expect(result.items[0].pages).toBeNull()
   })
 
   it('returns an empty result when the inbox query has nothing pending', async () => {

extensions/general/mcp-server/server.ts

@@ -5536,7 +5536,18 @@ export const tools: McpTool[] = [
         throw new Error(`transactions_without_documents failed: ${result?.code ?? 'unknown error'}`)
       }
 
-      const rows = result.transactions ?? []
+      // Every row here is booked by construction (the RPC joins
+      // journal_entries), but transactions.category keeps its column default
+      // 'uncategorized' when a row is booked by a manual voucher plus link
+      // (lib/transactions/link-journal-entry.ts never writes category).
+      // gnubok_list_uncategorized_transactions uses that same word to mean
+      // "no journal entry yet", so echoing it here made agents try to book an
+      // already-booked deposit (feedback seq 288574). null = no category
+      // label; the journal_entry_id is the booking truth.
+      const rows = (result.transactions ?? []).map((row) => {
+        const r = row as Record<string, unknown>
+        return r.category === 'uncategorized' ? { ...r, category: null } : r
+      })
       const total = result.total_count ?? 0
       return { transactions: rows, ...pageTail(rows, total, offset) }
     },
@@ -13488,7 +13499,7 @@ export const tools: McpTool[] = [
       const fetchSize = limit * 2
       let inboxQuery = supabase
         .from('invoice_inbox_items')
-        .select('id, document_id, source, email_from, email_subject, email_received_at, extracted_data, created_at')
+        .select('id, document_id, source, email_from, email_subject, email_received_at, extracted_data, created_at, document_attachments(file_name)')
         .eq('company_id', companyId)
         .not('document_id', 'is', null)
         .is('created_supplier_invoice_id', null)
@@ -13533,8 +13544,17 @@ export const tools: McpTool[] = [
           let currency: string | null = null
           let invoiceDate: string | null = null
           let paymentReference: string | null = null
+          // Page coverage of the extraction (set only when the PDF was sliced,
+          // extensions/general/invoice-inbox/lib/upload-and-extract.ts). Lets
+          // the agent tell "this document has no total" from "we read 3 of 38
+          // pages" instead of reading amount: null as a fact about the file.
+          let pages: { total: number; analyzed: number } | null = null
 
           if (extracted) {
+            const pageInfo = extracted.pages as { total?: unknown; analyzed?: unknown } | undefined
+            if (typeof pageInfo?.total === 'number' && typeof pageInfo?.analyzed === 'number') {
+              pages = { total: pageInfo.total, analyzed: pageInfo.analyzed }
+            }
             const supplier = extracted.supplier as Record<string, unknown> | undefined
             const invoice = extracted.invoice as Record<string, unknown> | undefined
             const totals = extracted.totals as Record<string, unknown> | undefined
@@ -13551,9 +13571,22 @@ export const tools: McpTool[] = [
             paymentReference = (invoice?.paymentReference as string) || null
           }
 
+          // Original file name, same embed gnubok_list_inbox_items uses: the
+          // archive file name was a better date signal than the OCR'd
+          // invoice_date in every case one reporter checked (feedback seq
+          // 265062), and without it the agent must fetch each document just
+          // to learn what it is.
+          const attachment = item.document_attachments as
+            | { file_name?: string | null }
+            | Array<{ file_name?: string | null }>
+            | null
+            | undefined
+          const fileName = (Array.isArray(attachment) ? attachment[0]?.file_name : attachment?.file_name) ?? null
+
           return {
             inbox_item_id: item.id,
             document_id: item.document_id,
+            file_name: fileName,
             source: item.source,
             created_at: item.created_at,
             email_from: item.email_from,
@@ -13565,6 +13598,7 @@ export const tools: McpTool[] = [
             currency,
             invoice_date: invoiceDate,
             payment_reference: paymentReference,
+            pages,
           }
         })