nyc311-mcp 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# nyc311-mcp
+
+Explore public NYC 311 service-request data for civic research, neighborhood-level trend analysis, and city-service questions.
+
+## Tools
+
+- `search_requests`: search bounded request metadata by complaint type, borough, agency, and dates.
+- `count_requests`: aggregate request totals by complaint type with the same filters.
+
+The server intentionally excludes street addresses, latitude, longitude, and other precise location fields. NYC 311 records are reports of requests, not verified findings, and may contain reporting delays or duplicates. The public Socrata API requires no key for these read-only queries.
+
+## Run
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+## Quick start
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code, MCP Inspector, or another compatible MCP client.
+
+## Tools at a glance
+
+- `search_requests`: Search recent public NYC 311 requests using non-location-identifying fields. Addresses and coordinates are intentionally excluded.
+- `count_requests`: Count NYC 311 requests grouped by complaint type with optional date, borough, and agency filters.
+
+## Limits and privacy
+
+This project is intentionally narrow. It should be treated as a practical helper, not a complete certification or security audit. Check the implementation and the returned data before using it with sensitive material. No credentials are required unless the project explicitly says otherwise.
+
+## 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`.

package/dist/api.d.ts

@@ -0,0 +1,5 @@
+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;

package/dist/api.js

@@ -0,0 +1,64 @@
+const BASE = "https://data.cityofnewyork.us/resource/erm2-nwe9.json";
+const HEADERS = { "User-Agent": "mrfentmen-nyc311-mcp/1.0" };
+export class Nyc311Error extends Error {
+}
+function quote(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function validateDates(start, end) {
+    const parse = (value) => {
+        const date = new Date(`${value}T00:00:00Z`);
+        if (Number.isNaN(date.getTime()) || date.toISOString().slice(0, 10) !== value)
+            throw new Nyc311Error(`Invalid date: ${value}`);
+        return date;
+    };
+    if (start && end && parse(start) >= parse(end))
+        throw new Nyc311Error("start must be earlier than end");
+    if (start)
+        parse(start);
+    if (end)
+        parse(end);
+}
+function filters(complaintType, borough, agency, start, end) {
+    validateDates(start, end);
+    const result = [];
+    if (complaintType)
+        result.push(`complaint_type = ${quote(complaintType)}`);
+    if (borough)
+        result.push(`borough = ${quote(borough.toUpperCase())}`);
+    if (agency)
+        result.push(`agency = ${quote(agency.toUpperCase())}`);
+    if (start)
+        result.push(`created_date >= ${quote(start)}`);
+    if (end)
+        result.push(`created_date < ${quote(end)}`);
+    return result;
+}
+async function query(params) {
+    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 response.json();
+}
+export function searchRequests(complaintType, borough, agency, start, end, limit = 20) {
+    const where = filters(complaintType, borough, agency, start, end);
+    return query({
+        $select: "created_date,closed_date,agency,complaint_type,descriptor,borough,status",
+        $order: "created_date DESC",
+        $limit: String(limit),
+        ...(where.length ? { $where: where.join(" AND ") } : {}),
+    });
+}
+export function countRequests(complaintType, borough, agency, start, end, limit = 100) {
+    const where = filters(complaintType, borough, agency, start, end);
+    return query({
+        $select: "complaint_type,count(*) as total",
+        $group: "complaint_type",
+        $order: "total DESC",
+        $limit: String(limit),
+        ...(where.length ? { $where: where.join(" AND ") } : {}),
+    });
+}
+export function format(value) { return JSON.stringify(value, null, 2).slice(0, 16000); }

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,51 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { countRequests, format, searchRequests } 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 };
+const errorText = (error) => text(`Error: ${error instanceof Error ? error.message : String(error)}`);
+const date = z.string().regex(/^\\d{4}-\\d{2}-\\d{2}/).optional();
+export function createServer() {
+    const server = new McpServer({ name: "nyc311-mcp", version: "1.0.0" });
+    const filters = {
+        complaintType: z.string().max(120).optional(),
+        borough: z.enum(["MANHATTAN", "BRONX", "BROOKLYN", "QUEENS", "STATEN ISLAND"]).optional(),
+        agency: z.string().max(20).optional(),
+        start: date,
+        end: date,
+    };
+    server.registerTool("search_requests", {
+        title: "Search requests",
+        description: "Search recent public NYC 311 requests using non-location-identifying fields. Addresses and coordinates are intentionally excluded.",
+        inputSchema: z.object({
+            ...filters,
+            limit: z.number().int().min(1).max(50).default(20),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ complaintType, borough, agency, start, end, limit }) => {
+        try {
+            return text(format(await searchRequests(complaintType, borough, agency, start, end, limit)));
+        }
+        catch (error) {
+            return errorText(error);
+        }
+    });
+    server.registerTool("count_requests", {
+        title: "Count requests",
+        description: "Count NYC 311 requests grouped by complaint type with optional date, borough, and agency filters.",
+        inputSchema: z.object({
+            ...filters,
+            limit: z.number().int().min(1).max(100).default(50),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ complaintType, borough, agency, start, end, limit }) => {
+        try {
+            return text(format(await countRequests(complaintType, borough, agency, start, end, limit)));
+        }
+        catch (error) {
+            return errorText(error);
+        }
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "nyc311-mcp",
+  "version": "1.0.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/nyc311-mcp.git"
+  },
+  "bin": {
+    "nyc311-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "server.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "npm run build && node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "public-data",
+    "nyc311"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.mrfentmen/nyc311-mcp",
+  "description": "Use this MCP server to NYC 311 public service request search and aggregate civic data. Tools...",
+  "repository": {
+    "url": "https://github.com/mrfentmen/nyc311-mcp",
+    "source": "github"
+  },
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "nyc311-mcp",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}