@nightsquawktech/appfolio-mcp-server 0.0.1

package/dist/clients/appfolio-client.js

@@ -0,0 +1,131 @@
+import { formatError } from "@nightsquawktech/mcp-core/catalog";
+const RATE_LIMIT_MAX = 7;
+const RATE_LIMIT_WINDOW_MS = 15000;
+export class AppfolioClient {
+    constructor() {
+        this.vhost = null;
+        this.clientId = null;
+        this.clientSecret = null;
+        this.initialized = false;
+        this.requestTimestamps = [];
+    }
+    /**
+     * Lazily reads env vars on first API call, so import-time errors
+     * don't crash the process before the MCP server can report them.
+     */
+    ensureInitialized() {
+        if (this.initialized)
+            return;
+        const missing = [];
+        const vhost = process.env.APPFOLIO_VHOST;
+        const clientId = process.env.APPFOLIO_CLIENT_ID;
+        const clientSecret = process.env.APPFOLIO_CLIENT_SECRET;
+        if (!vhost)
+            missing.push("APPFOLIO_VHOST");
+        if (!clientId)
+            missing.push("APPFOLIO_CLIENT_ID");
+        if (!clientSecret)
+            missing.push("APPFOLIO_CLIENT_SECRET");
+        if (missing.length > 0) {
+            throw new Error(`Missing required environment variables: ${missing.join(", ")}`);
+        }
+        this.vhost = vhost;
+        this.clientId = clientId;
+        this.clientSecret = clientSecret;
+        this.initialized = true;
+    }
+    /**
+     * Waits if necessary to respect the 7-requests-per-15-seconds rate limit.
+     * Pagination URL fetches should NOT call this — they are exempt from rate limits.
+     */
+    async waitForRateLimit() {
+        const now = Date.now();
+        // Remove timestamps older than the window
+        this.requestTimestamps = this.requestTimestamps.filter((t) => now - t < RATE_LIMIT_WINDOW_MS);
+        if (this.requestTimestamps.length >= RATE_LIMIT_MAX) {
+            const oldest = this.requestTimestamps[0];
+            const waitMs = RATE_LIMIT_WINDOW_MS - (now - oldest) + 50; // +50ms buffer
+            if (waitMs > 0) {
+                await new Promise((resolve) => setTimeout(resolve, waitMs));
+            }
+            // Clean up again after waiting
+            const afterWait = Date.now();
+            this.requestTimestamps = this.requestTimestamps.filter((t) => afterWait - t < RATE_LIMIT_WINDOW_MS);
+        }
+        this.requestTimestamps.push(Date.now());
+    }
+    getAuthHeader() {
+        const credentials = Buffer.from(`${this.clientId}:${this.clientSecret}`).toString("base64");
+        return `Basic ${credentials}`;
+    }
+    getBaseUrl(endpoint) {
+        return `https://${this.vhost}.appfolio.com/api/v2/reports/${endpoint}.json`;
+    }
+    /**
+     * Run an AppFolio report. Handles rate limiting and auto-pagination.
+     * Returns all results aggregated across pages.
+     */
+    async runReport(endpoint, params) {
+        try {
+            this.ensureInitialized();
+            // Initial request (rate-limited)
+            await this.waitForRateLimit();
+            const url = this.getBaseUrl(endpoint);
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: this.getAuthHeader(),
+                },
+                body: JSON.stringify(params),
+            });
+            if (!response.ok) {
+                const body = await response.text();
+                return {
+                    result: null,
+                    isError: true,
+                    error: `HTTP ${response.status}: ${body}`,
+                };
+            }
+            const data = await response.json();
+            // If paginate_results=false, the API returns a plain array
+            if (Array.isArray(data)) {
+                return { result: data, isError: false, error: null };
+            }
+            // Paginated response: { results: [...], next_page_url?: "..." }
+            let allResults = data.results || [];
+            let nextPageUrl = data.next_page_url;
+            // Auto-follow pagination (these URLs bypass rate limits)
+            while (nextPageUrl) {
+                const pageResponse = await fetch(nextPageUrl, {
+                    method: "GET",
+                    headers: {
+                        Authorization: this.getAuthHeader(),
+                    },
+                });
+                if (!pageResponse.ok) {
+                    const body = await pageResponse.text();
+                    return {
+                        result: null,
+                        isError: true,
+                        error: `Pagination HTTP ${pageResponse.status}: ${body}`,
+                    };
+                }
+                const pageData = await pageResponse.json();
+                if (Array.isArray(pageData)) {
+                    allResults = allResults.concat(pageData);
+                    nextPageUrl = undefined;
+                }
+                else {
+                    allResults = allResults.concat(pageData.results || []);
+                    nextPageUrl = pageData.next_page_url;
+                }
+            }
+            return { result: allResults, isError: false, error: null };
+        }
+        catch (error) {
+            return { result: null, isError: true, error: formatError(error) };
+        }
+    }
+}
+export const appfolioClient = new AppfolioClient();

