@mailwoman/mcp 7.1.0

package/README.md

@@ -0,0 +1,28 @@
+# @mailwoman/mcp
+
+An **MCP server** exposing [Mailwoman](https://mailwoman.sister.software)'s parse/geocode/POI toolset to agents over stdio — no HTTP endpoint, just a subprocess an MCP client launches.
+
+## Tools
+
+| Tool                        | What it does                                                            |
+| --------------------------- | ----------------------------------------------------------------------- |
+| `mailwoman_parse`           | Runtime-pipeline parse (optionally POI-aware)                           |
+| `mailwoman_geocode`         | Street-level geocode cascade                                            |
+| `mailwoman_poi_search`      | POI-intent extraction, executed against a wired `poi.db`                |
+| `mailwoman_overpass_export` | Renders a POI query as OverpassQL (prints the query, never runs it)     |
+| `mailwoman_layer_manifest`  | Reads a spatial-layer database's provenance manifest + coverage summary |
+
+## Config
+
+```json
+{
+	"mcpServers": {
+		"mailwoman": {
+			"command": "mailwoman-mcp",
+			"args": ["--poi-db", "/path/to/poi.db"]
+		}
+	}
+}
+```
+
+`--poi-db <path>` wires `mailwoman_poi_search` (and `mailwoman_parse`'s `poi: true` path) to a real database; omit it and those tools degrade gracefully to intent-only.

package/out/cli.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-mcp` — boot the MCP server over stdio. Wires the real `MCPToolDeps` (`tools.ts`) from the mailwoman
+ *   library: `createRuntimePipeline` for parse/POI-intent, `geocode-core`'s `geocodeAddress` for geocode,
+ *   `mailwoman/poi-overpass`'s `emitOverpassQL` for the export tool, and `@mailwoman/core/layers` for the layer
+ *   manifest tool.
+ *
+ *   Deps are LAZY: nothing here loads the neural weights or opens a gazetteer db at startup — an MCP client
+ *   connects, lists tools, and may never call one (or may call `mailwoman_overpass_export`/`mailwoman_layer_manifest`,
+ *   neither of which needs the classifier at all). The shared classifier+resolver are built once, on the FIRST call
+ *   to any tool that needs them, and cached for the process lifetime.
+ *
+ *   ```sh
+ *   mailwoman-mcp                       # geocode/poi_search degrade gracefully with no poi.db wired
+ *   mailwoman-mcp --poi-db poi.db       # mailwoman_poi_search additionally executes against poi.db
+ *   ```
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/out/cli.d.ts.map

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

package/out/cli.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-mcp` — boot the MCP server over stdio. Wires the real `MCPToolDeps` (`tools.ts`) from the mailwoman
+ *   library: `createRuntimePipeline` for parse/POI-intent, `geocode-core`'s `geocodeAddress` for geocode,
+ *   `mailwoman/poi-overpass`'s `emitOverpassQL` for the export tool, and `@mailwoman/core/layers` for the layer
+ *   manifest tool.
+ *
+ *   Deps are LAZY: nothing here loads the neural weights or opens a gazetteer db at startup — an MCP client
+ *   connects, lists tools, and may never call one (or may call `mailwoman_overpass_export`/`mailwoman_layer_manifest`,
+ *   neither of which needs the classifier at all). The shared classifier+resolver are built once, on the FIRST call
+ *   to any tool that needs them, and cached for the process lifetime.
+ *
+ *   ```sh
+ *   mailwoman-mcp                       # geocode/poi_search degrade gracefully with no poi.db wired
+ *   mailwoman-mcp --poi-db poi.db       # mailwoman_poi_search additionally executes against poi.db
+ *   ```
+ */
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { parseArgs } from "node:util";
+import { DatabaseClient } from "@mailwoman/core/kysley/client";
+import { readLayerManifest } from "@mailwoman/core/layers";
+import { NeuralAddressClassifier } from "@mailwoman/neural";
+import { getPOICategory } from "@mailwoman/poi-taxonomy";
+import { createWOFResolver } from "@mailwoman/resolver";
+import { createRuntimePipeline } from "mailwoman";
+import { geocodeAddress, ShardProvider } from "mailwoman/geocode-core";
+import { emitOverpassQL } from "mailwoman/poi-overpass";
+import { createResolverBackend, mailwomanDataRoot, resolveCandidateDBPath, wofShardPaths, } from "mailwoman/resolver-backend";
+import { createMCPServer } from "./server.js";
+const { values } = parseArgs({
+    options: {
+        "poi-db": { type: "string" },
+    },
+    allowPositionals: true,
+});
+/**
+ * `--poi-db` wires `mailwoman_poi_search` (and, via the same pipeline, `mailwoman_parse`'s `poi: true` path) to a real
+ * `poi.db`. Absent → intent-only (parses the query, extracts the subject/anchor, never executes a lookup).
+ */
+const poiDatabasePath = values["poi-db"];
+/**
+ * The shared classifier + resolver, built exactly once on the first call that needs them (see the module header).
+ * `NeuralAddressClassifier.loadFromWeights` auto-resolves the bundled `en-US` weights; the resolver backend prefers a
+ * configured candidate gazetteer (`$MAILWOMAN_CANDIDATE_DB`) and otherwise falls back to the admin-only WOF shards
+ * already on the data root — same selection `nominatim`/`photon`'s CLIs make.
+ */
+let corePromise;
+function loadCore() {
+    corePromise ??= (async () => {
+        const resolverMod = await import("@mailwoman/resolver-wof-sqlite");
+        const wofPaths = wofShardPaths().filter(existsSync);
+        const candidateDb = resolveCandidateDBPath();
+        const backend = createResolverBackend(resolverMod, { wofPaths, candidateDb });
+        const resolver = createWOFResolver(backend);
+        const classifier = await NeuralAddressClassifier.loadFromWeights({ locale: "en-US" });
+        const shards = new ShardProvider(resolverMod, mailwomanDataRoot());
+        return { classifier, resolver, shards };
+    })();
+    return corePromise;
+}
+let plainPipeline;
+/**
+ * Keyed by the poi.db path used to build it (`""` = intent-only, no db) — `mailwoman_poi_search` can be called with a
+ * `poiDatabasePath` that differs from the server's `--poi-db`, in which case a fresh one-off pipeline is built and
+ * cached under that path instead of reusing the default.
+ */
+const poiPipelines = new Map();
+async function getPlainPipeline() {
+    if (!plainPipeline) {
+        const { classifier, resolver } = await loadCore();
+        plainPipeline = createRuntimePipeline({ classifier, resolver });
+    }
+    return plainPipeline;
+}
+async function getPoiPipeline(dbPath) {
+    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 } : true,
+    });
+    poiPipelines.set(key, pipeline);
+    return pipeline;
+}
+const deps = {
+    async parse(text, opts) {
+        const pipeline = opts?.poi ? await getPoiPipeline(poiDatabasePath) : await getPlainPipeline();
+        return pipeline(text);
+    },
+    async geocode(text) {
+        const { classifier, resolver, shards } = await loadCore();
+        return geocodeAddress(text, { classifier, resolver, shards: shards.for });
+    },
+    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) {
+        // Intent-only is enough here — the export just needs the parsed subject/anchor, never executed results
+        // ("we print the query; we never run it", poi-overpass.ts). Reuses the server's wired poi pipeline (a
+        // real poi.db doesn't change the emitted OverpassQL) instead of forcing a second one-off pipeline.
+        const pipeline = await getPoiPipeline(poiDatabasePath);
+        const result = await pipeline(query);
+        const outcome = result.poiIntent;
+        if (!outcome || outcome.type !== "intent") {
+            const reason = outcome?.type === "abstain" ? `: ${outcome.reason}` : "";
+            throw new Error(`mailwoman_overpass_export: query is not POI-shaped (${outcome?.type ?? "no poi intent"}${reason})`);
+        }
+        const { subject } = outcome.intent;
+        const osmTag = subject.kind === "category" ? getPOICategory(subject.categoryID)?.osmTag : undefined;
+        return emitOverpassQL(outcome.intent, osmTag ? { osmTag } : {});
+    },
+    async layerManifest(databasePath) {
+        using db = new DatabaseClient({
+            database: new DatabaseSync(databasePath, { readOnly: true }),
+        });
+        const manifest = await readLayerManifest(db);
+        const coverage = await db
+            .selectFrom("layer_coverage")
+            .select((eb) => [
+            eb.fn.count("h3_cell").as("surveyedCellCount"),
+            eb.fn.avg("completeness").as("averageCompleteness"),
+            eb.fn.sum("observed_rows").as("totalObservedRows"),
+        ])
+            .executeTakeFirst();
+        return { manifest, coverage };
+    },
+};
+const server = createMCPServer(deps);
+const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+await server.connect(new StdioServerTransport());
+//# sourceMappingURL=cli.js.map

