@mailwoman/mcp 10.0.0 → 10.2.0

package/README.md

@@ -16,7 +16,7 @@ An **MCP server** exposing [Mailwoman](https://mailwoman.ai)'s parse/geocode/POI
 | `mailwoman_filer_lookup`         | Reads the FCC filer identity crosswalk from a `filer.db` layer               | No                            |
 | `mailwoman_filer_family`         | Reads a corporate family's membership from a `filer.db` layer                | No                            |
 
-The four model-backed tools load the `en-US` weights and open a resolver on the first call that needs them, not at
+The four model-backed tools load the `en-US` weights and open a resolver on the first call that needs them rather than at
 startup. With neither `$MAILWOMAN_CANDIDATE_DB` nor a WOF distribution on the data root, that first call answers with
 the `mailwoman data pull candidate` fix instead of an internal resolver error.
 

package/cli/main.ts

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { filingLandscape, plausibilityCheck, type BDCDatabase } from "@mailwoman/bdc"
+import type { PipelineResult } from "@mailwoman/core"
+import { dataRootPath } from "@mailwoman/core/data-root"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
+import { readLayerManifest, type layerschemadatabase } from "@mailwoman/core/layers"
+import type { Resolver } from "@mailwoman/core/resolver"
+import { parseArguments } from "@mailwoman/core/scripting/arguments"
+import { familyRollup } from "@mailwoman/filer/family-rollup"
+import { filerLookup } from "@mailwoman/filer/filer-lookup"
+import { toFRN, type FRN } from "@mailwoman/filer/frn"
+import { NeuralAddressClassifier, type ScriptRoutedClassifier } from "@mailwoman/neural"
+import { getPOICategory } from "@mailwoman/poi-taxonomy"
+import { emitOverpassQL } from "@mailwoman/poi-taxonomy/overpass"
+import { createWOFResolver } from "@mailwoman/resolver"
+import { wofExtractPaths } from "@mailwoman/resolver-wof-sqlite/paths"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { createRuntimePipeline } from "mailwoman"
+import { geocodeAddress, USStateDatabaseProvider } from "mailwoman/geocode"
+import { buildNoGazetteerMessage, createResolverBackend, resolveCandidateDBPath } from "mailwoman/resolver-backend"
+
+import {
+	assertBDCDatabaseExists,
+	assertFilerDatabaseExists,
+	openBDCDatabaseIfPresent,
+	openFilerDatabaseIfPresent,
+	openPlausibilityPOIDeps,
+} from "#layer-guards"
+import { createMCPServer } from "#server"
+import type { MCPToolDeps } from "#tools"
+
+const { values } = parseArguments({
+	options: {
+		"poi-db": { type: "string" },
+	},
+	allowPositionals: true,
+})
+
+const poiDatabasePath = values["poi-db"] ?? null
+
+let corePromise:
+	| Promise<{
+			classifier: ScriptRoutedClassifier<NeuralAddressClassifier>
+			resolver: Resolver
+			databases: USStateDatabaseProvider
+	  }>
+	| undefined
+
+const CORE_BACKED_TOOLS = "mailwoman_parse, mailwoman_geocode, mailwoman_poi_search, mailwoman_overpass_export"
+
+const CORE_FREE_TOOLS =
+	"mailwoman_layer_manifest, mailwoman_bdc_filing_landscape, mailwoman_filer_lookup, mailwoman_filer_family"
+
+function loadCore(): Promise<{
+	classifier: ScriptRoutedClassifier
+	resolver: Resolver
+	/**
+	 * The concrete US provider, because `GeocodeDeps.databases` accepts a null state slug.
+	 */
+	databases: USStateDatabaseProvider
+}> {
+	corePromise ??= (async () => {
+		const resolverMod = await import("@mailwoman/resolver-wof-sqlite")
+		const wofPaths: string[] = []
+
+		for (const extractPath of wofExtractPaths()) {
+			if (await pathExists(extractPath)) {
+				wofPaths.push(extractPath)
+			}
+		}
+
+		const candidateDB = await resolveCandidateDBPath()
+
+		if (!candidateDB && !wofPaths.length) {
+			throw new Error(
+				`${buildNoGazetteerMessage({
+					dataRoot: dataRootPath(),
+					docsPath: "/docs/developers/how-to/use-the-mcp-server",
+				})}\n\n  Needs it: ${CORE_BACKED_TOOLS}\n  Works without it: ${CORE_FREE_TOOLS}`
+			)
+		}
+
+		const backend = await createResolverBackend(resolverMod, { wofPaths, candidateDB })
+		const resolver = createWOFResolver(backend)
+
+		let classifier: ScriptRoutedClassifier<NeuralAddressClassifier>
+
+		try {
+			classifier = await NeuralAddressClassifier.loadRoutedFromWeights({ locale: "en-US" })
+		} catch (error) {
+			throw new Error(
+				`✗ ${error instanceof Error ? error.message : String(error)}\n\n` +
+					`  Needs it: ${CORE_BACKED_TOOLS}\n  Works without it: ${CORE_FREE_TOOLS}`
+			)
+		}
+
+		const databases = await USStateDatabaseProvider.create(resolverMod, dataRootPath())
+
+		return { classifier, resolver, databases }
+	})()
+
+	return corePromise
+}
+
+type Pipeline = (raw: string) => Promise<PipelineResult>
+
+let plainPipeline: Pipeline | null = null
+
+const poiPipelines = new Map<string, Pipeline>()
+
+async function getPlainPipeline(): Promise<Pipeline> {
+	if (!plainPipeline) {
+		const { classifier, resolver } = await loadCore()
+
+		plainPipeline = createRuntimePipeline({ classifier, resolver })
+	}
+
+	return plainPipeline
+}
+
+async function getPoiPipeline(dbPath: string | null): Promise<Pipeline> {
+	const key = dbPath ?? ""
+	const cached = poiPipelines.get(key)
+
+	if (cached) return cached
+	const { classifier, resolver } = await loadCore()
+
+	const pipeline = createRuntimePipeline({
+		classifier,
+		resolver,
+		poiQueryKind: dbPath ? { poiDatabasePath: dbPath } : "extract",
+	})
+
+	poiPipelines.set(key, pipeline)
+
+	return pipeline
+}
+
+async function resolveGeocode(address: string) {
+	const { classifier, resolver, databases } = await loadCore()
+
+	return geocodeAddress(address, { classifier, resolver, databases: databases.for })
+}
+
+const deps: MCPToolDeps = {
+	async parse(text, opts) {
+		const pipeline = opts?.poi ? await getPoiPipeline(poiDatabasePath) : await getPlainPipeline()
+
+		return pipeline(text)
+	},
+
+	async geocode(text) {
+		return resolveGeocode(text)
+	},
+
+	async poiSearch(q) {
+		const pipeline = await getPoiPipeline(q.poiDatabasePath ?? poiDatabasePath)
+		const result = await pipeline(q.query)
+
+		return result.poiIntent ?? { type: "abstain", reason: "not_poi_shaped" }
+	},
+
+	async overpassExport(query) {
+		const pipeline = await getPoiPipeline(poiDatabasePath)
+		const result = await pipeline(query)
+		const poiIntent = result.poiIntent
+
+		if (!poiIntent || poiIntent.type !== "intent") {
+			const reason = poiIntent?.type === "abstain" ? `: ${poiIntent.reason}` : ""
+
+			throw new Error(
+				`mailwoman_overpass_export: query is not POI-shaped (${poiIntent?.type ?? "no poi intent"}${reason})`
+			)
+		}
+
+		const { subject } = poiIntent.intent
+
+		const osmTags =
+			subject.kind === "category"
+				? subject.categoryIDs.map((id) => getPOICategory(id)?.osmTag).filter((tag) => tag !== undefined)
+				: []
+
+		return emitOverpassQL(
+			poiIntent.intent,
+			subject.kind === "category" && osmTags.length === subject.categoryIDs.length ? { osmTags } : {}
+		)
+	},
+
+	async layerManifest(databasePath) {
+		using db = new DatabaseClient<layerschemadatabase>(databasePath, { readOnly: true })
+
+		const manifest = await readLayerManifest(db)
+
+		const coverage = await db
+			.selectFrom("layer_coverage")
+			.select((eb) => [
+				eb.fn.count<number>("h3_cell").as("surveyedCellCount"),
+				eb.fn.avg<number>("completeness").as("averageCompleteness"),
+				eb.fn.sum<number>("observed_rows").as("totalObservedRows"),
+			])
+			.executeTakeFirst()
+
+		return { manifest, coverage }
+	},
+
+	async bdcFilingLandscape(q) {
+		await assertBDCDatabaseExists("mailwoman_bdc_filing_landscape", q.databasePath)
+
+		using db = new DatabaseClient<BDCDatabase>(q.databasePath, { readOnly: true })
+
+		return await filingLandscape(db, { geoids: q.geoids, h3Cells: q.h3Cells })
+	},
+
+	async plausibilityCheck(q) {
+		const bdcDB = await openBDCDatabaseIfPresent(q.bdcDatabasePath)
+		const poi = await openPlausibilityPOIDeps(q.poiDatabasePath)
+
+		try {
+			return await plausibilityCheck(
+				{
+					address: q.address,
+					point: q.point,
+					geoid: q.geoid,
+					technologyCode: q.technologyCode,
+					claimedDownloadMbps: q.claimedDownloadMbps,
+				},
+				{ bdcDB, poi, geocode: resolveGeocode }
+			)
+		} finally {
+			bdcDB?.destroy()
+			poi?.schemadb.destroy()
+		}
+	},
+
+	async filerLookup(q) {
+		await assertFilerDatabaseExists("mailwoman_filer_lookup", q.databasePath)
+
+		using db = (await openFilerDatabaseIfPresent(q.databasePath))!
+
+		let frn: FRN | null = null
+
+		if (q.frn) {
+			const parsed = toFRN(q.frn)
+
+			if (!parsed) {
+				throw new Error(`mailwoman_filer_lookup: "${q.frn}" is not a valid FRN`)
+			}
+
+			frn = parsed
+		}
+
+		return await filerLookup(db, {
+			frn,
+			form499ID: q.form499ID,
+			bdcProviderID: q.bdcProviderID,
+			asOf: q.asOf,
+		})
+	},
+
+	async filerFamily(q) {
+		await assertFilerDatabaseExists("mailwoman_filer_family", q.databasePath)
+
+		using db = (await openFilerDatabaseIfPresent(q.databasePath))!
+
+		return await familyRollup(db, {
+			familyID: q.familyID,
+			nodeID: q.nodeID,
+			asOf: q.asOf,
+		})
+	},
+}
+
+const server = createMCPServer(deps)
+const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js")
+
+await server.connect(new StdioServerTransport())

package/lib/layer-guards.ts

@@ -6,18 +6,18 @@
  *   Decision 6 layer-absent guards — kept out of `cli.ts` in their own importable module so the
  *   branching itself has direct unit coverage (`layer-guards.test.ts`), not just
  *   "the tool handler passes an abstain through" (`tools.test.ts`'s stub-level dispatch tests). `cli.ts`
- *   top-level-`await`s a real stdio transport connection at import time, so IT can't be imported by vitest — these
+ *   top-level-`await`s a real stdio transport connection at import time, so IT can't be imported by vitest. These
  *   three functions have no such dependency (pure existence-check + open, or a thrown Error), so they live here and
  *   `cli.ts` just calls them.
  *
  *   - `openBDCDatabaseIfPresent` / `openPlausibilityPOIDeps` — `mailwoman_plausibility_check`'s `bdcDB`/`poi` deps
- *     (`PlausibilityDeps`) are each OPTIONAL, so a missing/absent path degrades to `undefined`, which
+ *     (`PlausibilityDeps`) are each optional, so a missing/absent path degrades to `undefined`, which
  *     `plausibilityCheck` (`@mailwoman/bdc`) already turns into a typed abstain evidence entry
  *     (`{type:"abstain", reason:"requires_bdc_layer"|"requires_build_local_layer"}`) — never a raw sqlite throw.
  *   - `assertBDCDatabaseExists` — `mailwoman_bdc_filing_landscape` requires bdc.db unconditionally (no optional-dep
  *     abstain shape exists for that tool), so a missing file becomes one friendly thrown `Error` naming the layer
  *     instead of the raw `node:sqlite` "unable to open database file" message.
- *   - `openFilerDatabaseIfPresent` / `assertFilerDatabaseExists` — the SAME pairing, for filer.db.
+ *   - `openFilerDatabaseIfPresent` / `assertFilerDatabaseExists` — the same pairing, for filer.db.
  *     `mailwoman_filer_lookup` requires filer.db unconditionally (mirrors `mailwoman_bdc_filing_landscape`'s own
  *     "requires the layer" discipline — `filerLookup` itself has no optional-dep abstain shape either, since criterion
  *     4 makes it throw rather than answer unstamped), so `cli.ts` pairs `assertFilerDatabaseExists` (the friendly
@@ -25,34 +25,45 @@
  */
 
 import type { BDCDatabase, PlausibilityDeps } from "@mailwoman/bdc"
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import type { FilerDatabase } from "@mailwoman/filer"
 import type { POIDatabase } from "@mailwoman/resolver-wof-sqlite/poi"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
+import type { PathBuilderLike } from "path-ts"
 
 /**
- * Open a bdc.db, or return `undefined` when `databasePath` is unset or the file is missing — NEVER a raw sqlite throw.
+ * Open a bdc.db, or return `undefined` when `databasePath` is unset
+ * or the file is missing, never a raw sqlite throw.
+ *
  * See the module header.
  */
 export async function openBDCDatabaseIfPresent(
-	databasePath: string | undefined
-): Promise<DatabaseClient<BDCDatabase> | undefined> {
-	if (!databasePath || !(await pathExists(databasePath))) return undefined
+	databasePath: PathBuilderLike | undefined
+): Promise<DatabaseClient<BDCDatabase> | null> {
+	if (!databasePath || !(await pathExists(databasePath))) return null
 
 	return new DatabaseClient<BDCDatabase>(databasePath, { readOnly: true })
 }
 
 /**
- * Same graceful discipline as {@link openBDCDatabaseIfPresent}, for the poi.db side of `plausibilityCheck`'s deps —
- * `undefined` here becomes the `{type:"abstain", reason:"requires_build_local_layer"}` entry `plausibilityCheck`
- * already produces when a claimed technology's physical-plant categories can't be searched. `POILookup` is dynamically
- * imported (matching `cli.ts`'s existing `resolver-wof-sqlite` laziness) since it's only ever needed when a caller
- * actually wires a poi.db. `lookup` and `contractDB` share ONE `DatabaseSync` handle (the AGENTS.md "one connection,
- * shared" convention) — a real poi.db's rows and its `layer_manifest`/`layer_coverage` tables live in the same file in
- * production, so disposing `contractDB` (which closes the shared handle) is enough; `POILookup` never owns it
+ * Same graceful discipline as {@link openBDCDatabaseIfPresent}, for the poi.db
+ * side of `plausibilityCheck`'s deps.
+ *
+ * `undefined` here becomes the `{type:"abstain", reason:"requires_build_local_layer"}`
+ * entry `plausibilityCheck` already produces when a claimed technology's
+ * physical-plant categories can't be searched.
+ *
+ * `POILookup` is dynamically imported (matching `cli.ts`'s existing `resolver-wof-sqlite` laziness)
+ * since it's only ever needed when a caller actually wires a poi.db.
+ * `lookup` and `schemadb` share one `DatabaseSync` handle
+ * (the agents.md "one connection, shared" convention) — a real poi.db's rows
+ * and its `layer_manifest`/`layer_coverage` tables live in the same file in production,
+ * so disposing `schemadb` (which closes the shared handle) is enough; `POILookup` never owns it
  * (constructed with `{database}`, not `{databasePath}` — see `poi-lookup.ts`), so it never double-closes.
  */
-export async function openPlausibilityPOIDeps(databasePath: string | undefined): Promise<PlausibilityDeps["poi"]> {
+export async function openPlausibilityPOIDeps(
+	databasePath: PathBuilderLike | undefined
+): Promise<PlausibilityDeps["poi"]> {
 	if (!databasePath || !(await pathExists(databasePath))) return undefined
 
 	const { POILookup } = await import("@mailwoman/resolver-wof-sqlite/poi")
@@ -60,41 +71,47 @@ export async function openPlausibilityPOIDeps(databasePath: string | undefined):
 
 	return {
 		lookup: new POILookup({ database }),
-		contractDB: database,
+		schemadb: database,
 	}
 }
 
 /**
- * Throws a friendly Error naming the layer when `databasePath` doesn't exist — `mailwoman_bdc_filing_landscape`'s guard
- * (decision 6b). `toolName` is threaded through so the message matches whichever tool calls this (today: only
- * `mailwoman_bdc_filing_landscape`).
+ * Throws a friendly Error naming the layer when `databasePath` doesn't exist —
+ * `mailwoman_bdc_filing_landscape`'s guard (decision 6b).
+ *
+ * `toolName` is threaded through so the message matches whichever tool calls this
+ * (today: only `mailwoman_bdc_filing_landscape`).
  */
-export async function assertBDCDatabaseExists(toolName: string, databasePath: string): Promise<void> {
+export async function assertBDCDatabaseExists(toolName: string, databasePath: PathBuilderLike): Promise<void> {
 	if (!(await pathExists(databasePath))) {
 		throw new Error(`${toolName}: bdc.db not found at "${databasePath}"`)
 	}
 }
 
 /**
- * Open a filer.db, or return `undefined` when `databasePath` is unset or the file is missing — NEVER a raw sqlite throw
- * (mirroring {@link openBDCDatabaseIfPresent}). Used by `cli.ts`'s `mailwoman_filer_lookup` handler after
- * {@link assertFilerDatabaseExists} has already confirmed the file is present.
+ * Open a filer.db, or return `undefined` when `databasePath` is unset or the file is missing,
+ * never a raw sqlite throw (mirroring {@link openBDCDatabaseIfPresent}).
+ *
+ * Used by `cli.ts`'s `mailwoman_filer_lookup` handler after {@link assertFilerDatabaseExists}
+ * has already confirmed the file is present.
  */
 export async function openFilerDatabaseIfPresent(
-	databasePath: string | undefined
-): Promise<DatabaseClient<FilerDatabase> | undefined> {
-	if (!databasePath || !(await pathExists(databasePath))) return undefined
+	databasePath: PathBuilderLike | undefined
+): Promise<DatabaseClient<FilerDatabase> | null> {
+	if (!databasePath || !(await pathExists(databasePath))) return null
 
 	return new DatabaseClient<FilerDatabase>(databasePath, { readOnly: true })
 }
 
 /**
- * Throws a friendly Error naming the layer when `databasePath` doesn't exist — `mailwoman_filer_lookup`'s guard
- * (mirroring {@link assertBDCDatabaseExists}). `filerLookup` itself has no optional-dep abstain shape (criterion 4
- * makes it throw rather than answer unstamped), so filer.db is required unconditionally, same as bdc.db is for
- * `mailwoman_bdc_filing_landscape`.
+ * Throws a friendly Error naming the layer when `databasePath` doesn't exist —
+ * `mailwoman_filer_lookup`'s guard (mirroring {@link assertBDCDatabaseExists}).
+ *
+ * `filerLookup` itself has no optional-dep abstain shape
+ * (criterion 4 makes it throw rather than answer unstamped), so filer.db is required
+ * unconditionally, same as bdc.db is for `mailwoman_bdc_filing_landscape`.
  */
-export async function assertFilerDatabaseExists(toolName: string, databasePath: string): Promise<void> {
+export async function assertFilerDatabaseExists(toolName: string, databasePath: PathBuilderLike): Promise<void> {
 	if (!(await pathExists(databasePath))) {
 		throw new Error(`${toolName}: filer.db not found at "${databasePath}"`)
 	}

package/lib/server.ts

@@ -4,29 +4,41 @@
  * @author Teffen Ellis, et al.
  *
  *   MCP server wiring — thin glue that registers `tools.ts`'s tool table on an `McpServer`. The tool table is the
- *   stable, tested contract (`tools.test.ts`); this module only adapts it to the SDK's `registerTool` signature and
+ *   stable, tested interface (`tools.test.ts`); this module only adapts it to the SDK's `registerTool` signature and
  *   `CallToolResult` envelope. `cli.ts` owns building the real `MCPToolDeps` and connecting a transport.
  */
 
+import { prettyJSON } from "@mailwoman/core/json"
+import { readPackageJSON } from "@mailwoman/core/module/resolve-from"
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"
 
 import { buildToolTable, type MCPToolDeps } from "#tools"
 
 /**
- * The advertised server version — keep in lockstep with `package.json`'s `version` (not read from it dynamically: a
- * static string avoids `resolveJsonModule`/`composite` friction for one cosmetic field, the same tradeoff
- * `nominatim`/`photon`'s OpenAPI `info.version` DON'T make since theirs is a documented public contract; an MCP client
- * only ever logs this).
+ * The advertised server version, read from this package's own manifest at load.
+ *
+ * A JSON import would make `tsc` copy the file into `out/`, where it becomes the package
+ * scope for the compiled tree, so the manifest is read through the module resolver instead.
  */
-const MCP_SERVER_VERSION = "7.1.0"
+const MCP_SERVER_VERSION = await readPackageJSON(import.meta.url, "@mailwoman/mcp").then((manifest) => {
+	if (!manifest.version) {
+		throw new Error("@mailwoman/mcp: package.json carries no version to advertise")
+	}
+
+	return manifest.version
+})
 
 /**
- * Build an `McpServer` with every `tools.ts` tool registered. A handler's returned value is JSON-stringified into a
- * single `text` content block — every tool here answers with structured data (parse trees, geocode results, search
- * hits), so a plain JSON text block is the simplest faithful rendering; none of the tools need images, resource links,
- * or other MCP content kinds. A thrown error becomes an `isError` tool result instead of a protocol-level failure, so a
- * bad address / missing db surfaces to the agent as a normal (if unsuccessful) tool call.
+ * Build an `McpServer` with every `tools.ts` tool registered.
+ *
+ * A handler's returned value is JSON-stringified into a single `text` content block.
+ * Every tool here answers with structured data (parse trees, geocode results, search hits),
+ * so a plain JSON text block is the simplest faithful rendering.
+ *
+ * None of the tools need images, resource links, or other MCP content kinds.
+ * A thrown error becomes an `isError` tool result instead of a protocol-level failure,
+ * so a bad address / missing db surfaces to the agent as a normal (if unsuccessful) tool call.
  */
 export function createMCPServer(deps: MCPToolDeps): McpServer {
 	const server = new McpServer({ name: "mailwoman", version: MCP_SERVER_VERSION })
@@ -39,7 +51,7 @@ export function createMCPServer(deps: MCPToolDeps): McpServer {
 				try {
 					const result = await tool.handler(args)
 
-					return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }
+					return { content: [{ type: "text", text: prettyJSON(result) }] }
 				} catch (error) {
 					const message = error instanceof Error ? error.message : String(error)
 

package/lib/tools.ts

@@ -2,44 +2,13 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   The MCP tool table — pure, transport-free. `server.ts` adapts this to the `@modelcontextprotocol/sdk`'s
- *   registration API; `cli.ts` builds the real `MCPToolDeps` from the mailwoman library. Kept separate so this
- *   file (the actual product surface) is testable without any MCP plumbing — `tools.test.ts` calls
- *   `buildToolTable` directly with stub deps.
- *
- *   One tool per capability the exotic-POI/BDC arcs' other packages expose to a human/CLI caller — see
- *   `buildToolTable`'s return value for the authoritative, current list (this comment intentionally states no count,
- *   so it can't go stale as tools are added):
- *
- *   - `mailwoman_parse` — the runtime pipeline's parse (optionally POI-aware).
- *   - `mailwoman_geocode` — the street-level geocode cascade (`mailwoman/geocode-core`).
- *   - `mailwoman_poi_search` — POI-intent extraction + (when a poi.db is wired) execution.
- *   - `mailwoman_overpass_export` — OverpassQL EXPORT emitter (`mailwoman/poi-overpass`) — "we print the query;
- *     we never run it".
- *   - `mailwoman_layer_manifest` — read a spatial-layer database's provenance manifest + coverage summary
- *     (`@mailwoman/core/layers`).
- *   - `mailwoman_bdc_filing_landscape` — read a bdc.db layer's provider/technology/speed-bucket filing census over a
- *     set of census blocks or H3 cells (`@mailwoman/bdc`'s `filingLandscape`).
- *   - `mailwoman_plausibility_check` — score one claimed broadband-service assertion against BDC filing evidence and
- *     nearby telecom infrastructure (`@mailwoman/bdc`'s `plausibilityCheck`), returning a positive-evidence-only bundle
- *     with an always-present `coverage_confidence`. A missing/absent `bdc_database_path`/`poi_database_path` degrades
- *     to a typed abstain entry in the bundle, never a throw (decision 6).
- *   - `mailwoman_filer_lookup` — read the FCC filer identity crosswalk (`@mailwoman/filer`'s
- *     `filerLookup`) for one identifier (FRN, Form 499 ID, or BDC provider ID): every OTHER identifier it shares an
- *     authoritative edge with, its current attributes, its authoritative entity cluster, and any inferred links —
- *     reported separately, never merged into the cluster. `as_of` is always present (defaults to today).
- *   - `mailwoman_filer_family` — read a corporate family's membership (`@mailwoman/filer/sdk`'s
- *     `familyRollup`) from a filer.db layer database, given a `family_id` or a `node_id`. Distinct from an entity
- *     cluster (same filer, different identifiers) — a corporate family spans several DIFFERENT filers under a
- *     holding/parent/subsidiary/management relationship. The handler passes `familyRollup`'s result through
- *     unchanged: no reshaping, filtering, or summarizing of who-owns-whom data.
  */
 
 import { z } from "zod"
 
 /**
- * The library surface every tool handler dispatches to. `cli.ts` builds the real implementation.
+ * Defines the library operations that MCP tool handlers call.
+ * `cli.ts` implements those operations.
  */
 export interface MCPToolDeps {
 	parse: (text: string, opts?: { poi?: boolean }) => Promise<unknown>
@@ -68,13 +37,12 @@ export interface MCPToolDeps {
 }
 
 /**
- * One MCP tool. `inputSchema` is a plain Zod object (not `any` — this repo's oxlint config errors on
- * `typescript/no-explicit-any`) — `z.ZodRawShape` is zod's own umbrella type for "any object shape", so this stays
- * generic over the concrete per-tool schemas without reaching for `any`. `handler` re-parses `args` through the same
- * schema (cheap; zod objects are small here) rather than trusting an unchecked cast, so the array of heterogeneous
- * tools stays type-safe internally despite the necessarily-uniform external shape.
+ * Describes one MCP tool as registered with the server.
+ *
+ * Each `handler` re-parses `args` through its own `inputSchema` instead of trusting a cast,
+ * because the table's uniform signature erases the per-tool types.
  */
-export interface MCPToolDef {
+interface MCPToolDef {
 	name: string
 	description: string
 	inputSchema: z.ZodObject<z.ZodRawShape>
@@ -255,7 +223,8 @@ const FilerFamilyInputSchema = z.object({
 })
 
 /**
- * Build the tool table for a concrete `MCPToolDeps` implementation. Pure — no transport, no I/O of its own.
+ * Builds the MCP tool table over the given dependencies, without opening a transport
+ * or performing I/O itself.
  */
 export function buildToolTable(deps: MCPToolDeps): MCPToolDef[] {
 	return [

package/out/cli/main.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+export {};
+//# sourceMappingURL=main.d.ts.map

package/out/cli/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../cli/main.ts"],"names":[],"mappings":";AACA;;;;GAIG"}