package/dist/clients/appfolio-db-client.js

@@ -0,0 +1,186 @@
+import { formatError } from "@nightsquawktech/mcp-core/catalog";
+const BASE_URL = "https://api.appfolio.com/api/v0";
+// Documented global rate limits per credential set: 8/sec, 256/min, 4096/hour.
+const RATE_WINDOWS = [
+    { max: 8, ms: 1000 },
+    { max: 256, ms: 60000 },
+    { max: 4096, ms: 3600000 },
+];
+const MAX_429_RETRIES = 4;
+export class AppfolioDbClient {
+    constructor() {
+        this.clientId = null;
+        this.clientSecret = null;
+        this.developerId = null;
+        this.initialized = false;
+        this.requestTimestamps = [];
+    }
+    /**
+     * Lazily reads env vars on first API call, so import-time errors don't crash
+     * the process before the MCP server can report them.
+     */
+    ensureInitialized() {
+        if (this.initialized)
+            return;
+        const missing = [];
+        const clientId = process.env.APPFOLIO_DB_CLIENT_ID;
+        const clientSecret = process.env.APPFOLIO_DB_CLIENT_SECRET;
+        const developerId = process.env.APPFOLIO_DB_DEVELOPER_ID;
+        if (!clientId)
+            missing.push("APPFOLIO_DB_CLIENT_ID");
+        if (!clientSecret)
+            missing.push("APPFOLIO_DB_CLIENT_SECRET");
+        if (!developerId)
+            missing.push("APPFOLIO_DB_DEVELOPER_ID");
+        if (missing.length > 0) {
+            throw new Error(`Missing required environment variables: ${missing.join(", ")}`);
+        }
+        this.clientId = clientId;
+        this.clientSecret = clientSecret;
+        this.developerId = developerId;
+        this.initialized = true;
+    }
+    /** Waits if necessary to respect all three documented rate-limit windows. */
+    async waitForRateLimit() {
+        // Prune timestamps older than the longest window.
+        const longest = RATE_WINDOWS[RATE_WINDOWS.length - 1].ms;
+        let now = Date.now();
+        this.requestTimestamps = this.requestTimestamps.filter((t) => now - t < longest);
+        // For each window, if we're at the cap, wait until the oldest in-window request ages out.
+        // Loop because waiting for one window may still leave another saturated.
+        for (let guard = 0; guard < RATE_WINDOWS.length * 2; guard++) {
+            now = Date.now();
+            let waitMs = 0;
+            for (const w of RATE_WINDOWS) {
+                const inWindow = this.requestTimestamps.filter((t) => now - t < w.ms);
+                if (inWindow.length >= w.max) {
+                    const oldest = inWindow[0];
+                    waitMs = Math.max(waitMs, w.ms - (now - oldest) + 50);
+                }
+            }
+            if (waitMs <= 0)
+                break;
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+            const after = Date.now();
+            this.requestTimestamps = this.requestTimestamps.filter((t) => after - t < longest);
+        }
+        this.requestTimestamps.push(Date.now());
+    }
+    getHeaders(hasBody) {
+        const credentials = Buffer.from(`${this.clientId}:${this.clientSecret}`).toString("base64");
+        const headers = {
+            Authorization: `Basic ${credentials}`,
+            "X-AppFolio-Developer-ID": this.developerId,
+        };
+        if (hasBody)
+            headers["Content-Type"] = "application/json";
+        return headers;
+    }
+    /** Substitute {param} placeholders in the path; URL-encode each value. */
+    buildPath(path, pathParams) {
+        return path.replace(/\{([^}]+)\}/g, (_, key) => {
+            const v = pathParams?.[key];
+            if (v === undefined || v === null || v === "") {
+                throw new Error(`Missing path parameter "${key}" for "${path}"`);
+            }
+            return encodeURIComponent(String(v));
+        });
+    }
+    buildQuery(opts) {
+        const parts = [];
+        if (opts.filters) {
+            for (const [k, v] of Object.entries(opts.filters)) {
+                if (v === undefined || v === null)
+                    continue;
+                // Allow callers to pass either "Id" or "filters[Id]".
+                const key = /^filters\[/.test(k) ? k : `filters[${k}]`;
+                const val = Array.isArray(v) ? v.join(",") : String(v);
+                parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(val)}`);
+            }
+        }
+        if (opts.query) {
+            for (const [k, v] of Object.entries(opts.query)) {
+                if (v === undefined || v === null)
+                    continue;
+                parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+            }
+        }
+        if (opts.page?.number !== undefined)
+            parts.push(`page[number]=${encodeURIComponent(String(opts.page.number))}`);
+        if (opts.page?.size !== undefined)
+            parts.push(`page[size]=${encodeURIComponent(String(opts.page.size))}`);
+        return parts.length ? `?${parts.join("&")}` : "";
+    }
+    /** One fetch with rate limiting + Retry-After-aware 429 retries. */
+    async fetchWithRetry(url, init) {
+        for (let attempt = 0;; attempt++) {
+            await this.waitForRateLimit();
+            const response = await fetch(url, init);
+            if (response.status === 429 && attempt < MAX_429_RETRIES) {
+                const retryAfter = parseInt(response.headers.get("Retry-After") || "1", 10);
+                const waitMs = (Number.isFinite(retryAfter) ? retryAfter : 1) * 1000 + 100;
+                await new Promise((resolve) => setTimeout(resolve, waitMs));
+                continue;
+            }
+            return response;
+        }
+    }
+    /**
+     * Execute an AppFolio Database API request. Handles auth, rate limiting,
+     * 429 Retry-After, and (for GET) auto-pagination via next_page_path.
+     */
+    async request(method, path, opts = {}) {
+        try {
+            this.ensureInitialized();
+            const resolvedPath = this.buildPath(path, opts.pathParams);
+            const hasBody = opts.body !== undefined && method !== "GET";
+            const url = `${BASE_URL}${resolvedPath}${this.buildQuery(opts)}`;
+            const response = await this.fetchWithRetry(url, {
+                method,
+                headers: this.getHeaders(hasBody),
+                body: hasBody ? JSON.stringify(opts.body) : undefined,
+            });
+            if (!response.ok) {
+                const errBody = await response.text();
+                return { result: null, isError: true, error: `HTTP ${response.status}: ${errBody}` };
+            }
+            // DELETE / 204 responses may have no body.
+            const text = await response.text();
+            const data = text ? JSON.parse(text) : null;
+            // Non-paginated (writes, single-record GETs, or pagination disabled): return as-is.
+            const paginate = opts.paginate !== false;
+            if (method !== "GET" ||
+                !paginate ||
+                !data ||
+                typeof data !== "object" ||
+                !("data" in data)) {
+                return { result: data, isError: false, error: null };
+            }
+            // Paginated GET: aggregate `data` arrays across next_page_path links.
+            let allData = Array.isArray(data.data) ? data.data : [];
+            let nextPath = data.next_page_path || undefined;
+            while (nextPath) {
+                const nextUrl = nextPath.startsWith("http")
+                    ? nextPath
+                    : `https://api.appfolio.com${nextPath}`;
+                const pageResp = await this.fetchWithRetry(nextUrl, {
+                    method: "GET",
+                    headers: this.getHeaders(false),
+                });
+                if (!pageResp.ok) {
+                    const errBody = await pageResp.text();
+                    return { result: null, isError: true, error: `Pagination HTTP ${pageResp.status}: ${errBody}` };
+                }
+                const pageText = await pageResp.text();
+                const pageData = pageText ? JSON.parse(pageText) : {};
+                allData = allData.concat(Array.isArray(pageData.data) ? pageData.data : []);
+                nextPath = pageData.next_page_path || undefined;
+            }
+            return { result: { data: allData }, isError: false, error: null };
+        }
+        catch (error) {
+            return { result: null, isError: true, error: formatError(error) };
+        }
+    }
+}
+export const appfolioDbClient = new AppfolioDbClient();

