MCP PropTech

Instructions

Implementation Reference

• src/mcp-server/tools/get-open-tickets.ts:47-60 (handler)

  The handleGetOpenTickets function is the main handler that executes the tool logic. It queries the ticket store with input filters and returns filtered tickets along with total and filtered counts.

  export function handleGetOpenTickets(
    input: GetOpenTicketsInput
  ): GetOpenTicketsOutput {
    const allNonClosed = ticketStore.query({ status: "all" }).filter(
      (t) => t.status !== "closed"
    );
    const filtered = ticketStore.query(input);
  
    return {
      tickets: filtered,
      total: allNonClosed.length,
      filtered: filtered.length,
    };
  }

• src/mcp-server/tools/get-open-tickets.ts:15-43 (schema)

  The GetOpenTicketsSchema is a Zod schema defining input validation for the tool. It specifies optional filters: status (enum), priority (enum), category (enum), propertyId (string), and limit (number 1-100).

  export const GetOpenTicketsSchema = z.object({
    status: z
      .enum(["open", "in_progress", "awaiting_tenant", "escalated", "resolved", "closed", "all"])
      .optional()
      .describe(
        "Filter by ticket status. Omit to return all non-resolved/non-closed tickets."
      ),
    priority: z
      .enum(["low", "medium", "high", "emergency"])
      .optional()
      .describe("Filter to a specific priority level."),
    category: z
      .enum(["plumbing", "electrical", "hvac", "appliance", "structural", "pest", "general"])
      .optional()
      .describe("Filter by maintenance category / trade."),
    propertyId: z
      .string()
      .optional()
      .describe("Filter to tickets for a specific property (use property ID)."),
    limit: z
      .number()
      .int()
      .min(1)
      .max(100)
      .optional()
      .describe("Maximum number of tickets to return (default: all matching)."),
  });
  
  export type GetOpenTicketsInput = z.infer<typeof GetOpenTicketsSchema>;

• src/mcp-server/index.ts:49-69 (registration)

  Tool registration using server.tool() that registers 'get_open_tickets' with the MCP server. Includes description, schema binding, and async handler wrapper that returns JSON-formatted results.

  // ── Tool: get_open_tickets ────────────────────────────────────────────────────
  
  server.tool(
    "get_open_tickets",
    "Retrieves maintenance tickets from the property management system. " +
    "Filters by status (default: all non-resolved), priority, category, and property. " +
    "Returns tickets sorted by priority (emergency first) then recency.",
    GetOpenTicketsSchema.shape,
    async (input) => {
      const result = handleGetOpenTickets(input);
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    }
  );

• src/data/tickets-store.ts:23-67 (helper)

  The TicketStore.query method is a supporting utility that filters tickets by status, priority, category, and propertyId. It sorts results by priority (emergency first) then by recency, and applies optional limit.

  query(filters: GetOpenTicketsInput): MaintenanceTicket[] {
    let results = Array.from(this.tickets.values());
  
    if (filters.status && filters.status !== "all") {
      results = results.filter((t) => t.status === filters.status);
    } else if (!filters.status) {
      // default: exclude resolved/closed
      results = results.filter(
        (t) => t.status !== "resolved" && t.status !== "closed"
      );
    }
  
    if (filters.priority) {
      results = results.filter((t) => t.priority === filters.priority);
    }
  
    if (filters.category) {
      results = results.filter((t) => t.category === filters.category);
    }
  
    if (filters.propertyId) {
      results = results.filter(
        (t) => t.property.id === filters.propertyId
      );
    }
  
    // sort: emergency → high → medium → low, then newest first
    const priorityOrder: Record<TicketPriority, number> = {
      emergency: 0,
      high: 1,
      medium: 2,
      low: 3,
    };
    results.sort((a, b) => {
      const pd = priorityOrder[a.priority] - priorityOrder[b.priority];
      if (pd !== 0) return pd;
      return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
    });
  
    if (filters.limit) {
      results = results.slice(0, filters.limit);
    }
  
    return results;
  }

• src/types.ts:75-87 (schema)

  TypeScript interfaces GetOpenTicketsInput and GetOpenTicketsOutput define the type shapes for the tool's input parameters and output structure (tickets array, total count, filtered count).

  export interface GetOpenTicketsInput {
    status?: TicketStatus | "all";
    priority?: TicketPriority;
    category?: MaintenanceCategory;
    propertyId?: string;
    limit?: number;
  }
  
  export interface GetOpenTicketsOutput {
    tickets: MaintenanceTicket[];
    total: number;
    filtered: number;
  }