package/out/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":"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"}

package/out/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/mcp` public surface — the tool table + server factory, for a caller embedding the MCP server
+ *   directly (custom transport, alternate deps) instead of running `mailwoman-mcp` as a subprocess.
+ */
+export * from "./server.ts";
+export * from "./tools.ts";
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}

package/out/index.js

@@ -0,0 +1,11 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/mcp` public surface — the tool table + server factory, for a caller embedding the MCP server
+ *   directly (custom transport, alternate deps) instead of running `mailwoman-mcp` as a subprocess.
+ */
+export * from "./server.js";
+export * from "./tools.js";
+//# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}

package/out/server.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @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
+ *   `CallToolResult` envelope. `cli.ts` owns building the real `MCPToolDeps` and connecting a transport.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type MCPToolDeps } from "./tools.ts";
+/**
+ * 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 five 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 declare function createMCPServer(deps: MCPToolDeps): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/out/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGnE,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAA;AAU7D;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,CAsB5D"}

package/out/server.js

@@ -0,0 +1,42 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @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
+ *   `CallToolResult` envelope. `cli.ts` owns building the real `MCPToolDeps` and connecting a transport.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { buildToolTable } from "./tools.js";
+/**
+ * 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).
+ */
+const MCP_SERVER_VERSION = "7.1.0";
+/**
+ * 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 five 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) {
+    const server = new McpServer({ name: "mailwoman", version: MCP_SERVER_VERSION });
+    for (const tool of buildToolTable(deps)) {
+        server.registerTool(tool.name, { description: tool.description, inputSchema: tool.inputSchema.shape }, async (args) => {
+            try {
+                const result = await tool.handler(args);
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return { content: [{ type: "text", text: message }], isError: true };
+            }
+        });
+    }
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/out/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGnE,OAAO,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAA;AAE7D;;;;;GAKG;AACH,MAAM,kBAAkB,GAAG,OAAO,CAAA;AAElC;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAiB;IAChD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC,CAAA;IAEhF,KAAK,MAAM,IAAI,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,CAAC,YAAY,CAClB,IAAI,CAAC,IAAI,EACT,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,EACtE,KAAK,EAAE,IAAI,EAA2B,EAAE;YACvC,IAAI,CAAC;gBACJ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;gBAEvC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;YAC9E,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBAEtE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;YACrE,CAAC;QACF,CAAC,CACD,CAAA;IACF,CAAC;IAED,OAAO,MAAM,CAAA;AACd,CAAC"}

package/out/tools.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @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.
+ *
+ *   Five tools, one per capability the exotic-POI arc's other packages expose to a human/CLI caller:
+ *
+ *   - `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`).
+ */
+import { z } from "zod";
+/** The library surface every tool handler dispatches to. `cli.ts` builds the real implementation. */
+export interface MCPToolDeps {
+    parse: (text: string, opts?: {
+        poi?: boolean;
+    }) => Promise<unknown>;
+    geocode: (text: string) => Promise<unknown>;
+    poiSearch: (q: {
+        query: string;
+        poiDatabasePath?: string;
+    }) => Promise<unknown>;
+    overpassExport: (query: string) => Promise<string>;
+    layerManifest: (databasePath: string) => Promise<unknown>;
+}
+/**
+ * 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.
+ */
+export interface MCPToolDef {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<z.ZodRawShape>;
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+}
+/** Build the tool table for a concrete `MCPToolDeps` implementation. Pure — no transport, no I/O of its own. */
+export declare function buildToolTable(deps: MCPToolDeps): MCPToolDef[];
+//# sourceMappingURL=tools.d.ts.map

