@lanten-ai/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# @lanten-ai/mcp-server
+
+An [MCP](https://modelcontextprotocol.io) server that connects AI assistants to the [Lanten](https://lanten.co) property management API. Use it with Claude, Cursor, Zed, or any MCP-compatible client to manage tenants, units, and work orders using natural language.
+
+## Quick start
+
+1. **Get an API key** — in your Lanten dashboard go to **Settings → Developers** and create a key.
+
+2. **Add to your MCP client config:**
+
+```json
+{
+  "mcpServers": {
+    "lanten": {
+      "command": "npx",
+      "args": ["-y", "@lanten-ai/mcp-server"],
+      "env": {
+        "LANTEN_API_KEY": "lk_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+For **Claude Desktop** this file lives at:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+For **Claude Code** run: `claude mcp add lanten -e LANTEN_API_KEY=lk_your_key -- npx -y @lanten-ai/mcp-server`
+
+3. **Restart your client** and start chatting:
+
+> *"List all open work orders for Flat 4, 12 Oak Street"*
+> *"Create a new tenant: Jane Smith, jane@example.com, assign her to unit abc-123"*
+> *"Mark work order WO-214 as completed"*
+
+---
+
+## Available tools
+
+### Tenants
+
+| Tool | Description |
+|---|---|
+| `list_tenants` | List tenants with optional search and pagination |
+| `get_tenant` | Get a single tenant by ID |
+| `create_tenant` | Create a tenant, optionally linked to a unit |
+| `update_tenant` | Update tenant fields (partial update) |
+| `delete_tenant` | Permanently delete a tenant |
+
+### Units
+
+| Tool | Description |
+|---|---|
+| `list_units` | List property units with optional address search |
+| `get_unit` | Get a single unit by ID |
+| `create_unit` | Create a property unit |
+| `update_unit` | Update unit fields (partial update) |
+| `delete_unit` | Permanently delete a unit |
+
+### Work Orders
+
+| Tool | Description |
+|---|---|
+| `list_work_orders` | List work orders; filter by status, priority, tenant, or unit |
+| `get_work_order` | Get a single work order by ID |
+| `create_work_order` | Create a work order linked to a tenant/unit |
+| `update_work_order` | Update a work order (status, priority, etc.) |
+| `delete_work_order` | Permanently delete a work order |
+
+**Priority levels:** `0` Emergency · `1` High · `2` Medium · `3` Low
+**Statuses:** `reported` · `in_progress` · `completed` · `cancelled`
+
+---
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `LANTEN_API_KEY` | ✅ | Your API key from Settings → Developers |
+| `LANTEN_API_URL` | — | Override the base URL (e.g. for self-hosted instances). Defaults to `https://app.lanten.co/api/open/v1` |
+
+---
+
+## Developing locally
+
+```bash
+git clone https://github.com/lanten/mcp-server
+cd mcp-server
+npm install
+npm run build
+
+# Test with the MCP Inspector
+LANTEN_API_KEY=lk_your_key npm run inspector
+```

package/build/client.js

@@ -0,0 +1,36 @@
+export class LantenClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    async request(method, path, options = {}) {
+        let url = `${this.baseUrl}${path}`;
+        if (options.query) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(options.query)) {
+                if (value !== undefined && value !== '') {
+                    params.set(key, String(value));
+                }
+            }
+            const qs = params.toString();
+            if (qs)
+                url += `?${qs}`;
+        }
+        const res = await fetch(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+        });
+        const json = (await res.json());
+        if (!res.ok) {
+            const message = typeof json.error === 'string' ? json.error : `HTTP ${res.status} ${res.statusText}`;
+            throw new Error(message);
+        }
+        return json;
+    }
+}

