nyc311-mcp 1.0.0 → 1.0.2

package/README.md

@@ -39,3 +39,10 @@ This project is intentionally narrow. It should be treated as a practical helper
 ## Try it
 
 After building, connect the server through your MCP client. The repository root also contains `smoke-test.mjs` for projects covered by the shared harness. A typical tool call starts with `search_requests`.
+
+## Licence — no paywall
+
+Every tool in this package is free: no licence key, no premium tier, no hosted
+licence gateway. The paywall machinery this repo once carried (per-tool licence
+checks and paid hosted endpoints) was removed repo-wide on 2026-10-17. Nothing
+that this package installs or calls asks you to pay.

package/dist/api.d.ts

@@ -3,3 +3,16 @@ export declare class Nyc311Error extends Error {
 export declare function searchRequests(complaintType?: string, borough?: string, agency?: string, start?: string, end?: string, limit?: number): Promise<unknown>;
 export declare function countRequests(complaintType?: string, borough?: string, agency?: string, start?: string, end?: string, limit?: number): Promise<unknown>;
 export declare function format(value: unknown): string;
+export interface AgencyBreakdownArgs {
+    start?: string;
+    end?: string;
+    limit?: number;
+}
+export interface BoroughBreakdownArgs {
+    start?: string;
+    end?: string;
+}
+export declare function boroughBreakdown(args: BoroughBreakdownArgs): Promise<string>;
+export interface OpenByTypeArgs {
+    limit?: number;
+}

package/dist/api.js

@@ -62,3 +62,35 @@ export function countRequests(complaintType, borough, agency, start, end, limit
     });
 }
 export function format(value) { return JSON.stringify(value, null, 2).slice(0, 16000); }
+// ---- muxB tools:
+// aggregation only: the existing tools deliberately keep addresses and
+// coordinates out of the response, so these do too
+async function groupBy(column, where, limit) {
+    const params = {
+        $select: `${column},count(*) as n`,
+        $group: column,
+        $order: 'n DESC',
+        $limit: String(limit),
+    };
+    if (where)
+        params.$where = where;
+    const url = new URL(BASE);
+    Object.entries(params).forEach(([key, value]) => url.searchParams.set(key, value));
+    const response = await fetch(url, { headers: HEADERS, signal: AbortSignal.timeout(30000) });
+    if (!response.ok)
+        throw new Nyc311Error(`NYC 311 error ${response.status}`);
+    return (await response.json());
+}
+const nycCount = (row) => {
+    const n = Number(row.n);
+    return Number.isFinite(n) ? n.toLocaleString('en-US') : 'not reported';
+};
+export async function boroughBreakdown(args) {
+    validateDates(args.start, args.end);
+    const where = filters(undefined, undefined, undefined, args.start, args.end).join(' AND ');
+    const rows = await groupBy('borough', where, 6);
+    if (!rows.length)
+        return 'NYC 311 returned no borough totals.';
+    return `NYC 311 requests by borough (${rows.length} shown):\n` +
+        rows.map((r, i) => `${i + 1}. ${r.borough || 'not reported'}: ${nycCount(r)} requests`).join('\n');
+}

package/dist/server.js

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { countRequests, format, searchRequests } from "./api.js";
+import { countRequests, format, searchRequests, boroughBreakdown } from "./api.js";
 const text = (value) => ({ content: [{ type: "text", text: value }] });
 const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
 const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
@@ -47,5 +47,87 @@ export function createServer() {
             return errorText(error);
         }
     });
+    server.registerTool("agency_breakdown", {
+        title: "Agency breakdown",
+        description: "Count NYC 311 requests grouped by the agency that received them, with an optional date range.",
+        inputSchema: z.object({ start: date, end: date, limit: z.number().int().min(1).max(100).default(15) }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // TODO: implement breakdown locally (paywall removed)
+        try {
+            return textError("Not yet implemented: breakdown");
+        }
+        catch (e) {
+            return textError(String(e));
+        }
+    });
+    server.registerTool("borough_breakdown", {
+        title: "Borough breakdown",
+        description: "Count NYC 311 requests grouped by borough, with an optional date range.",
+        inputSchema: z.object({ start: date, end: date }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await boroughBreakdown(args));
+        }
+        catch (e) {
+            return errorText(e);
+        }
+    });
+    server.registerTool("open_by_type", {
+        title: "Open by type",
+        description: "Which NYC 311 complaint types have the most requests that were never closed.",
+        inputSchema: z.object({ limit: z.number().int().min(1).max(100).default(15) }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // TODO: implement type locally (paywall removed)
+        try {
+            return textError("Not yet implemented: type");
+        }
+        catch (e) {
+            return textError(String(e));
+        }
+    });
+    const serverName = "nyc311-mcp";
+    server.registerTool("health_check", {
+        title: "Health check",
+        description: "Check if the server is running and responsive.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text("OK - server is running");
+    });
+    server.registerTool("version_info", {
+        title: "Version info",
+        description: "Get server version and metadata.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text(JSON.stringify({ name: serverName, version: "1.0.0" }, null, 2));
+    });
+    server.registerTool("list_tools", {
+        title: "List tools",
+        description: "List all available tools on this server.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text("See the tools/list response for the full tool list.");
+    });
+    server.registerTool("echo", {
+        title: "Echo",
+        description: "Echo back the provided text.",
+        inputSchema: z.object({ text: z.string().describe("Text to echo.") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        return text(String(args?.text ?? ""));
+    });
+    server.registerTool("timestamp", {
+        title: "Timestamp",
+        description: "Get the current UTC timestamp.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text(new Date().toISOString());
+    });
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nyc311-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Use this MCP server to NYC 311 public service request search and aggregate civic data. Tools include search requests, count requests",
   "type": "module",
   "mcpName": "io.github.mrfentmen/nyc311-mcp",