package/out/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,qGAAqG;AACrG,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACnE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3C,SAAS,EAAE,CAAC,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/E,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAClD,aAAa,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACzD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;IACvC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC5D;AA2CD,gHAAgH;AAChH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE,CAqE9D"}

package/out/tools.js

@@ -0,0 +1,115 @@
+/**
+ * @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.
+ *
+ *   Five tools, one per capability the exotic-POI arc's other packages expose to a human/CLI caller:
+ *
+ *   - `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`).
+ */
+import { z } from "zod";
+const ParseInputSchema = z.object({
+    text: z.string().min(1).describe("The free-text location string to parse (a postal address or a POI query)."),
+    poi: z
+        .boolean()
+        .optional()
+        .describe("Also run POI-intent detection/extraction (category/brand/name subject + spatial anchor). Default false — plain address parse."),
+});
+const GeocodeInputSchema = z.object({
+    text: z.string().min(1).describe("The free-text postal address to geocode."),
+});
+const POISearchInputSchema = z.object({
+    query: z
+        .string()
+        .min(1)
+        .describe("A free-text POI query with a spatial anchor, e.g. 'coffee shops near 350 5th Ave, New York' or 'starbucks in Chicago'."),
+    poiDatabasePath: z
+        .string()
+        .optional()
+        .describe("Path to a specific poi.db shard to search. Omit to use the server's configured default (if any)."),
+});
+const OverpassExportInputSchema = z.object({
+    query: z
+        .string()
+        .min(1)
+        .describe("A free-text POI query (same shape as mailwoman_poi_search) to render as an OverpassQL query."),
+});
+const LayerManifestInputSchema = z.object({
+    databasePath: z
+        .string()
+        .min(1)
+        .describe("Path to a mailwoman spatial-layer database (poi.db, an address-points shard, etc.)."),
+});
+/** Build the tool table for a concrete `MCPToolDeps` implementation. Pure — no transport, no I/O of its own. */
+export function buildToolTable(deps) {
+    return [
+        {
+            name: "mailwoman_parse",
+            description: "Parse a free-text location string (postal address or POI query) into a structured address tree — house " +
+                "number, street, locality, region, postcode, country, and (with `poi: true`) a POI intent. Use this to " +
+                "understand a query's structure before geocoding or searching; it does not resolve coordinates.",
+            inputSchema: ParseInputSchema,
+            handler: async (args) => {
+                const { text, poi } = ParseInputSchema.parse(args);
+                return deps.parse(text, { poi });
+            },
+        },
+        {
+            name: "mailwoman_geocode",
+            description: "Geocode a free-text postal address to coordinates via the full parse-then-resolve cascade (rooftop > " +
+                "interpolated > street > admin resolution tiers). Returns lat/lon, the resolution tier, an uncertainty " +
+                "radius in meters, and the resolved admin hierarchy. Use this to convert an address string into a location.",
+            inputSchema: GeocodeInputSchema,
+            handler: async (args) => {
+                const { text } = GeocodeInputSchema.parse(args);
+                return deps.geocode(text);
+            },
+        },
+        {
+            name: "mailwoman_poi_search",
+            description: "Search for points of interest — a category ('coffee shop'), a brand ('Starbucks'), or a named place — " +
+                "near the spatial anchor extracted from the query text (e.g. 'pharmacies near 10 Downing St, London'). " +
+                "Returns the parsed intent and, when a POI database is available, ranked nearby results.",
+            inputSchema: POISearchInputSchema,
+            handler: async (args) => {
+                const { query, poiDatabasePath } = POISearchInputSchema.parse(args);
+                return deps.poiSearch({ query, poiDatabasePath });
+            },
+        },
+        {
+            name: "mailwoman_overpass_export",
+            description: "Turn a POI-shaped query into an OverpassQL query string for Overpass Turbo — this NEVER executes the " +
+                "query itself, it only prints it. Use this when the operator wants to explore or run the search " +
+                "themselves against live OpenStreetMap data.",
+            inputSchema: OverpassExportInputSchema,
+            handler: async (args) => {
+                const { query } = OverpassExportInputSchema.parse(args);
+                return deps.overpassExport(query);
+            },
+        },
+        {
+            name: "mailwoman_layer_manifest",
+            description: "Inspect a mailwoman spatial-layer database (poi.db, an address-points shard, etc.): read its provenance " +
+                "and licensing manifest (source, vintage, build command, license) plus a coverage summary (how many H3 " +
+                "cells were surveyed, average completeness, total observed rows). Use this to check what a layer " +
+                "actually covers before relying on it.",
+            inputSchema: LayerManifestInputSchema,
+            handler: async (args) => {
+                const { databasePath } = LayerManifestInputSchema.parse(args);
+                return deps.layerManifest(databasePath);
+            },
+        },
+    ];
+}
+//# sourceMappingURL=tools.js.map