package/build/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { LantenClient } from './client.js';
+import { registerTenantTools } from './tools/tenants.js';
+import { registerUnitTools } from './tools/units.js';
+import { registerWorkOrderTools } from './tools/work-orders.js';
+const apiKey = process.env.LANTEN_API_KEY;
+if (!apiKey) {
+    console.error('Error: LANTEN_API_KEY environment variable is required.');
+    console.error('Get an API key from your Lanten dashboard: Settings → Developers');
+    process.exit(1);
+}
+const baseUrl = (process.env.LANTEN_API_URL ?? 'https://app.lanten.co/api/open/v1').replace(/\/$/, '');
+const client = new LantenClient(baseUrl, apiKey);
+const server = new McpServer({
+    name: 'lanten',
+    version: '0.1.0',
+});
+registerTenantTools(server, client);
+registerUnitTools(server, client);
+registerWorkOrderTools(server, client);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/build/tools/tenants.js

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+export function registerTenantTools(server, client) {
+    // ── List ────────────────────────────────────────────────────────────────────
+    server.registerTool('list_tenants', {
+        description: 'List tenants for the account. Supports free-text search across name, email, phone, and unit address. Returns paginated results.',
+        inputSchema: {
+            search: z.string().optional().describe('Search across name, email, phone, unit address'),
+            page: z.number().int().min(1).optional().default(1).describe('Page number (default 1)'),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .default(20)
+                .describe('Results per page (max 50, default 20)'),
+        },
+    }, async ({ search, page, pageSize }) => {
+        try {
+            const result = await client.request('GET', '/tenants', {
+                query: { search, page, pageSize },
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    // ── Get ─────────────────────────────────────────────────────────────────────
+    server.registerTool('get_tenant', {
+        description: 'Get a single tenant by ID, including their linked units.',
+        inputSchema: {
+            id: z.string().uuid().describe('Tenant UUID'),
+        },
+    }, async ({ id }) => {
+        try {
+            const result = await client.request('GET', `/tenants/${id}`);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    // ── Create ──────────────────────────────────────────────────────────────────
+    server.registerTool('create_tenant', {
+        description: 'Create a new tenant. Optionally assign them to an existing unit.',
+        inputSchema: {
+            firstName: z.string().min(1).max(160).describe('First name'),
+            lastName: z.string().min(1).max(160).describe('Last name'),
+            email: z.string().email().optional().describe('Email address'),
+            phoneNumber: z.string().optional().describe('Phone number'),
+            notes: z.string().optional().describe('Internal notes'),
+            unitId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe('UUID of an existing unit to assign this tenant to'),
+        },
+    }, async ({ firstName, lastName, email, phoneNumber, notes, unitId }) => {
+        try {
+            const result = await client.request('POST', '/tenants', {
+                body: { firstName, lastName, email, phoneNumber, notes, unitId },
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    // ── Update ──────────────────────────────────────────────────────────────────
+    server.registerTool('update_tenant', {
+        description: 'Update an existing tenant. Only supplied fields are changed.',
+        inputSchema: {
+            id: z.string().uuid().describe('Tenant UUID'),
+            firstName: z.string().min(1).max(160).optional().describe('Updated first name'),
+            lastName: z.string().min(1).max(160).optional().describe('Updated last name'),
+            email: z.string().email().nullable().optional().describe('Updated email (null to clear)'),
+            phoneNumber: z
+                .string()
+                .nullable()
+                .optional()
+                .describe('Updated phone number (null to clear)'),
+            notes: z.string().nullable().optional().describe('Updated notes (null to clear)'),
+        },
+    }, async ({ id, ...fields }) => {
+        try {
+            const result = await client.request('PUT', `/tenants/${id}`, { body: fields });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    // ── Delete ──────────────────────────────────────────────────────────────────
+    server.registerTool('delete_tenant', {
+        description: 'Permanently delete a tenant. This cannot be undone.',
+        inputSchema: {
+            id: z.string().uuid().describe('Tenant UUID'),
+        },
+    }, async ({ id }) => {
+        try {
+            const result = await client.request('DELETE', `/tenants/${id}`);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/units.js

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+export function registerUnitTools(server, client) {
+    // ── List ────────────────────────────────────────────────────────────────────
+    server.registerTool('list_units', {
+        description: 'List property units for the account. Supports address search. Returns paginated results including current tenants.',
+        inputSchema: {
+            search: z.string().optional().describe('Search by address'),
+            page: z.number().int().min(1).optional().default(1).describe('Page number (default 1)'),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .default(20)
+                .describe('Results per page (max 50, default 20)'),
+        },
+    }, async ({ search, page, pageSize }) => {
+        try {
+            const result = await client.request('GET', '/units', {
+                query: { search, page, pageSize },
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    // ── Get ─────────────────────────────────────────────────────────────────────
+    server.registerTool('get_unit', {
+        description: 'Get a single property unit by ID, including current tenants.',
+        inputSchema: {
+            id: z.string().uuid().describe('Unit UUID'),
+        },
+    }, async ({ id }) => {
+        try {
+            const result = await client.request('GET', `/units/${id}`);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    // ── Create ──────────────────────────────────────────────────────────────────
+    server.registerTool('create_unit', {
+        description: 'Create a new property unit.',
+        inputSchema: {
+            addressLine1: z.string().min(1).max(260).describe('Street address line 1'),
+            addressLine2: z
+                .string()
+                .max(260)
+                .optional()
+                .describe('Street address line 2 (flat number, etc.)'),
+            city: z.string().min(1).max(160).describe('City or town'),
+            county: z.string().max(160).optional().describe('County or province'),
+            country: z.string().min(1).max(160).describe('Country'),
+            postcode: z.string().min(1).max(80).describe('Postal / zip code'),
+            area: z.string().max(160).optional().describe('Area or region label (e.g. "North Zone")'),
+        },
+    }, async ({ addressLine1, addressLine2, city, county, country, postcode, area }) => {
+        try {
+            const result = await client.request('POST', '/units', {
+                body: { addressLine1, addressLine2, city, county, country, postcode, area },
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    // ── Update ──────────────────────────────────────────────────────────────────
+    server.registerTool('update_unit', {
+        description: 'Update an existing property unit. Only supplied fields are changed.',
+        inputSchema: {
+            id: z.string().uuid().describe('Unit UUID'),
+            addressLine1: z.string().min(1).max(260).optional().describe('Updated street address'),
+            addressLine2: z
+                .string()
+                .max(260)
+                .nullable()
+                .optional()
+                .describe('Updated address line 2 (null to clear)'),
+            city: z.string().min(1).max(160).optional().describe('Updated city'),
+            county: z.string().max(160).optional().describe('Updated county'),
+            country: z.string().min(1).max(160).optional().describe('Updated country'),
+            postcode: z.string().min(1).max(80).optional().describe('Updated postcode'),
+            area: z.string().max(160).nullable().optional().describe('Updated area (null to clear)'),
+        },
+    }, async ({ id, ...fields }) => {
+        try {
+            const result = await client.request('PUT', `/units/${id}`, { body: fields });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    // ── Delete ──────────────────────────────────────────────────────────────────
+    server.registerTool('delete_unit', {
+        description: 'Permanently delete a property unit. This cannot be undone.',
+        inputSchema: {
+            id: z.string().uuid().describe('Unit UUID'),
+        },
+    }, async ({ id }) => {
+        try {
+            const result = await client.request('DELETE', `/units/${id}`);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/work-orders.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+const STATUS = z
+    .enum(['reported', 'in_progress', 'completed', 'cancelled'])
+    .describe('Work order status');
+const PRIORITY = z
+    .enum(['0', '1', '2', '3'])
+    .describe('Priority: 0 = Emergency, 1 = High, 2 = Medium, 3 = Low');
+export function registerWorkOrderTools(server, client) {
+    // ── List ────────────────────────────────────────────────────────────────────
+    server.registerTool('list_work_orders', {
+        description: 'List work orders (maintenance issues) for the account. Filter by status, priority, tenant, or unit. Supports search by title or code.',
+        inputSchema: {
+            search: z.string().optional().describe('Search by title or work order code (e.g. WO-101)'),
+            status: STATUS.optional(),
+            priority: PRIORITY.optional(),
+            tenantId: z.string().uuid().optional().describe('Filter by tenant UUID'),
+            unitId: z.string().uuid().optional().describe('Filter by unit UUID'),
+            page: z.number().int().min(1).optional().default(1).describe('Page number (default 1)'),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .default(20)
+                .describe('Results per page (max 50, default 20)'),
+        },
+    }, async ({ search, status, priority, tenantId, unitId, page, pageSize }) => {
+        try {
+            const result = await client.request('GET', '/work-orders', {
+                query: { search, status, priority, tenantId, unitId, page, pageSize },
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    // ── Get ─────────────────────────────────────────────────────────────────────
+    server.registerTool('get_work_order', {
+        description: 'Get a single work order by ID, including tenant, unit, and attachments.',
+        inputSchema: {
+            id: z.string().uuid().describe('Work order UUID'),
+        },
+    }, async ({ id }) => {
+        try {
+            const result = await client.request('GET', `/work-orders/${id}`);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    // ── Create ──────────────────────────────────────────────────────────────────
+    server.registerTool('create_work_order', {
+        description: 'Create a new work order (maintenance issue). Optionally link to a tenant and/or unit.',
+        inputSchema: {
+            title: z.string().min(1).max(260).describe('Short title describing the issue'),
+            description: z.string().min(1).describe('Full description of the issue'),
+            priority: PRIORITY.optional().default('2'),
+            tenantId: z.string().uuid().optional().describe('UUID of the tenant who reported it'),
+            unitId: z.string().uuid().optional().describe('UUID of the property unit affected'),
+            availability: z
+                .string()
+                .max(260)
+                .optional()
+                .describe("Free-text tenant availability window (e.g. 'weekday mornings')"),
+        },
+    }, async ({ title, description, priority, tenantId, unitId, availability }) => {
+        try {
+            const result = await client.request('POST', '/work-orders', {
+                body: { title, description, priority, tenantId, unitId, availability },
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    // ── Update ──────────────────────────────────────────────────────────────────
+    server.registerTool('update_work_order', {
+        description: 'Update an existing work order. Only supplied fields are changed. Setting status to "completed" automatically records the resolved time.',
+        inputSchema: {
+            id: z.string().uuid().describe('Work order UUID'),
+            title: z.string().min(1).max(260).optional().describe('Updated title'),
+            description: z.string().min(1).optional().describe('Updated description'),
+            status: STATUS.optional(),
+            priority: PRIORITY.optional(),
+            tenantId: z
+                .string()
+                .uuid()
+                .nullable()
+                .optional()
+                .describe('Updated tenant UUID (null to unlink)'),
+            unitId: z
+                .string()
+                .uuid()
+                .nullable()
+                .optional()
+                .describe('Updated unit UUID (null to unlink)'),
+            availability: z.string().max(260).optional().describe('Updated availability window'),
+        },
+    }, async ({ id, ...fields }) => {
+        try {
+            const result = await client.request('PUT', `/work-orders/${id}`, { body: fields });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+    // ── Delete ──────────────────────────────────────────────────────────────────
+    server.registerTool('delete_work_order', {
+        description: 'Permanently delete a work order. This cannot be undone.',
+        inputSchema: {
+            id: z.string().uuid().describe('Work order UUID'),
+        },
+    }, async ({ id }) => {
+        try {
+            const result = await client.request('DELETE', `/work-orders/${id}`);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Error: ${err.message}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@lanten-ai/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for the Lanten property management API",
+  "type": "module",
+  "bin": {
+    "lanten-mcp": "build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "dev": "tsc --watch",
+    "inspector": "npx @modelcontextprotocol/inspector node ./build/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}