package/dist/helpers/register-db-tools.js

@@ -0,0 +1,27 @@
+import { RegisterTool } from "@nightsquawktech/mcp-core/catalog";
+import { listEndpointsTool } from "../tools/list-endpoints.js";
+import { describeEndpointTool } from "../tools/describe-endpoint.js";
+import { callEndpointTool } from "../tools/call-endpoint.js";
+import { loadDbIndex } from "../catalog-db/endpoint-spec.js";
+/**
+ * Registers the consolidated AppFolio Database API (v0) tools with the MCP server.
+ *
+ * Like the Reporting API tools, we expose three catalog-backed tools instead of
+ * one tool per endpoint (~156 tools = heavy context cost and poor tool selection):
+ *   - list_endpoints      discover endpoints by category / resource / method
+ *   - describe_endpoint   full parameter + body spec for one endpoint
+ *   - call_endpoint       validate against the catalog spec, then execute
+ *
+ * Boot-time sanity check: the catalog index must load and be non-empty, so a
+ * missing/uncopied catalog fails fast at startup rather than on first tool call.
+ */
+export function registerAllDbTools(server) {
+    const index = loadDbIndex();
+    if (!index.endpoints || index.endpoints.length === 0) {
+        throw new Error("Database API catalog is empty or missing — expected src/catalog-db/index.json with endpoints. " +
+            "Did the build copy the catalog into dist/? Run `node scripts/assemble-catalog-db.mjs` to regenerate it.");
+    }
+    RegisterTool(server, listEndpointsTool);
+    RegisterTool(server, describeEndpointTool);
+    RegisterTool(server, callEndpointTool);
+}