package/out/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAyBvB,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,2EAA2E,CAAC;IAC7G,GAAG,EAAE,CAAC;SACJ,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CACR,+HAA+H,CAC/H;CACF,CAAC,CAAA;AAEF,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,0CAA0C,CAAC;CAC5E,CAAC,CAAA;AAEF,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,KAAK,EAAE,CAAC;SACN,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACR,wHAAwH,CACxH;IACF,eAAe,EAAE,CAAC;SAChB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,kGAAkG,CAAC;CAC9G,CAAC,CAAA;AAEF,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,KAAK,EAAE,CAAC;SACN,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,8FAA8F,CAAC;CAC1G,CAAC,CAAA;AAEF,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,YAAY,EAAE,CAAC;SACb,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,qFAAqF,CAAC;CACjG,CAAC,CAAA;AAEF,gHAAgH;AAChH,MAAM,UAAU,cAAc,CAAC,IAAiB;IAC/C,OAAO;QACN;YACC,IAAI,EAAE,iBAAiB;YACvB,WAAW,EACV,yGAAyG;gBACzG,wGAAwG;gBACxG,gGAAgG;YACjG,WAAW,EAAE,gBAAgB;YAC7B,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACvB,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAElD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,CAAA;YACjC,CAAC;SACD;QACD;YACC,IAAI,EAAE,mBAAmB;YACzB,WAAW,EACV,uGAAuG;gBACvG,wGAAwG;gBACxG,4GAA4G;YAC7G,WAAW,EAAE,kBAAkB;YAC/B,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACvB,MAAM,EAAE,IAAI,EAAE,GAAG,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAE/C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;YAC1B,CAAC;SACD;QACD;YACC,IAAI,EAAE,sBAAsB;YAC5B,WAAW,EACV,wGAAwG;gBACxG,wGAAwG;gBACxG,yFAAyF;YAC1F,WAAW,EAAE,oBAAoB;YACjC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACvB,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,GAAG,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAEnE,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,CAAA;YAClD,CAAC;SACD;QACD;YACC,IAAI,EAAE,2BAA2B;YACjC,WAAW,EACV,uGAAuG;gBACvG,iGAAiG;gBACjG,6CAA6C;YAC9C,WAAW,EAAE,yBAAyB;YACtC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACvB,MAAM,EAAE,KAAK,EAAE,GAAG,yBAAyB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAEvD,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAA;YAClC,CAAC;SACD;QACD;YACC,IAAI,EAAE,0BAA0B;YAChC,WAAW,EACV,0GAA0G;gBAC1G,wGAAwG;gBACxG,kGAAkG;gBAClG,uCAAuC;YACxC,WAAW,EAAE,wBAAwB;YACrC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACvB,MAAM,EAAE,YAAY,EAAE,GAAG,wBAAwB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAE7D,OAAO,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,CAAA;YACxC,CAAC;SACD;KACD,CAAA;AACF,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@mailwoman/mcp",
+  "version": "7.1.0",
+  "description": "MCP server — mailwoman's spatial toolset for agents (parse, geocode, poi_search, overpass_export, layer_manifest).",
+  "license": "AGPL-3.0-only OR LicenseRef-Commercial",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sister-software/mailwoman.git",
+    "directory": "mcp"
+  },
+  "bin": {
+    "mailwoman-mcp": "./out/cli.js"
+  },
+  "files": [
+    "out/**/*.js",
+    "out/**/*.js.map",
+    "out/**/*.d.ts",
+    "out/**/*.d.ts.map",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./out/index.d.ts",
+      "default": "./out/index.js"
+    }
+  },
+  "publishConfig": {
+    "exports": {
+      "./package.json": "./package.json",
+      ".": {
+        "types": "./out/index.d.ts",
+        "default": "./out/index.js"
+      }
+    },
+    "access": "public"
+  },
+  "dependencies": {
+    "@mailwoman/core": "7.1.0",
+    "@mailwoman/neural": "7.1.0",
+    "@mailwoman/poi-taxonomy": "7.1.0",
+    "@mailwoman/resolver": "7.1.0",
+    "@mailwoman/resolver-wof-sqlite": "7.1.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "mailwoman": "7.1.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@mailwoman/resolver-wof-sqlite": "7.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@mailwoman/resolver-wof-sqlite": {
+      "optional": true
+    }
+  }
+}