@nightsquawktech/appfolio-mcp-server 0.0.1

package/dist/tools/list-endpoints.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { loadDbIndex } from "../catalog-db/endpoint-spec.js";
+const schema = z.object({
+    category: z
+        .string()
+        .optional()
+        .describe("Optional category filter (e.g. 'Accounting', 'Leasing', 'People', 'Properties', " +
+        "'Maintenance', 'Community Associations', 'Corporate Accounting', 'Custom Fields', 'System'). " +
+        "Call without args first to see all categories."),
+    resource: z
+        .string()
+        .optional()
+        .describe("Optional resource filter (e.g. 'bills', 'tenants', 'work_orders')."),
+    method: z
+        .string()
+        .optional()
+        .describe("Optional HTTP method filter: GET, POST, PATCH, PUT, or DELETE."),
+    reads_only: z
+        .boolean()
+        .optional()
+        .describe("If true, return only read (GET) endpoints."),
+});
+/**
+ * Lists available AppFolio Database API (v0) endpoints from the catalog.
+ * Lightweight discovery tool: returns operationId, method, path, category, and a
+ * one-line description per endpoint so the model can pick one, then call
+ * describe_endpoint for its full parameter spec.
+ */
+export const listEndpointsTool = {
+    name: "list_endpoints",
+    description: "List the available AppFolio Database API endpoints (operationId, method, path, " +
+        "category, description). Optionally filter by category, resource, method, or reads-only. " +
+        "Use this to discover which endpoint to use, then call describe_endpoint for its parameters " +
+        "and call_endpoint to execute it. This is the AppFolio v0 Database API (records/CRUD), " +
+        "distinct from the Reporting API (list_reports/run_report).",
+    schema,
+    handler: async ({ params }) => {
+        const index = loadDbIndex();
+        const category = params?.category;
+        const resource = params?.resource;
+        const method = params?.method?.toUpperCase();
+        const readsOnly = params?.reads_only;
+        let endpoints = index.endpoints;
+        if (category) {
+            const wanted = category.toLowerCase();
+            endpoints = endpoints.filter((e) => e.category.toLowerCase() === wanted);
+        }
+        if (resource) {
+            const wanted = resource.toLowerCase();
+            endpoints = endpoints.filter((e) => e.resource.toLowerCase() === wanted);
+        }
+        if (method)
+            endpoints = endpoints.filter((e) => e.method === method);
+        if (readsOnly)
+            endpoints = endpoints.filter((e) => !e.writeOperation);
+        const categories = [...new Set(index.endpoints.map((e) => e.category))].sort();
+        if ((category || resource || method) && endpoints.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No endpoints matched your filters. ` +
+                            `Available categories: ${categories.join(", ")}.`,
+                    },
+                ],
+            };
+        }
+        const payload = {
+            endpointCount: endpoints.length,
+            totalEndpoints: index.endpointCount,
+            baseUrl: index.baseUrl,
+            categories,
+            paginationParams: index.paginationParams,
+            endpoints: endpoints.map((e) => ({
+                operation_id: e.operationId,
+                method: e.method,
+                path: e.path,
+                name: e.name,
+                category: e.category,
+                resource: e.resource,
+                description: e.description,
+                writeOperation: e.writeOperation,
+                ...(e.deprecated ? { deprecated: true } : {}),
+            })),
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload) }],
+        };
+    },
+};

package/dist/tools/list-reports.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { loadIndex } from "../catalog/report-spec.js";
+const schema = z.object({
+    category: z
+        .string()
+        .optional()
+        .describe("Optional category filter (e.g. 'Financial', 'Leasing', 'Tenant'). " +
+        "Omit to list every report. Call without args first to see all categories."),
+});
+/**
+ * Lists available AppFolio reports from the catalog. Lightweight discovery tool:
+ * returns slug, name, category, and required filters per report so the model can
+ * pick one, then call describe_report for its full parameter spec.
+ */
+export const listReportsTool = {
+    name: "list_reports",
+    description: "List the available AppFolio reports (slug, name, category, required filters). " +
+        "Optionally filter by category. Use this to discover which report to run, then " +
+        "call describe_report for its parameters and run_report to execute it.",
+    schema,
+    handler: async ({ params }) => {
+        const index = loadIndex();
+        const category = params?.category;
+        let reports = index.reports;
+        if (category) {
+            const wanted = category.toLowerCase();
+            reports = reports.filter((r) => r.category.toLowerCase() === wanted);
+        }
+        const categories = [...new Set(index.reports.map((r) => r.category))].sort();
+        const payload = {
+            reportCount: reports.length,
+            totalReports: index.reportCount,
+            categories,
+            universalParameters: index.universalParameters,
+            reports: reports.map((r) => ({
+                report_name: r.slug,
+                name: r.name,
+                category: r.category,
+                description: r.description,
+                requiredFilters: r.requiredFilters,
+            })),
+        };
+        if (category && reports.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No reports found in category "${category}". ` +
+                            `Available categories: ${categories.join(", ")}.`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload) }],
+        };
+    },
+};