package/dist/helpers/register-report-tools.js

@@ -0,0 +1,27 @@
+import { RegisterTool } from "@nightsquawktech/mcp-core/catalog";
+import { listReportsTool } from "../tools/list-reports.js";
+import { describeReportTool } from "../tools/describe-report.js";
+import { runReportTool } from "../tools/run-report.js";
+import { loadIndex } from "../catalog/report-spec.js";
+/**
+ * Registers the consolidated AppFolio report tools with the MCP server.
+ *
+ * Instead of one tool per endpoint (~137 tools = heavy context cost and poor
+ * tool selection), we expose three tools backed by the report catalog:
+ *   - list_reports      discover reports by category
+ *   - describe_report   full parameter spec for one report
+ *   - run_report        validate against the catalog spec, then execute
+ *
+ * Boot-time sanity check: the catalog index must load and be non-empty, so a
+ * missing/uncopied catalog fails fast at startup rather than on first tool call.
+ */
+export function registerAllReportTools(server) {
+    const index = loadIndex();
+    if (!index.reports || index.reports.length === 0) {
+        throw new Error("Report catalog is empty or missing — expected src/catalog/index.json with reports. " +
+            "Did the build copy the catalog into dist/?");
+    }
+    RegisterTool(server, listReportsTool);
+    RegisterTool(server, describeReportTool);
+    RegisterTool(server, runReportTool);
+}

