Problem
The eval identifies five categories of module-level state distributed across the src/ directory: the PineconeClient class in pinecone-client.ts (605 lines) managing lazy initialization of two index connections for dense and sparse search (eval §5.2), the URL generator registry as a module-private Map<string, UrlGenerator> in url-generation.ts (eval §5.4), plus config, suggestion flow gate state, and namespace caching in the 10 src/server/ helpers (eval §2). This module-level state makes the server's internal configuration an inescapable part of its public API contract — the eval's closed extension surface finding (T23) notes that adding new URL patterns, tools, or response transformations "requires source modification" because extension points are not exported (eval §5.4). The eval rates the project's bus factor at 1 (eval §5.3), meaning all implicit singleton initialization order and inter-dependency knowledge lives in a single maintainer's head with no automated verification at the interface layer. Encapsulating these singletons into a ServerContext instance is the prerequisite for the eval's recommended decomposition of pinecone-client.ts into pinecone-search.ts, result-merger.ts, and reranker.ts (eval §5.2), and for exposing the URL generator registry as a supported extension point.
Acceptance Criteria
Implementation Notes
- This is the BEGIN of a multi-week refactor (8pt starts, 8pt completes in horizon)
- Jonathan's Week 4 PR A already introduced core/alliance boundary
- Pattern:
ServerContext holds client, config, cache; tool handlers receive it as first arg
- The backward-compat layer ensures no breaking change this week
References
Problem
The eval identifies five categories of module-level state distributed across the
src/directory: thePineconeClientclass inpinecone-client.ts(605 lines) managing lazy initialization of two index connections for dense and sparse search (eval §5.2), the URL generator registry as a module-privateMap<string, UrlGenerator>inurl-generation.ts(eval §5.4), plus config, suggestion flow gate state, and namespace caching in the 10src/server/helpers (eval §2). This module-level state makes the server's internal configuration an inescapable part of its public API contract — the eval's closed extension surface finding (T23) notes that adding new URL patterns, tools, or response transformations "requires source modification" because extension points are not exported (eval §5.4). The eval rates the project's bus factor at 1 (eval §5.3), meaning all implicit singleton initialization order and inter-dependency knowledge lives in a single maintainer's head with no automated verification at the interface layer. Encapsulating these singletons into aServerContextinstance is the prerequisite for the eval's recommended decomposition ofpinecone-client.tsintopinecone-search.ts,result-merger.ts, andreranker.ts(eval §5.2), and for exposing the URL generator registry as a supported extension point.Acceptance Criteria
ServerContextclass encapsulating all five singletonscreateServer(config)returning aServerContextinstanceImplementation Notes
ServerContextholds client, config, cache; tool handlers receive it as first argReferences