package/dist/tools/run-report.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { loadReportSpec, loadIndex, universalParameters } from "../catalog/report-spec.js";
+import { appfolioClient } from "../clients/appfolio-client.js";
+const schema = z.object({
+    report_name: z
+        .string()
+        .describe("The report slug to run, e.g. 'balance_sheet'. See list_reports / describe_report."),
+    filters: z
+        .record(z.any())
+        .optional()
+        .describe("Report-specific filters as a JSON object keyed by the parameter names from " +
+        "describe_report (e.g. { posted_on_to: '2024-12-31', properties: { properties_ids: ['123'] } }). " +
+        "Required filters must be included or the request is rejected."),
+    columns: z
+        .array(z.string())
+        .optional()
+        .describe("Optional subset of response columns to return. All columns are returned by default."),
+    paginate_results: z
+        .boolean()
+        .optional()
+        .describe("Default true (5,000 rows/page, auto-followed). Set false to return all rows as one array."),
+    page: z.number().optional().describe("Pagination page (advanced; usually handled automatically)."),
+    limit: z.number().optional().describe("Rows per page (advanced)."),
+});
+function errorText(text) {
+    return { content: [{ type: "text", text }] };
+}
+/**
+ * Executes an AppFolio report after validating the request against the catalog
+ * spec: the report must exist, all required filters must be present, and every
+ * supplied parameter must be a known filter for that report (or a universal
+ * pagination param). Enum values are advisory (see describe_report) and not hard
+ * enforced, to avoid rejecting valid inputs over doc-formatting quirks.
+ */
+export const runReportTool = {
+    name: "run_report",
+    description: "Run an AppFolio report and return its rows. Validates the report name, required " +
+        "filters, and parameter names against the report catalog before calling AppFolio. " +
+        "Use describe_report first to learn the exact filter keys for the report.",
+    schema,
+    handler: async ({ params }) => {
+        const reportName = params?.report_name;
+        const spec = loadReportSpec(reportName);
+        if (!spec) {
+            const known = loadIndex().reports.map((r) => r.slug);
+            const suggestions = known
+                .filter((s) => reportName && (s.includes(reportName) || reportName.includes(s)))
+                .slice(0, 5);
+            return errorText(`Unknown report "${reportName}". ` +
+                (suggestions.length ? `Did you mean: ${suggestions.join(", ")}? ` : "") +
+                `Call list_reports to see all ${known.length} reports.`);
+        }
+        // Assemble the request body from filters + pagination/column args.
+        const body = { ...(params?.filters ?? {}) };
+        if (params?.columns !== undefined)
+            body.columns = params.columns;
+        if (params?.paginate_results !== undefined)
+            body.paginate_results = params.paginate_results;
+        if (params?.page !== undefined)
+            body.page = params.page;
+        if (params?.limit !== undefined)
+            body.limit = params.limit;
+        // Reject unknown parameters early with a helpful list.
+        const allowed = new Set([
+            ...spec.parameters.map((p) => p.name),
+            ...universalParameters(),
+        ]);
+        const unknown = Object.keys(body).filter((k) => !allowed.has(k));
+        if (unknown.length > 0) {
+            return errorText(`Unknown parameter(s) for "${spec.slug}": ${unknown.join(", ")}. ` +
+                `Valid filters: ${spec.parameters.map((p) => p.name).join(", ")}. ` +
+                `Plus universal: ${universalParameters().join(", ")}. ` +
+                `Call describe_report("${spec.slug}") for details.`);
+        }
+        // Enforce required filters.
+        const missing = spec.requiredFilters.filter((rf) => {
+            const v = body[rf];
+            return v === undefined || v === null || (typeof v === "string" && v.trim() === "");
+        });
+        if (missing.length > 0) {
+            return errorText(`Missing required filter(s) for "${spec.slug}": ${missing.join(", ")}. ` +
+                `Call describe_report("${spec.slug}") to see their expected format.`);
+        }
+        // The client appends ".json" to the slug.
+        const response = await appfolioClient.runReport(spec.slug, body);
+        if (response.isError) {
+            return errorText(`Error running ${spec.slug}: ${response.error}`);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        report_name: spec.slug,
+                        rowCount: Array.isArray(response.result) ? response.result.length : 0,
+                        results: response.result,
+                    }),
+                },
+            ],
+        };
+    },
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@nightsquawktech/appfolio-mcp-server",
+  "version": "0.0.1",
+  "description": "MCP server for AppFolio Reporting API v2",
+  "license": "AGPL-3.0-only",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "COMMERCIAL.md"
+  ],
+  "scripts": {
+    "build": "tsc && shx mkdir -p dist/catalog && shx cp -r src/catalog/reports dist/catalog && shx cp src/catalog/index.json dist/catalog && shx mkdir -p dist/catalog-db && shx cp -r src/catalog-db/endpoints dist/catalog-db && shx cp src/catalog-db/index.json dist/catalog-db && shx chmod +x dist/*.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.0",
+    "@nightsquawktech/mcp-core": "^0.1.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2"
+  },
+  "author": "Kevin Reyes (NightSquawk Tech) <hello@nightsquawk.tech>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NightSquawk/appfolio-mcp-server.git"
+  },
+  "homepage": "https://github.com/NightSquawk/appfolio-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/NightSquawk/appfolio-mcp-server/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}