@vprop/mcp 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,379 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+const BASE_URL = process.env.VPROP_BASE_URL ?? "https://vprop.ai/api/v1";
+function getApiKey() {
+    const key = process.env.VPROP_API_KEY;
+    if (!key)
+        throw new Error("VPROP_API_KEY environment variable is required");
+    return key;
+}
+async function vpropFetch(path, options = {}) {
+    const { headers: extraHeaders, ...rest } = options;
+    const response = await fetch(`${BASE_URL}${path}`, {
+        ...rest,
+        headers: {
+            Authorization: `Bearer ${getApiKey()}`,
+            "Content-Type": "application/json",
+            ...extraHeaders,
+        },
+    });
+    if (response.status === 204)
+        return null;
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+        const msg = body?.error?.message ?? `HTTP ${response.status}`;
+        throw new Error(msg);
+    }
+    return body;
+}
+function toText(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+const CONTENT_TYPES = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+};
+async function uploadBuffer(uploadUrl, data, contentType) {
+    const res = await fetch(uploadUrl, {
+        method: "PUT",
+        headers: { "Content-Type": contentType },
+        body: data,
+    });
+    if (!res.ok)
+        throw new Error(`S3 PUT failed: HTTP ${res.status}`);
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Server
+// ────────────────────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "vprop",
+    version: "1.0.0",
+    description: "vProp Public API — create real-estate video projects from listings and agents. " +
+        "Typical flow: create_listing → upload_listing_image (10+ photos) → create_agent → " +
+        "upload_agent_photo → create_project → poll get_project_status → get_project (for video_url).",
+});
+// ── Voices ───────────────────────────────────────────────────────────────────
+server.registerTool("list_voices", {
+    description: "List all available narration voices. Use the returned `id` as `voice_id` when creating agents or projects.",
+}, async () => toText(await vpropFetch("/voices")));
+// ── BGMs ─────────────────────────────────────────────────────────────────────
+server.registerTool("list_bgms", {
+    description: "List all available background music tracks. Use the returned `id` as `bgm_id` when creating projects.",
+}, async () => toText(await vpropFetch("/bgms")));
+// ── Listings ─────────────────────────────────────────────────────────────────
+server.registerTool("create_listing", {
+    description: "Create a new property listing. Returns a listing ID (`lst_…`) used for image uploads and project creation.",
+    inputSchema: {
+        address: z.string().describe("Full US property address, e.g. '123 Main St, San Francisco, CA 94105' (required)"),
+        bedrooms: z.number().optional().describe("Number of bedrooms"),
+        bathrooms: z.number().optional().describe("Number of bathrooms"),
+        square_feet: z.number().optional().describe("Property size in square feet"),
+        price: z.number().optional().describe("Listing price in USD"),
+        year_built: z.number().optional().describe("Year the property was built"),
+        metadata: z.record(z.string(), z.unknown()).optional().describe("Arbitrary key-value metadata"),
+    },
+}, async ({ address, bedrooms, bathrooms, square_feet, price, year_built, metadata }) => {
+    const attributes = bedrooms !== undefined || bathrooms !== undefined || square_feet !== undefined || price !== undefined || year_built !== undefined
+        ? { bedrooms, bathrooms, square_feet, price, year_built }
+        : undefined;
+    return toText(await vpropFetch("/listings", {
+        method: "POST",
+        body: JSON.stringify({ address, attributes, metadata }),
+    }));
+});
+server.registerTool("get_listing", {
+    description: "Get full details of a listing by its ID.",
+    inputSchema: {
+        id: z.string().describe("Listing ID, e.g. 'lst_AbCdEfGhIjKl'"),
+    },
+}, async ({ id }) => toText(await vpropFetch(`/listings/${id}`)));
+server.registerTool("list_listings", {
+    description: "List all listings with cursor-based pagination.",
+    inputSchema: {
+        limit: z.number().int().min(1).max(100).optional().describe("Results per page (1–100, default 20)"),
+        cursor: z.string().optional().describe("Pagination cursor from the previous response's `next_cursor`"),
+    },
+}, async ({ limit, cursor }) => {
+    const params = new URLSearchParams();
+    if (limit !== undefined)
+        params.set("limit", String(limit));
+    if (cursor)
+        params.set("cursor", cursor);
+    const qs = params.size ? `?${params}` : "";
+    return toText(await vpropFetch(`/listings${qs}`));
+});
+server.registerTool("update_listing", {
+    description: "Update an existing listing's address, attributes, or metadata.",
+    inputSchema: {
+        id: z.string().describe("Listing ID to update"),
+        address: z.string().optional().describe("New property address"),
+        bedrooms: z.number().optional(),
+        bathrooms: z.number().optional(),
+        square_feet: z.number().optional(),
+        price: z.number().optional(),
+        year_built: z.number().optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+    },
+}, async ({ id, address, bedrooms, bathrooms, square_feet, price, year_built, metadata }) => {
+    const attributes = bedrooms !== undefined || bathrooms !== undefined || square_feet !== undefined || price !== undefined || year_built !== undefined
+        ? { bedrooms, bathrooms, square_feet, price, year_built }
+        : undefined;
+    return toText(await vpropFetch(`/listings/${id}`, {
+        method: "PATCH",
+        body: JSON.stringify({ address, attributes, metadata }),
+    }));
+});
+server.registerTool("delete_listing", {
+    description: "Permanently delete a listing and its images.",
+    inputSchema: {
+        id: z.string().describe("Listing ID to delete"),
+    },
+}, async ({ id }) => {
+    await vpropFetch(`/listings/${id}`, { method: "DELETE" });
+    return toText({ deleted: true, id });
+});
+server.registerTool("list_listing_images", {
+    description: "List images that have been uploaded to a listing.",
+    inputSchema: {
+        id: z.string().describe("Listing ID"),
+        limit: z.number().int().min(1).max(100).optional().describe("Results per page"),
+        cursor: z.string().optional().describe("Pagination cursor"),
+    },
+}, async ({ id, limit, cursor }) => {
+    const params = new URLSearchParams();
+    if (limit !== undefined)
+        params.set("limit", String(limit));
+    if (cursor)
+        params.set("cursor", cursor);
+    const qs = params.size ? `?${params}` : "";
+    return toText(await vpropFetch(`/listings/${id}/images${qs}`));
+});
+server.registerTool("upload_listing_image", {
+    description: "Upload a local image file (JPEG/PNG/WebP) to a listing. " +
+        "Gets a presigned URL then performs the binary PUT automatically. " +
+        "Minimum 10 images recommended for best video quality.",
+    inputSchema: {
+        listing_id: z.string().describe("Listing ID to attach the image to"),
+        file_path: z.string().describe("Absolute local path to the image file"),
+    },
+}, async ({ listing_id, file_path }) => {
+    const ext = extname(file_path).toLowerCase();
+    const content_type = CONTENT_TYPES[ext];
+    if (!content_type) {
+        throw new Error(`Unsupported extension '${ext}'. Use .jpg, .jpeg, .png, or .webp`);
+    }
+    const filename = file_path.split("/").pop() ?? "image.jpg";
+    // Read file before any API call — if the file is missing or unreadable
+    // we fail here without touching remote state.
+    const fileData = readFileSync(file_path);
+    const { upload_url, image_id, image_url, expires_at } = await vpropFetch(`/listings/${listing_id}/images/upload-url`, {
+        method: "POST",
+        body: JSON.stringify({ filename, content_type }),
+    });
+    // The backend already inserted a DB record. If the binary PUT fails,
+    // clean up the orphaned record so the listing doesn't end up with a
+    // ghost image that points to an empty S3 object.
+    try {
+        await uploadBuffer(upload_url, fileData, content_type);
+    }
+    catch (err) {
+        await vpropFetch(`/listings/${listing_id}/images/${image_id}`, {
+            method: "DELETE",
+        }).catch(() => { });
+        throw new Error(`Upload failed: ${err instanceof Error ? err.message : String(err)}. ` +
+            `The image record (${image_id}) has been cleaned up.`);
+    }
+    return toText({ image_id, image_url, expires_at });
+});
+server.registerTool("delete_listing_image", {
+    description: "Delete a specific image from a listing.",
+    inputSchema: {
+        listing_id: z.string().describe("Listing ID"),
+        image_id: z.string().describe("Image ID to delete (from list_listing_images)"),
+    },
+}, async ({ listing_id, image_id }) => {
+    await vpropFetch(`/listings/${listing_id}/images/${image_id}`, { method: "DELETE" });
+    return toText({ deleted: true, listing_id, image_id });
+});
+// ── Agents ───────────────────────────────────────────────────────────────────
+server.registerTool("create_agent", {
+    description: "Create a realtor agent profile used in video projects. Returns an agent ID (`agt_…`). " +
+        "After creation, call upload_agent_photo to add a headshot for the avatar feature.",
+    inputSchema: {
+        name: z.string().describe("Agent's full name (required)"),
+        email: z.string().email().optional().describe("Agent's email address"),
+        phone: z.string().optional().describe("Agent's phone number"),
+        voice_id: z.string().optional().describe("Default voice ID from list_voices (overridable per-project)"),
+        metadata: z.record(z.string(), z.unknown()).optional().describe("Arbitrary key-value metadata"),
+    },
+}, async ({ name, email, phone, voice_id, metadata }) => toText(await vpropFetch("/agents", {
+    method: "POST",
+    body: JSON.stringify({ name, email, phone, voice_id, metadata }),
+})));
+server.registerTool("get_agent", {
+    description: "Get full details of an agent by their ID.",
+    inputSchema: {
+        id: z.string().describe("Agent ID, e.g. 'agt_MnOpQrStUvWx'"),
+    },
+}, async ({ id }) => toText(await vpropFetch(`/agents/${id}`)));
+server.registerTool("list_agents", {
+    description: "List all agents with cursor-based pagination.",
+    inputSchema: {
+        limit: z.number().int().min(1).max(100).optional().describe("Results per page (1–100, default 20)"),
+        cursor: z.string().optional().describe("Pagination cursor"),
+    },
+}, async ({ limit, cursor }) => {
+    const params = new URLSearchParams();
+    if (limit !== undefined)
+        params.set("limit", String(limit));
+    if (cursor)
+        params.set("cursor", cursor);
+    const qs = params.size ? `?${params}` : "";
+    return toText(await vpropFetch(`/agents${qs}`));
+});
+server.registerTool("update_agent", {
+    description: "Update an existing agent's information.",
+    inputSchema: {
+        id: z.string().describe("Agent ID to update"),
+        name: z.string().optional(),
+        email: z.string().email().optional(),
+        phone: z.string().optional(),
+        voice_id: z.string().optional().describe("New default voice ID"),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+    },
+}, async ({ id, name, email, phone, voice_id, metadata }) => toText(await vpropFetch(`/agents/${id}`, {
+    method: "PATCH",
+    body: JSON.stringify({ name, email, phone, voice_id, metadata }),
+})));
+server.registerTool("delete_agent", {
+    description: "Delete an agent by their ID.",
+    inputSchema: {
+        id: z.string().describe("Agent ID to delete"),
+    },
+}, async ({ id }) => {
+    await vpropFetch(`/agents/${id}`, { method: "DELETE" });
+    return toText({ deleted: true, id });
+});
+server.registerTool("upload_agent_photo", {
+    description: "Upload a headshot photo for an agent (JPEG/PNG/WebP). " +
+        "Required for the avatar and lipsync features in video projects.",
+    inputSchema: {
+        agent_id: z.string().describe("Agent ID to attach the photo to"),
+        file_path: z.string().describe("Absolute local path to the photo file"),
+    },
+}, async ({ agent_id, file_path }) => {
+    const ext = extname(file_path).toLowerCase();
+    const content_type = CONTENT_TYPES[ext];
+    if (!content_type) {
+        throw new Error(`Unsupported extension '${ext}'. Use .jpg, .jpeg, .png, or .webp`);
+    }
+    const filename = file_path.split("/").pop() ?? "photo.jpg";
+    // Read file before any API call — the presigned-URL endpoint immediately
+    // stamps agents.photo in the DB, so a missing/unreadable file must be
+    // caught here before we mutate remote state.
+    const fileData = readFileSync(file_path);
+    const { upload_url, photo_url } = await vpropFetch(`/agents/${agent_id}/photo/upload-url`, {
+        method: "POST",
+        body: JSON.stringify({ filename, content_type }),
+    });
+    // agents.photo is now stamped. If PUT fails, no delete endpoint exists —
+    // the only recovery is re-calling this tool with a valid file.
+    try {
+        await uploadBuffer(upload_url, fileData, content_type);
+    }
+    catch (err) {
+        throw new Error(`Upload failed: ${err instanceof Error ? err.message : String(err)}. ` +
+            `The agent's photo URL is now broken. ` +
+            `Call upload_agent_photo again with a valid file to recover.`);
+    }
+    return toText({ photo_url });
+});
+// ── Projects ──────────────────────────────────────────────────────────────────
+server.registerTool("create_project", {
+    description: "Start a video generation project (async, returns immediately with status 'pending'). " +
+        "Poll get_project_status until 'completed', then call get_project to retrieve the video_url. " +
+        "Completion typically takes a few minutes.",
+    inputSchema: {
+        listing_id: z.string().describe("Listing ID (`lst_…`) with uploaded images"),
+        agent_id: z.string().describe("Agent ID (`agt_…`) to feature in the video"),
+        title: z.string().max(120).optional().describe("Video title shown in the intro scene (max 120 chars)"),
+        cta: z.string().max(120).optional().describe("Call-to-action text in the agent scene (default: 'Schedule a tour')"),
+        theme: z.enum(["modern", "classic", "bold", "elegant"]).optional().describe("Visual theme (default: modern)"),
+        resolution: z.enum(["portrait", "landscape"]).optional().describe("Video orientation (default: portrait/9:16)"),
+        caption: z.enum(["none", "keyword", "description"]).optional().describe("Caption style (default: keyword)"),
+        voice_id: z.string().optional().describe("Per-project voice override (from list_voices)"),
+        bgm_id: z.string().optional().describe("Background music ID (from list_bgms)"),
+        use_agent_avatar: z.boolean().optional().describe("Show animated agent avatar (default: true, needs agent photo)"),
+        use_lipsync: z.boolean().optional().describe("Lipsync the avatar (default: false)"),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+    },
+}, async ({ listing_id, agent_id, title, cta, theme, resolution, caption, voice_id, bgm_id, use_agent_avatar, use_lipsync, metadata, }) => {
+    const options = theme || resolution || caption || voice_id || bgm_id || use_agent_avatar !== undefined || use_lipsync !== undefined
+        ? { theme, resolution, caption, voice_id, bgm_id, use_agent_avatar, use_lipsync }
+        : undefined;
+    return toText(await vpropFetch("/projects", {
+        method: "POST",
+        headers: { "Idempotency-Key": randomUUID() },
+        body: JSON.stringify({ listing_id, agent_id, title, cta, options, metadata }),
+    }));
+});
+server.registerTool("get_project", {
+    description: "Get full project details. When status is 'completed', the response includes `video_url` and `thumbnail_url`.",
+    inputSchema: {
+        id: z.string().describe("Project ID (`proj_…`)"),
+    },
+}, async ({ id }) => toText(await vpropFetch(`/projects/${id}`)));
+server.registerTool("get_project_status", {
+    description: "Lightweight status check for a project. Returns one of: pending | processing | completed | failed. " +
+        "Use this to poll until completed, then call get_project for the video URL.",
+    inputSchema: {
+        id: z.string().describe("Project ID (`proj_…`)"),
+    },
+}, async ({ id }) => toText(await vpropFetch(`/projects/${id}/status`)));
+server.registerTool("list_projects", {
+    description: "List video projects with optional status filter and cursor pagination.",
+    inputSchema: {
+        status: z
+            .enum(["pending", "processing", "completed", "failed"])
+            .optional()
+            .describe("Filter by project status"),
+        limit: z.number().int().min(1).max(100).optional().describe("Results per page"),
+        cursor: z.string().optional().describe("Pagination cursor"),
+    },
+}, async ({ status, limit, cursor }) => {
+    const params = new URLSearchParams();
+    if (status)
+        params.set("status", status);
+    if (limit !== undefined)
+        params.set("limit", String(limit));
+    if (cursor)
+        params.set("cursor", cursor);
+    const qs = params.size ? `?${params}` : "";
+    return toText(await vpropFetch(`/projects${qs}`));
+});
+// ── Webhooks ──────────────────────────────────────────────────────────────────
+server.registerTool("register_webhook", {
+    description: "Register an HTTPS webhook URL to receive project lifecycle events. " +
+        "One webhook per API key is allowed (re-registering replaces the previous one). " +
+        "Note: GET/DELETE/rotate-secret webhook endpoints are not yet implemented in the API.",
+    inputSchema: {
+        url: z.string().url().describe("HTTPS endpoint that will receive POST requests"),
+        events: z
+            .array(z.enum(["project.created", "project.processing", "project.completed", "project.failed"]))
+            .min(1)
+            .describe("Event types to subscribe to"),
+    },
+}, async ({ url, events }) => toText(await vpropFetch("/webhooks", {
+    method: "POST",
+    body: JSON.stringify({ url, events }),
+})));
+// ── Start ─────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@vprop/mcp",
+  "version": "1.0.0",
+  "description": "MCP server for the vProp Public API — generate real-estate listing videos with AI",
+  "type": "module",
+  "bin": {
+    "vprop-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "dev": "node --experimental-strip-types src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "vprop",
+    "real-estate",
+    "ai",
+    "video"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5"
+  }
+}