package/dist/index.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { AppfolioMCPServer } from "./server/appfolio-mcp-server.js";
+import { registerAllReportTools } from "./helpers/register-report-tools.js";
+import { registerAllDbTools } from "./helpers/register-db-tools.js";
+const server = AppfolioMCPServer.GetServer();
+registerAllReportTools(server);
+registerAllDbTools(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/server/appfolio-mcp-server.js

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export class AppfolioMCPServer {
+    constructor() { }
+    static GetServer() {
+        if (AppfolioMCPServer.instance === null) {
+            AppfolioMCPServer.instance = new McpServer({
+                name: "AppFolio MCP Server",
+                version: "0.0.1",
+            }, {
+                capabilities: {
+                    tools: {},
+                },
+            });
+        }
+        return AppfolioMCPServer.instance;
+    }
+}
+AppfolioMCPServer.instance = null;

package/dist/tools/call-endpoint.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { loadEndpointSpec, loadDbIndex } from "../catalog-db/endpoint-spec.js";
+import { appfolioDbClient } from "../clients/appfolio-db-client.js";
+const schema = z.object({
+    operation_id: z
+        .string()
+        .describe("The endpoint operationId to call, e.g. 'get_tenants' or 'post_bills'. See list_endpoints / describe_endpoint."),
+    path_params: z
+        .record(z.any())
+        .optional()
+        .describe("Values for {param} placeholders in the path, e.g. { billId: '1abc...' } for /bills/{billId}."),
+    filters: z
+        .record(z.any())
+        .optional()
+        .describe("GET filter params keyed by filter name (the 'filters[...]' wrapper is added automatically), " +
+        "e.g. { LastUpdatedAtFrom: '2020-01-01T00:00:00Z', Id: 'uuid,uuid' }. Arrays are comma-joined."),
+    query: z
+        .record(z.any())
+        .optional()
+        .describe("Additional raw query params (rare; most filtering goes through `filters`)."),
+    body: z
+        .any()
+        .optional()
+        .describe("JSON request body for write operations (POST/PATCH/PUT). See describe_endpoint for the schema."),
+    page: z
+        .object({ number: z.number().optional(), size: z.number().optional() })
+        .optional()
+        .describe("Pagination for GET list endpoints: { number, size }. Default size is 1000."),
+    paginate_results: z
+        .boolean()
+        .optional()
+        .describe("GET only. Default true: follow next_page_path and aggregate all rows. Set false for a single page."),
+});
+function errorText(text) {
+    return { content: [{ type: "text", text }] };
+}
+/**
+ * Executes an AppFolio Database API request after validating against the catalog
+ * spec: the endpoint must exist and all required path params must be present.
+ * Query filters are advisory (the reference rarely enumerates them all), so
+ * unknown filters are NOT rejected. Read and write operations both execute
+ * (no write gate, per configuration).
+ */
+export const callEndpointTool = {
+    name: "call_endpoint",
+    description: "Call an AppFolio Database API endpoint and return its JSON response. Validates the " +
+        "operationId and required path params against the catalog before calling AppFolio, then " +
+        "executes (GET reads are auto-paginated; POST/PATCH/PUT/DELETE writes execute live against " +
+        "your AppFolio database). Use describe_endpoint first to learn the exact params and body.",
+    schema,
+    handler: async ({ params }) => {
+        const operationId = params?.operation_id;
+        const spec = loadEndpointSpec(operationId);
+        if (!spec) {
+            const known = loadDbIndex().endpoints.map((e) => e.operationId);
+            const suggestions = known
+                .filter((id) => operationId && (id.includes(operationId) || operationId.includes(id)))
+                .slice(0, 5);
+            return errorText(`Unknown endpoint "${operationId}". ` +
+                (suggestions.length ? `Did you mean: ${suggestions.join(", ")}? ` : "") +
+                `Call list_endpoints to see all ${known.length} endpoints.`);
+        }
+        // Enforce required path params (hard — the URL can't be built without them).
+        const required = (spec.pathParams ?? []).filter((p) => p.required !== false);
+        const provided = params?.path_params ?? {};
+        const missing = required.filter((p) => {
+            const v = provided[p.name];
+            return v === undefined || v === null || (typeof v === "string" && v.trim() === "");
+        });
+        if (missing.length > 0) {
+            return errorText(`Missing required path parameter(s) for "${spec.operationId}" (${spec.method} ${spec.path}): ` +
+                `${missing.map((p) => p.name).join(", ")}. Call describe_endpoint("${spec.operationId}") for details.`);
+        }
+        // Guard: a write body was supplied to a GET (likely a mistake).
+        if (spec.method === "GET" && params?.body !== undefined) {
+            return errorText(`"${spec.operationId}" is a GET endpoint and does not accept a body. ` +
+                `Use "filters" for query criteria.`);
+        }
+        const response = await appfolioDbClient.request(spec.method, spec.path, {
+            pathParams: provided,
+            filters: params?.filters,
+            query: params?.query,
+            body: params?.body,
+            page: params?.page,
+            paginate: params?.paginate_results,
+        });
+        if (response.isError) {
+            return errorText(`Error calling ${spec.operationId} (${spec.method} ${spec.path}): ${response.error}`);
+        }
+        const result = response.result;
+        const rowCount = result && typeof result === "object" && Array.isArray(result.data)
+            ? result.data.length
+            : undefined;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        operation_id: spec.operationId,
+                        method: spec.method,
+                        path: spec.path,
+                        ...(rowCount !== undefined ? { rowCount } : {}),
+                        result,
+                    }),
+                },
+            ],
+        };
+    },
+};

