@kbzowski/mcp-inbox 0.5.1 → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -0
- package/dist/app.js +1559 -426
- package/dist/cache/backfill.d.ts +35 -0
- package/dist/cache/db.d.ts +7 -2
- package/dist/cache/indexer.d.ts +34 -0
- package/dist/cache/queries.d.ts +18 -0
- package/dist/cache/schema.d.ts +117 -0
- package/dist/cache/vectors.d.ts +77 -0
- package/dist/config/env.d.ts +38 -0
- package/dist/embeddings/chunk.d.ts +3 -0
- package/dist/embeddings/client.d.ts +11 -0
- package/dist/errors/types.d.ts +3 -1
- package/dist/formatters/markdown.d.ts +23 -0
- package/dist/http.d.ts +14 -0
- package/dist/imap/body-text.d.ts +47 -0
- package/dist/migrations/20260804153609_illegal_scream/migration.sql +8 -0
- package/dist/migrations/20260804153609_illegal_scream/snapshot.json +383 -0
- package/dist/tools/define-tool.d.ts +4 -0
- package/dist/tools/emails/index-folder.d.ts +10 -0
- package/dist/tools/emails/semantic-search.d.ts +13 -0
- package/dist/tools/emails/shared.d.ts +14 -0
- package/dist/utils/logger.d.ts +8 -5
- package/package.json +20 -20
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import type { CacheDb } from './db';
|
|
2
|
+
import type { TextBodies } from '../imap/body-text';
|
|
3
|
+
import type { EmbeddingsConfig } from '../config/env';
|
|
4
|
+
/**
|
|
5
|
+
* Supplies plain body text for a batch of UIDs. Injected rather than imported
|
|
6
|
+
* so this module never depends on ImapFlow, and so the caller owns the mailbox
|
|
7
|
+
* lock - which must never be held across an embeddings round-trip.
|
|
8
|
+
*/
|
|
9
|
+
export type BodyTextFetcher = (uids: readonly number[]) => Promise<TextBodies>;
|
|
10
|
+
/**
|
|
11
|
+
* Cached messages still awaiting embedding across the given folders. Lives
|
|
12
|
+
* here rather than in vectors.ts, which must not import queries.ts - that
|
|
13
|
+
* module already imports vectors.ts for its delete hooks.
|
|
14
|
+
*/
|
|
15
|
+
export declare function pendingForFolders(db: CacheDb, folders: readonly string[]): number;
|
|
16
|
+
export interface BackfillResult {
|
|
17
|
+
embedded: number;
|
|
18
|
+
remaining: number;
|
|
19
|
+
/** Messages that contributed body chunks, not just an envelope. */
|
|
20
|
+
bodiesIndexed: number;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Embed cached envelopes outside the folder's indexed UID range, newest
|
|
24
|
+
* first, up to `budget` messages.
|
|
25
|
+
*
|
|
26
|
+
* Nothing writes vectors on the sync path - a network round-trip there would
|
|
27
|
+
* block every list/search call. Instead the indexed set is the contiguous
|
|
28
|
+
* range [fromUid, toUid] and this walks outward from it, so an interrupted
|
|
29
|
+
* run is resumed by simply calling again.
|
|
30
|
+
*
|
|
31
|
+
* ponytail: new mail becomes searchable only once a call does this work,
|
|
32
|
+
* so a search can lag one invocation behind. If that ever matters, drive
|
|
33
|
+
* backfillFolder from a setInterval over vec_index_state rows.
|
|
34
|
+
*/
|
|
35
|
+
export declare function backfillFolder(db: CacheDb, folder: string, cfg: EmbeddingsConfig, budget: number, direction: 'newer' | 'both', now: () => number, fetchBodies?: BodyTextFetcher): Promise<BackfillResult>;
|
package/dist/cache/db.d.ts
CHANGED
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import { drizzle } from 'drizzle-orm/node-sqlite';
|
|
2
|
-
import * as schema from './schema';
|
|
3
2
|
/**
|
|
4
3
|
* Default migrations folder resolved relative to this module.
|
|
5
4
|
*
|
|
@@ -8,9 +7,15 @@ import * as schema from './schema';
|
|
|
8
7
|
* copies the migrations there so the shipped tarball is self-contained)
|
|
9
8
|
*/
|
|
10
9
|
export declare const DEFAULT_MIGRATIONS_FOLDER: string;
|
|
11
|
-
export type CacheDb = ReturnType<typeof drizzle
|
|
10
|
+
export type CacheDb = ReturnType<typeof drizzle>;
|
|
12
11
|
export interface CacheHandle {
|
|
13
12
|
db: CacheDb;
|
|
13
|
+
/**
|
|
14
|
+
* Whether the sqlite-vec extension loaded. False on platforms with no
|
|
15
|
+
* prebuilt binary (win32-arm64, Alpine/musl); the semantic-search tools
|
|
16
|
+
* refuse to run and every other tool is unaffected.
|
|
17
|
+
*/
|
|
18
|
+
vectorsAvailable: boolean;
|
|
14
19
|
/** Release the underlying SQLite connection. Safe to call more than once. */
|
|
15
20
|
close: () => void;
|
|
16
21
|
}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import type { CacheDb } from './db';
|
|
2
|
+
import type { ImapClient } from '../imap/client';
|
|
3
|
+
import type { EmbeddingsConfig } from '../config/env';
|
|
4
|
+
export interface IndexSweeperOptions {
|
|
5
|
+
db: CacheDb;
|
|
6
|
+
imap: ImapClient;
|
|
7
|
+
cfg: EmbeddingsConfig;
|
|
8
|
+
intervalMs: number;
|
|
9
|
+
/** Messages embedded per tick, across all folders. */
|
|
10
|
+
budgetPerTick: number;
|
|
11
|
+
now: () => number;
|
|
12
|
+
}
|
|
13
|
+
export interface SweepResult {
|
|
14
|
+
folders: number;
|
|
15
|
+
embedded: number;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Keeps every opted-in folder's vector index current in the background.
|
|
19
|
+
*
|
|
20
|
+
* Without this, a folder is only topped up when someone searches it, so
|
|
21
|
+
* folders you rarely search drift silently out of date. Search itself stays a
|
|
22
|
+
* pure reader: freshness has exactly one owner.
|
|
23
|
+
*/
|
|
24
|
+
export declare class IndexSweeper {
|
|
25
|
+
#private;
|
|
26
|
+
constructor(opts: IndexSweeperOptions);
|
|
27
|
+
start(): void;
|
|
28
|
+
stop(): void;
|
|
29
|
+
/**
|
|
30
|
+
* One pass over the indexed folders. Never rejects: this runs detached from
|
|
31
|
+
* any request, so an escaping error would be an unhandled rejection.
|
|
32
|
+
*/
|
|
33
|
+
sweepOnce(): Promise<SweepResult>;
|
|
34
|
+
}
|
package/dist/cache/queries.d.ts
CHANGED
|
@@ -45,6 +45,24 @@ export interface ListEmailsOptions {
|
|
|
45
45
|
*/
|
|
46
46
|
export declare function listEmailsByFolder(db: CacheDb, folder: string, opts?: ListEmailsOptions): Email[];
|
|
47
47
|
export declare function countEmailsInFolder(db: CacheDb, folder: string, opts?: ListEmailsOptions): number;
|
|
48
|
+
export interface IndexCandidateOptions {
|
|
49
|
+
aboveUid?: number;
|
|
50
|
+
belowUid?: number;
|
|
51
|
+
limit: number;
|
|
52
|
+
order: 'asc' | 'desc';
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Cached envelopes on one side of the embedded UID range, oldest- or
|
|
56
|
+
* newest-first. Drives the semantic index backfill, which walks outward
|
|
57
|
+
* from the contiguous range recorded in `vec_index_state`.
|
|
58
|
+
*/
|
|
59
|
+
export declare function listIndexCandidates(db: CacheDb, folder: string, opts: IndexCandidateOptions): Email[];
|
|
60
|
+
/**
|
|
61
|
+
* How many cached messages fall outside the embedded range. `fromUid === 0
|
|
62
|
+
* && toUid === 0` means nothing is embedded yet - UIDs start at 1, so zero
|
|
63
|
+
* is a safe empty sentinel.
|
|
64
|
+
*/
|
|
65
|
+
export declare function countEmailsOutsideUidRange(db: CacheDb, folder: string, fromUid: number, toUid: number): number;
|
|
48
66
|
/**
|
|
49
67
|
* Return every cached UID for a folder. Used by the sync reconciliation
|
|
50
68
|
* path to detect ghost entries (UIDs we have locally that are gone on
|
package/dist/cache/schema.d.ts
CHANGED
|
@@ -132,6 +132,7 @@ export declare const folders: import("drizzle-orm/sqlite-core").SQLiteTableWithC
|
|
|
132
132
|
}, {}>;
|
|
133
133
|
};
|
|
134
134
|
dialect: 'sqlite';
|
|
135
|
+
isAlias: false;
|
|
135
136
|
}>;
|
|
136
137
|
/** Metadata only - attachment bytes are never persisted. */
|
|
137
138
|
export interface AttachmentInfo {
|
|
@@ -422,8 +423,124 @@ export declare const emails: import("drizzle-orm/sqlite-core").SQLiteTableWithCo
|
|
|
422
423
|
}, {}>;
|
|
423
424
|
};
|
|
424
425
|
dialect: 'sqlite';
|
|
426
|
+
isAlias: false;
|
|
427
|
+
}>;
|
|
428
|
+
/**
|
|
429
|
+
* Which folders are opted in to semantic search, and how much of each is
|
|
430
|
+
* embedded. IMAP UIDs increase monotonically within a UIDVALIDITY, so the
|
|
431
|
+
* indexed set is always the contiguous range [fromUid, toUid] - which means
|
|
432
|
+
* "what still needs embedding" is derivable from these two integers plus a
|
|
433
|
+
* query over `emails`, without ever reading back from the vec0 table.
|
|
434
|
+
*
|
|
435
|
+
* `model`/`dims` are recorded per folder because the vec0 table bakes its
|
|
436
|
+
* dimensionality in at creation: a change to either forces a rebuild.
|
|
437
|
+
*/
|
|
438
|
+
export declare const vecIndexState: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
|
|
439
|
+
name: "vec_index_state";
|
|
440
|
+
schema: undefined;
|
|
441
|
+
columns: {
|
|
442
|
+
folder: import("drizzle-orm/sqlite-core").SQLiteColumn<{
|
|
443
|
+
name: string;
|
|
444
|
+
tableName: "vec_index_state";
|
|
445
|
+
dataType: "string";
|
|
446
|
+
data: string;
|
|
447
|
+
driverParam: string;
|
|
448
|
+
notNull: true;
|
|
449
|
+
hasDefault: false;
|
|
450
|
+
isPrimaryKey: true;
|
|
451
|
+
isAutoincrement: false;
|
|
452
|
+
hasRuntimeDefault: false;
|
|
453
|
+
enumValues: [string, ...string[]];
|
|
454
|
+
baseColumn: never;
|
|
455
|
+
identity: undefined;
|
|
456
|
+
generated: undefined;
|
|
457
|
+
}, {}>;
|
|
458
|
+
model: import("drizzle-orm/sqlite-core").SQLiteColumn<{
|
|
459
|
+
name: string;
|
|
460
|
+
tableName: "vec_index_state";
|
|
461
|
+
dataType: "string";
|
|
462
|
+
data: string;
|
|
463
|
+
driverParam: string;
|
|
464
|
+
notNull: true;
|
|
465
|
+
hasDefault: false;
|
|
466
|
+
isPrimaryKey: false;
|
|
467
|
+
isAutoincrement: false;
|
|
468
|
+
hasRuntimeDefault: false;
|
|
469
|
+
enumValues: [string, ...string[]];
|
|
470
|
+
baseColumn: never;
|
|
471
|
+
identity: undefined;
|
|
472
|
+
generated: undefined;
|
|
473
|
+
}, {}>;
|
|
474
|
+
dims: import("drizzle-orm/sqlite-core").SQLiteColumn<{
|
|
475
|
+
name: string;
|
|
476
|
+
tableName: "vec_index_state";
|
|
477
|
+
dataType: "number int53";
|
|
478
|
+
data: number;
|
|
479
|
+
driverParam: number;
|
|
480
|
+
notNull: true;
|
|
481
|
+
hasDefault: false;
|
|
482
|
+
isPrimaryKey: false;
|
|
483
|
+
isAutoincrement: false;
|
|
484
|
+
hasRuntimeDefault: false;
|
|
485
|
+
enumValues: undefined;
|
|
486
|
+
baseColumn: never;
|
|
487
|
+
identity: undefined;
|
|
488
|
+
generated: undefined;
|
|
489
|
+
}, {}>;
|
|
490
|
+
fromUid: import("drizzle-orm/sqlite-core").SQLiteColumn<{
|
|
491
|
+
name: string;
|
|
492
|
+
tableName: "vec_index_state";
|
|
493
|
+
dataType: "number int53";
|
|
494
|
+
data: number;
|
|
495
|
+
driverParam: number;
|
|
496
|
+
notNull: true;
|
|
497
|
+
hasDefault: false;
|
|
498
|
+
isPrimaryKey: false;
|
|
499
|
+
isAutoincrement: false;
|
|
500
|
+
hasRuntimeDefault: false;
|
|
501
|
+
enumValues: undefined;
|
|
502
|
+
baseColumn: never;
|
|
503
|
+
identity: undefined;
|
|
504
|
+
generated: undefined;
|
|
505
|
+
}, {}>;
|
|
506
|
+
toUid: import("drizzle-orm/sqlite-core").SQLiteColumn<{
|
|
507
|
+
name: string;
|
|
508
|
+
tableName: "vec_index_state";
|
|
509
|
+
dataType: "number int53";
|
|
510
|
+
data: number;
|
|
511
|
+
driverParam: number;
|
|
512
|
+
notNull: true;
|
|
513
|
+
hasDefault: false;
|
|
514
|
+
isPrimaryKey: false;
|
|
515
|
+
isAutoincrement: false;
|
|
516
|
+
hasRuntimeDefault: false;
|
|
517
|
+
enumValues: undefined;
|
|
518
|
+
baseColumn: never;
|
|
519
|
+
identity: undefined;
|
|
520
|
+
generated: undefined;
|
|
521
|
+
}, {}>;
|
|
522
|
+
indexedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
|
|
523
|
+
name: string;
|
|
524
|
+
tableName: "vec_index_state";
|
|
525
|
+
dataType: "number int53";
|
|
526
|
+
data: number;
|
|
527
|
+
driverParam: number;
|
|
528
|
+
notNull: true;
|
|
529
|
+
hasDefault: false;
|
|
530
|
+
isPrimaryKey: false;
|
|
531
|
+
isAutoincrement: false;
|
|
532
|
+
hasRuntimeDefault: false;
|
|
533
|
+
enumValues: undefined;
|
|
534
|
+
baseColumn: never;
|
|
535
|
+
identity: undefined;
|
|
536
|
+
generated: undefined;
|
|
537
|
+
}, {}>;
|
|
538
|
+
};
|
|
539
|
+
dialect: 'sqlite';
|
|
540
|
+
isAlias: false;
|
|
425
541
|
}>;
|
|
426
542
|
export type Folder = typeof folders.$inferSelect;
|
|
427
543
|
export type FolderInsert = typeof folders.$inferInsert;
|
|
428
544
|
export type Email = typeof emails.$inferSelect;
|
|
429
545
|
export type EmailInsert = typeof emails.$inferInsert;
|
|
546
|
+
export type VecIndexState = typeof vecIndexState.$inferSelect;
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import type { CacheDb } from './db';
|
|
2
|
+
import { type VecIndexState } from './schema';
|
|
3
|
+
/** Envelope vectors. Body chunks take part 1..n. */
|
|
4
|
+
declare const ENVELOPE_PART = 0;
|
|
5
|
+
/** What gets stored in `vec_index_state.model`; tool output shows plain `cfg.model`. */
|
|
6
|
+
export declare function indexModelId(model: string): string;
|
|
7
|
+
export interface VectorRow {
|
|
8
|
+
uid: number;
|
|
9
|
+
part: number;
|
|
10
|
+
date: number | null;
|
|
11
|
+
vector: Float32Array;
|
|
12
|
+
}
|
|
13
|
+
export interface KnnHit {
|
|
14
|
+
folder: string;
|
|
15
|
+
uid: number;
|
|
16
|
+
distance: number;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Create the vec0 table if absent, rebuilding it when the configured model
|
|
20
|
+
* or dimensionality no longer matches what is indexed.
|
|
21
|
+
*
|
|
22
|
+
* This never runs as a migration: `CREATE VIRTUAL TABLE ... USING vec0`
|
|
23
|
+
* throws where the extension is unavailable, and a failing migration is a
|
|
24
|
+
* fatal startup error. Creating it lazily keeps those platforms bootable.
|
|
25
|
+
*/
|
|
26
|
+
export declare function ensureVecTable(db: CacheDb, model: string, dims: number): void;
|
|
27
|
+
/** Folders opted in to semantic search, in a stable order. */
|
|
28
|
+
export declare function indexedFolders(db: CacheDb): string[];
|
|
29
|
+
export declare function getVecState(db: CacheDb, folder: string): VecIndexState | undefined;
|
|
30
|
+
export declare function upsertVecState(db: CacheDb, row: VecIndexState): void;
|
|
31
|
+
/**
|
|
32
|
+
* vec0 has no unique constraint, so a plain INSERT would duplicate a message
|
|
33
|
+
* whenever the same range is embedded twice - after a crash between writing
|
|
34
|
+
* vectors and advancing the watermark, or when two clients index the same
|
|
35
|
+
* cache concurrently.
|
|
36
|
+
*
|
|
37
|
+
* The delete is per uid rather than per (uid, part): re-indexing a message
|
|
38
|
+
* into fewer chunks than last time must not leave the surplus parts behind,
|
|
39
|
+
* pointing at text the message no longer contains.
|
|
40
|
+
*/
|
|
41
|
+
export declare function insertVectors(db: CacheDb, folder: string, rows: readonly VectorRow[]): void;
|
|
42
|
+
/**
|
|
43
|
+
* Both deletes are best-effort cleanup invoked from the cache-invalidation
|
|
44
|
+
* path. A missing vec0 table (extension unavailable) or a failed delete must
|
|
45
|
+
* never fail the sync that triggered it, so they no-op when the folder was
|
|
46
|
+
* never indexed and warn rather than throw otherwise.
|
|
47
|
+
*/
|
|
48
|
+
export declare function deleteVectorsByFolder(db: CacheDb, folder: string): void;
|
|
49
|
+
export declare function deleteVectorsByUids(db: CacheDb, folder: string, uids: readonly number[]): void;
|
|
50
|
+
/**
|
|
51
|
+
* `k = ?` is mandatory for a vec0 KNN query - a bare LIMIT is not equivalent.
|
|
52
|
+
* The CTE is MATERIALIZED so the planner cannot inline the scan into an outer
|
|
53
|
+
* query and lose that constraint. Folder and date are applied inside the scan,
|
|
54
|
+
* so the k results come back already filtered rather than filtered afterwards.
|
|
55
|
+
*
|
|
56
|
+
* Grouping happens outside the CTE, leaving `k` untouched. A message is ranked
|
|
57
|
+
* by its single best chunk, not by an average: one sharply relevant paragraph
|
|
58
|
+
* in a long mail should beat a uniformly vague short one.
|
|
59
|
+
*
|
|
60
|
+
* Omitting `folders` searches every indexed folder in one pass - vec0 scans
|
|
61
|
+
* all partitions when the partition key is unconstrained.
|
|
62
|
+
*/
|
|
63
|
+
export declare function knnSearch(db: CacheDb, query: Float32Array, k: number, opts?: {
|
|
64
|
+
folders?: readonly string[];
|
|
65
|
+
sinceMs?: number;
|
|
66
|
+
beforeMs?: number;
|
|
67
|
+
}): KnnHit[];
|
|
68
|
+
/**
|
|
69
|
+
* Drop vectors whose cached envelope is gone. The delete hooks in queries.ts
|
|
70
|
+
* cover every in-process removal, so this only catches what they could not:
|
|
71
|
+
* rows written by a build predating those hooks, or by another client holding
|
|
72
|
+
* the same cache file. Returns how many were reclaimed.
|
|
73
|
+
*/
|
|
74
|
+
export declare function pruneOrphanedVectors(db: CacheDb, folder: string): number;
|
|
75
|
+
/** Messages, not rows - a message contributes an envelope plus its body chunks. */
|
|
76
|
+
export declare function countVectors(db: CacheDb, folder: string): number;
|
|
77
|
+
export { ENVELOPE_PART };
|
package/dist/config/env.d.ts
CHANGED
|
@@ -24,11 +24,22 @@ declare const EnvSchema: z.ZodPipe<z.ZodObject<{
|
|
|
24
24
|
IMAP_CACHE_DIR: z.ZodOptional<z.ZodString>;
|
|
25
25
|
IMAP_CACHE_DEFAULT_STALENESS_SEC: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
|
|
26
26
|
IMAP_CACHE_BODY_RETAIN_DAYS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
|
|
27
|
+
IMAP_EMBEDDINGS_BASE_URL: z.ZodOptional<z.ZodURL>;
|
|
28
|
+
IMAP_EMBEDDINGS_API_KEY: z.ZodOptional<z.ZodString>;
|
|
29
|
+
IMAP_EMBEDDINGS_MODEL: z.ZodDefault<z.ZodString>;
|
|
30
|
+
IMAP_EMBEDDINGS_DIMS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
|
|
31
|
+
IMAP_EMBEDDINGS_BATCH_SIZE: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
|
|
32
|
+
IMAP_EMBEDDINGS_TIMEOUT_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
|
|
33
|
+
IMAP_EMBEDDINGS_SWEEP_MINUTES: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
|
|
34
|
+
IMAP_EMBEDDINGS_SWEEP_BATCH: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
|
|
27
35
|
IMAP_IDLE_ENABLED: z.ZodDefault<z.ZodPipe<z.ZodEnum<{
|
|
28
36
|
false: "false";
|
|
29
37
|
true: "true";
|
|
30
38
|
}>, z.ZodTransform<boolean, "false" | "true">>>;
|
|
31
39
|
IMAP_IDLE_FOLDERS: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>>;
|
|
40
|
+
MCP_HTTP_PORT: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
|
|
41
|
+
MCP_HTTP_HOST: z.ZodDefault<z.ZodString>;
|
|
42
|
+
MCP_AUTH_TOKEN: z.ZodOptional<z.ZodString>;
|
|
32
43
|
DEBUG: z.ZodOptional<z.ZodString>;
|
|
33
44
|
}, z.core.$strip>, z.ZodTransform<{
|
|
34
45
|
imap: {
|
|
@@ -52,10 +63,25 @@ declare const EnvSchema: z.ZodPipe<z.ZodObject<{
|
|
|
52
63
|
defaultStalenessSec: number;
|
|
53
64
|
bodyRetainDays: number;
|
|
54
65
|
};
|
|
66
|
+
embeddings: {
|
|
67
|
+
baseUrl: string;
|
|
68
|
+
apiKey?: string;
|
|
69
|
+
model: string;
|
|
70
|
+
dims: number;
|
|
71
|
+
batchSize: number;
|
|
72
|
+
timeoutMs: number;
|
|
73
|
+
sweepMinutes: number;
|
|
74
|
+
sweepBatch: number;
|
|
75
|
+
} | null;
|
|
55
76
|
idle: {
|
|
56
77
|
enabled: boolean;
|
|
57
78
|
folders: string[];
|
|
58
79
|
};
|
|
80
|
+
http: {
|
|
81
|
+
port: number;
|
|
82
|
+
host: string;
|
|
83
|
+
token: string;
|
|
84
|
+
} | null;
|
|
59
85
|
debug: string;
|
|
60
86
|
}, {
|
|
61
87
|
IMAP_USER: string;
|
|
@@ -73,11 +99,23 @@ declare const EnvSchema: z.ZodPipe<z.ZodObject<{
|
|
|
73
99
|
IMAP_CACHE_DIR?: string | undefined;
|
|
74
100
|
IMAP_CACHE_DEFAULT_STALENESS_SEC: number;
|
|
75
101
|
IMAP_CACHE_BODY_RETAIN_DAYS: number;
|
|
102
|
+
IMAP_EMBEDDINGS_BASE_URL?: string | undefined;
|
|
103
|
+
IMAP_EMBEDDINGS_API_KEY?: string | undefined;
|
|
104
|
+
IMAP_EMBEDDINGS_MODEL: string;
|
|
105
|
+
IMAP_EMBEDDINGS_DIMS: number;
|
|
106
|
+
IMAP_EMBEDDINGS_BATCH_SIZE: number;
|
|
107
|
+
IMAP_EMBEDDINGS_TIMEOUT_MS: number;
|
|
108
|
+
IMAP_EMBEDDINGS_SWEEP_MINUTES: number;
|
|
109
|
+
IMAP_EMBEDDINGS_SWEEP_BATCH: number;
|
|
76
110
|
IMAP_IDLE_ENABLED: boolean;
|
|
77
111
|
IMAP_IDLE_FOLDERS: string[];
|
|
112
|
+
MCP_HTTP_PORT?: number | undefined;
|
|
113
|
+
MCP_HTTP_HOST: string;
|
|
114
|
+
MCP_AUTH_TOKEN?: string | undefined;
|
|
78
115
|
DEBUG?: string | undefined;
|
|
79
116
|
}>>;
|
|
80
117
|
export type AppConfig = z.infer<typeof EnvSchema>;
|
|
118
|
+
export type EmbeddingsConfig = NonNullable<AppConfig['embeddings']>;
|
|
81
119
|
/**
|
|
82
120
|
* Parses process.env and returns a validated AppConfig.
|
|
83
121
|
* Throws a readable error on invalid/missing configuration;
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { EmbeddingsConfig } from '../config/env';
|
|
2
|
+
/**
|
|
3
|
+
* The exact text projected into a vector. Exported so the indexer and any
|
|
4
|
+
* future re-indexer provably embed the same thing - a drift here silently
|
|
5
|
+
* degrades recall instead of failing.
|
|
6
|
+
*/
|
|
7
|
+
export declare function envelopeText(email: {
|
|
8
|
+
subject: string | null;
|
|
9
|
+
fromAddr: string | null;
|
|
10
|
+
}): string;
|
|
11
|
+
export declare function embedTexts(texts: readonly string[], cfg: EmbeddingsConfig): Promise<Float32Array[]>;
|
package/dist/errors/types.d.ts
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
* - `cause` is propagated via `Error`'s ES2022 `{ cause }` options object and
|
|
9
9
|
* inherited from the base class - no need to redeclare on subclasses.
|
|
10
10
|
*/
|
|
11
|
-
export type ErrorCode = 'CONFIG_INVALID' | 'IMAP_AUTH_FAILED' | 'IMAP_HOST_UNREACHABLE' | 'IMAP_CONNECTION_REFUSED' | 'IMAP_TIMEOUT' | 'IMAP_FOLDER_NOT_FOUND' | 'IMAP_MESSAGE_NOT_FOUND' | 'IMAP_UIDVALIDITY_CHANGED' | 'IMAP_UNKNOWN' | 'SMTP_AUTH_FAILED' | 'SMTP_SEND_FAILED' | 'SMTP_UNKNOWN' | 'CACHE_IO_FAILED' | 'CACHE_SCHEMA_MISMATCH' | 'ATTACHMENT_TOO_LARGE' | 'ATTACHMENT_NOT_FOUND' | 'TOOL_INVALID_INPUT' | 'INTERNAL';
|
|
11
|
+
export type ErrorCode = 'CONFIG_INVALID' | 'IMAP_AUTH_FAILED' | 'IMAP_HOST_UNREACHABLE' | 'IMAP_CONNECTION_REFUSED' | 'IMAP_TIMEOUT' | 'IMAP_FOLDER_NOT_FOUND' | 'IMAP_MESSAGE_NOT_FOUND' | 'IMAP_UIDVALIDITY_CHANGED' | 'IMAP_UNKNOWN' | 'SMTP_AUTH_FAILED' | 'SMTP_SEND_FAILED' | 'SMTP_UNKNOWN' | 'CACHE_IO_FAILED' | 'CACHE_SCHEMA_MISMATCH' | 'ATTACHMENT_TOO_LARGE' | 'ATTACHMENT_NOT_FOUND' | 'EMBEDDING_DISABLED' | 'EMBEDDING_INDEX_UNAVAILABLE' | 'EMBEDDING_NOT_INDEXED' | 'EMBEDDING_AUTH_FAILED' | 'EMBEDDING_UNREACHABLE' | 'EMBEDDING_DIM_MISMATCH' | 'TOOL_INVALID_INPUT' | 'INTERNAL';
|
|
12
12
|
export declare class McpInboxError extends Error {
|
|
13
13
|
readonly code: ErrorCode;
|
|
14
14
|
readonly userMessage: string;
|
|
@@ -20,6 +20,8 @@ export declare class SmtpError extends McpInboxError {
|
|
|
20
20
|
}
|
|
21
21
|
export declare class CacheError extends McpInboxError {
|
|
22
22
|
}
|
|
23
|
+
export declare class EmbeddingError extends McpInboxError {
|
|
24
|
+
}
|
|
23
25
|
export declare class ToolInputError extends McpInboxError {
|
|
24
26
|
constructor(userMessage: string, cause?: unknown);
|
|
25
27
|
}
|
|
@@ -6,6 +6,29 @@ export interface FolderSummary {
|
|
|
6
6
|
flags?: string[];
|
|
7
7
|
}
|
|
8
8
|
export declare function formatFoldersMarkdown(folders: readonly FolderSummary[]): string;
|
|
9
|
+
export interface RankedEmailSummary {
|
|
10
|
+
uid: number;
|
|
11
|
+
folder: string;
|
|
12
|
+
subject: string | null;
|
|
13
|
+
from: string | null;
|
|
14
|
+
date: string | null;
|
|
15
|
+
unseen: boolean;
|
|
16
|
+
has_attachments: boolean;
|
|
17
|
+
score: number;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Semantic-search results, scores included.
|
|
21
|
+
*
|
|
22
|
+
* The score column is the point: this tool never filters, so the caller has
|
|
23
|
+
* to judge relevance itself, and a ranked list without scores gives it
|
|
24
|
+
* nothing to judge with. The trailing note exists because the absolute
|
|
25
|
+
* values mislead - the model rates even strong matches around 0.4-0.6, so a
|
|
26
|
+
* naive reader would discard good hits against an intuitive threshold.
|
|
27
|
+
*
|
|
28
|
+
* The folder column is not decoration: UIDs are folder-scoped, so a result
|
|
29
|
+
* without its folder cannot be passed to any follow-up tool.
|
|
30
|
+
*/
|
|
31
|
+
export declare function formatSemanticResultsMarkdown(rows: readonly RankedEmailSummary[], pendingIndex: number): string;
|
|
9
32
|
/**
|
|
10
33
|
* Compact one-email-per-row summary. Unseen messages are bolded so the
|
|
11
34
|
* agent can scan inbox status at a glance.
|
package/dist/http.d.ts
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { type Server as HttpServer } from 'node:http';
|
|
2
|
+
import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
|
3
|
+
export interface HttpConfig {
|
|
4
|
+
port: number;
|
|
5
|
+
host: string;
|
|
6
|
+
token: string;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* Stateless streamable HTTP on POST /mcp. No sessions: every request gets
|
|
10
|
+
* its own Server + transport, so any number of clients can connect and
|
|
11
|
+
* there is no per-client state to leak. The tools never push server-initiated
|
|
12
|
+
* messages, so GET (SSE stream) is answered with 405.
|
|
13
|
+
*/
|
|
14
|
+
export declare function startHttpServer(cfg: HttpConfig, makeServer: () => Server): Promise<HttpServer>;
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import type { ImapFlow, MessageStructureObject } from 'imapflow';
|
|
2
|
+
import type { ImapClient } from './client';
|
|
3
|
+
export interface TextPart {
|
|
4
|
+
part: string;
|
|
5
|
+
charset: string;
|
|
6
|
+
encoding: string;
|
|
7
|
+
isHtml: boolean;
|
|
8
|
+
}
|
|
9
|
+
export interface TextBodies {
|
|
10
|
+
texts: Map<number, string>;
|
|
11
|
+
/** How many of the requested messages actually had a usable text part. */
|
|
12
|
+
expected: number;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Locate the message's readable text part.
|
|
16
|
+
*
|
|
17
|
+
* Only leaf `text/*` nodes qualify: on a real Dovecot mailbox the first child
|
|
18
|
+
* of a `multipart/mixed` is often a `multipart/alternative`, and fetching that
|
|
19
|
+
* container returns raw MIME with boundaries rather than prose.
|
|
20
|
+
*
|
|
21
|
+
* A root node carries no `part` id, in which case the body is part `1`.
|
|
22
|
+
* ImapFlow's own `download()` uses `TEXT` there, but GreenMail returns zero
|
|
23
|
+
* bytes for `TEXT` on a single-part message while both servers accept `1`.
|
|
24
|
+
*/
|
|
25
|
+
export declare function pickTextPart(structure: MessageStructureObject | undefined): TextPart | null;
|
|
26
|
+
export declare function decodeTextPart(raw: Buffer, part: TextPart, alreadyDecoded?: boolean): string;
|
|
27
|
+
/**
|
|
28
|
+
* Fetch the text part of many messages without pulling their attachments.
|
|
29
|
+
*
|
|
30
|
+
* Two passes because one FETCH command carries one part list for the whole UID
|
|
31
|
+
* set, and part ids differ per message. Each part group is isolated: a server
|
|
32
|
+
* that rejects one shape (GreenMail answers `NO` for a part id it has not got,
|
|
33
|
+
* which fails the whole command) must not cost us the other groups.
|
|
34
|
+
*/
|
|
35
|
+
export declare function fetchTextBodies(imap: ImapFlow, uids: readonly number[]): Promise<TextBodies>;
|
|
36
|
+
/**
|
|
37
|
+
* Wrap `fetchTextBodies` with connection and lock handling for the indexer.
|
|
38
|
+
*
|
|
39
|
+
* The lock is taken and released around the fetch alone, never across the
|
|
40
|
+
* embedding round-trips that follow: one connection serves every tool, so
|
|
41
|
+
* holding it for a full indexing run would stall the whole server.
|
|
42
|
+
*
|
|
43
|
+
* A failure yields `expected: 0`, which reads as "nothing to say about
|
|
44
|
+
* bodies" rather than "this server has none", so a transient connection
|
|
45
|
+
* error does not switch body indexing off for the rest of the run.
|
|
46
|
+
*/
|
|
47
|
+
export declare function bodyFetcherFor(client: ImapClient, folder: string): (uids: readonly number[]) => Promise<TextBodies>;
|