package/dist/tools/describe-endpoint.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { loadEndpointSpec, loadDbIndex } from "../catalog-db/endpoint-spec.js";
+const schema = z.object({
+    operation_id: z
+        .string()
+        .describe("The endpoint operationId, e.g. 'get_tenants' or 'post_bills'. See list_endpoints."),
+});
+/**
+ * Returns the full spec for one Database API endpoint: HTTP method, path, path
+ * params, query filters (for GET), the request body schema with nested
+ * attributes (for writes), response fields, and a request sample. The model
+ * calls this just before call_endpoint so it sends the exact parameters expected.
+ */
+export const describeEndpointTool = {
+    name: "describe_endpoint",
+    description: "Get the full specification for a single AppFolio Database API endpoint: HTTP method, " +
+        "path and path params, query filters (GET), request body schema with nested attributes " +
+        "(writes), response fields, and a request sample. Call this before call_endpoint to know " +
+        "exactly which parameters to pass.",
+    schema,
+    handler: async ({ params }) => {
+        const operationId = params?.operation_id;
+        const spec = loadEndpointSpec(operationId);
+        if (!spec) {
+            const known = loadDbIndex().endpoints.map((e) => e.operationId);
+            const suggestions = known
+                .filter((id) => operationId && (id.includes(operationId) || operationId.includes(id)))
+                .slice(0, 5);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Unknown endpoint "${operationId}". ` +
+                            (suggestions.length ? `Did you mean: ${suggestions.join(", ")}? ` : "") +
+                            `Call list_endpoints to see all ${known.length} endpoints.`,
+                    },
+                ],
+            };
+        }
+        const payload = {
+            operation_id: spec.operationId,
+            name: spec.name,
+            method: spec.method,
+            path: spec.path,
+            description: spec.description,
+            writeOperation: spec.writeOperation,
+            pagination: !!spec.pagination,
+            ...(spec.deprecated ? { deprecated: true } : {}),
+            pathParams: spec.pathParams ?? [],
+            queryFilters: spec.queryFilters ?? [],
+            ...(spec.requestBody ? { requestBody: spec.requestBody } : {}),
+            responseFields: spec.responseFields ?? [],
+            paginationParams: spec.pagination ? loadDbIndex().paginationParams : [],
+            requestSample: spec.requestSample,
+            note: "Query filters are advisory — AppFolio's reference often does not enumerate every " +
+                "filter, so call_endpoint does not reject unknown filters. Most GET list endpoints " +
+                "require at least a filters[Id] or filters[LastUpdatedAtFrom] value.",
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload) }],
+        };
+    },
+};

package/dist/tools/describe-report.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { loadReportSpec, loadIndex, universalParameters } from "../catalog/report-spec.js";
+const schema = z.object({
+    report_name: z
+        .string()
+        .describe("The report slug, e.g. 'balance_sheet' or 'rent_roll'. See list_reports."),
+});
+/**
+ * Returns the full parameter spec for one report: every filter with its type,
+ * whether it's required, allowed enum values, defaults, nested object attributes,
+ * the response columns, and a request sample. The model calls this just before
+ * run_report so it sends the exact parameter keys this report expects.
+ */
+export const describeReportTool = {
+    name: "describe_report",
+    description: "Get the full parameter specification for a single AppFolio report: required and " +
+        "optional filters, types, enums, defaults, nested attributes, and response columns. " +
+        "Call this before run_report to know exactly which parameters to pass.",
+    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 {
+                content: [
+                    {
+                        type: "text",
+                        text: `Unknown report "${reportName}". ` +
+                            (suggestions.length
+                                ? `Did you mean: ${suggestions.join(", ")}? `
+                                : "") +
+                            `Call list_reports to see all ${known.length} reports.`,
+                    },
+                ],
+            };
+        }
+        const payload = {
+            report_name: spec.slug,
+            name: spec.name,
+            description: spec.description,
+            requiredFilters: spec.requiredFilters,
+            parameters: spec.parameters,
+            universalParameters: universalParameters(),
+            responseColumns: spec.responseColumns,
+            requestSample: spec.requestSample,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload) }],
+        };
+    },
+};