@vprop/mcp 1.0.6 → 1.1.0

package/README.md

@@ -215,7 +215,15 @@ Any client that follows the [MCP specification](https://modelcontextprotocol.io)
 ### Webhooks
 | Tool | Description |
 |------|-------------|
-| `register_webhook` | Register an HTTPS URL to receive project events |
+| `register_webhook` | Register an HTTPS URL to receive project events (replaces any existing registration) |
+| `get_webhook` | Get the current webhook registration for this API key |
+| `delete_webhook` | Deactivate a webhook by its ID |
+| `rotate_webhook_secret` | Roll the HMAC signing secret for a webhook |
+
+### Usage
+| Tool | Description |
+|------|-------------|
+| `get_usage` | Get usage counts and credit balance for this API key |
 
 ## Example prompts
 
@@ -234,14 +242,19 @@ When calling `create_project`, you can customize:
 
 | Option | Values | Default |
 |--------|--------|---------|
-| `theme` | `modern` `classic` `bold` `elegant` | `modern` |
+| `theme` | `modern` `classic` `bold` `elegant` `luxe` `basic` `rosewood` `keystone` `pixel` `editorial` `sketch` | `modern` |
+| `background` | `black` `white` | theme default |
 | `resolution` | `portrait` (9:16) `landscape` (16:9) | `portrait` |
 | `caption` | `none` `keyword` `description` | `keyword` |
 | `language` | `en` `es` `ko` `zh-Hans` | `en` |
 | `voice_id` | ID from `list_voices` | agent default |
 | `bgm_id` | ID from `list_bgms` | theme default |
+| `background_music` | `true` `false` | `true` |
+| `narration_highlights` | free text (≤2000 chars) | — |
+| `word_highlight` | `true` `false` | `false` |
 | `use_agent_avatar` | `true` `false` | `true` |
 | `use_lipsync` | `true` `false` | `false` |
+| `display_info` | object — per-field booleans for agent card | platform defaults |
 
 ## Notes
 

package/dist/index.js

@@ -53,14 +53,15 @@ async function uploadBuffer(uploadUrl, data, contentType) {
 // ────────────────────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: "vprop",
-    version: "1.0.0",
+    version: "1.1.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.",
+    description: "List all available narration voices. Use the returned `id` as `voice_id` when creating agents or projects. " +
+        "Filter on `verified_languages` to find a voice that matches your project's `language` option.",
 }, async () => toText(await vpropFetch("/voices")));
 // ── BGMs ─────────────────────────────────────────────────────────────────────
 server.registerTool("list_bgms", {
@@ -68,23 +69,62 @@ server.registerTool("list_bgms", {
 }, 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.",
+    description: "Create a new property listing. Returns a listing ID (`lst_…`) used for image uploads and project creation. " +
+        "The server enriches the listing in parallel: an address-based property search (fills propertyType, lotSize, lat/long, etc.) " +
+        "and an LLM pass over the optional `options` free-form text. Merge precedence: explicit body fields > options-parsed > search.",
     inputSchema: {
-        address: z.string().describe("Full US property address, e.g. '123 Main St, San Francisco, CA 94105' (required)"),
+        address: z.string().describe("Full US street address, e.g. '123 Main St' (required)"),
+        city: z.string().optional().describe("City name (overrides address search and LLM parse)"),
+        state: z.string().optional().describe("State abbreviation, e.g. 'CA' (overrides address search and LLM parse)"),
+        zip_code: z.string().optional().describe("ZIP code (overrides address search and LLM parse)"),
         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"),
+        square_feet: z.number().optional().describe("Living area 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"),
+        property_status: z
+            .enum(["coming soon", "active", "under contract", "pending", "rent", "sold"])
+            .optional()
+            .describe("Listing status (default: active)"),
+        property_type: z
+            .enum([
+            "single family",
+            "townhome",
+            "condo",
+            "vacant land",
+            "multi family",
+            "manufactured",
+            "co-op",
+            "office",
+            "retail",
+            "industrial",
+            "hospitality",
+            "mixed-use",
+            "restaurant",
+            "other",
+        ])
+            .optional()
+            .describe("Property type (default: other)"),
+        listing_type: z
+            .enum(["sale", "rental"])
+            .optional()
+            .describe("Sale vs rental (default: sale)"),
+        metadata: z.record(z.string(), z.unknown()).optional().describe("Arbitrary key-value metadata (≤ 4KB)"),
+        options: z
+            .string()
+            .max(8192)
+            .optional()
+            .describe("Free-form natural language description of the listing " +
+            "(e.g. 'renovated kitchen, corner lot, HOA $250/month, listed for sale'). " +
+            "The server runs an LLM pass to extract additional fields. Explicit body fields always win."),
     },
-}, async ({ address, bedrooms, bathrooms, square_feet, price, year_built, metadata }) => {
+}, async ({ address, city, state, zip_code, bedrooms, bathrooms, square_feet, price, year_built, property_status, property_type, listing_type, metadata, options }) => {
     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 }),
+        body: JSON.stringify({ address, city, state, zip_code, attributes, property_status, property_type, listing_type, metadata, options }),
     }));
 });
 server.registerTool("get_listing", {
@@ -109,24 +149,52 @@ server.registerTool("list_listings", {
     return toText(await vpropFetch(`/listings${qs}`));
 });
 server.registerTool("update_listing", {
-    description: "Update an existing listing's address, attributes, or metadata.",
+    description: "Update an existing listing's fields. Only the fields you send are written; the rest keep their current value. " +
+        "The address-based property search is NOT re-run on update (updates are partner-driven corrections); " +
+        "the LLM `options` parse does run if `options` is provided.",
     inputSchema: {
         id: z.string().describe("Listing ID to update"),
-        address: z.string().optional().describe("New property address"),
+        address: z.string().optional(),
+        city: z.string().optional(),
+        state: z.string().optional(),
+        zip_code: z.string().optional(),
         bedrooms: z.number().optional(),
         bathrooms: z.number().optional(),
         square_feet: z.number().optional(),
         price: z.number().optional(),
         year_built: z.number().optional(),
+        property_status: z
+            .enum(["coming soon", "active", "under contract", "pending", "rent", "sold"])
+            .optional(),
+        property_type: z
+            .enum([
+            "single family",
+            "townhome",
+            "condo",
+            "vacant land",
+            "multi family",
+            "manufactured",
+            "co-op",
+            "office",
+            "retail",
+            "industrial",
+            "hospitality",
+            "mixed-use",
+            "restaurant",
+            "other",
+        ])
+            .optional(),
+        listing_type: z.enum(["sale", "rental"]).optional(),
         metadata: z.record(z.string(), z.unknown()).optional(),
+        options: z.string().max(8192).optional().describe("Free-form text for LLM field extraction"),
     },
-}, async ({ id, address, bedrooms, bathrooms, square_feet, price, year_built, metadata }) => {
+}, async ({ id, address, city, state, zip_code, bedrooms, bathrooms, square_feet, price, year_built, property_status, property_type, listing_type, metadata, options }) => {
     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 }),
+        body: JSON.stringify({ address, city, state, zip_code, attributes, property_status, property_type, listing_type, metadata, options }),
     }));
 });
 server.registerTool("delete_listing", {
@@ -209,17 +277,51 @@ server.registerTool("delete_listing_image", {
 // ── 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.",
+        "After creation, call upload_agent_photo to upload a local headshot file, or pass profile_photo_url if the photo is already hosted.",
     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"),
+        phone: z.string().optional().describe("Agent's direct phone number"),
+        profile_photo_url: z
+            .string()
+            .url()
+            .optional()
+            .describe("URL of an already-hosted headshot photo. " +
+            "Use this when you have a CDN/web URL. " +
+            "To upload a local file instead, call upload_agent_photo after creating the agent."),
+        license_number: z.string().optional().describe("Real-estate license / DRE / RECO number"),
+        website: z.string().optional().describe("Agent or business website URL"),
+        area: z.string().optional().describe("Service area or neighborhoods covered"),
+        team_name: z.string().optional().describe("Team name within the brokerage"),
+        company_name: z.string().optional().describe("Brokerage / company name"),
+        brokerage_phone: z
+            .string()
+            .optional()
+            .describe("Brokerage office phone (distinct from the agent's direct phone)"),
+        bio: z.string().optional().describe("Short agent biography"),
+        logo_url: z
+            .string()
+            .url()
+            .optional()
+            .describe("Agent logo image URL (shown on the agent card in the video)"),
+        team_logo_url: z.string().url().optional().describe("Team logo image URL"),
+        company_logo_url: z.string().url().optional().describe("Company / brokerage logo image URL"),
+        voice_id: z
+            .string()
+            .optional()
+            .describe("Default voice ID from list_voices. Used as the fallback when a project omits voice_id."),
+        metadata: z.record(z.string(), z.unknown()).optional().describe("Arbitrary key-value metadata (≤ 4KB)"),
+        options: z
+            .string()
+            .max(4096)
+            .optional()
+            .describe("Free-form natural language description of the agent " +
+            "(e.g. 'Team name is The Smith Group at Compass. DRE #01234567. Serves the SF Bay Area.'). " +
+            "The server runs an LLM pass to extract additional profile fields. Explicit body fields always win."),
     },
-}, async ({ name, email, phone, voice_id, metadata }) => toText(await vpropFetch("/agents", {
+}, async ({ name, email, phone, profile_photo_url, license_number, website, area, team_name, company_name, brokerage_phone, bio, logo_url, team_logo_url, company_logo_url, voice_id, metadata, options }) => toText(await vpropFetch("/agents", {
     method: "POST",
-    body: JSON.stringify({ name, email, phone, voice_id, metadata }),
+    body: JSON.stringify({ name, email, phone, profile_photo_url, license_number, website, area, team_name, company_name, brokerage_phone, bio, logo_url, team_logo_url, company_logo_url, voice_id, metadata, options }),
 })));
 server.registerTool("get_agent", {
     description: "Get full details of an agent by their ID.",
@@ -243,18 +345,34 @@ server.registerTool("list_agents", {
     return toText(await vpropFetch(`/agents${qs}`));
 });
 server.registerTool("update_agent", {
-    description: "Update an existing agent's information.",
+    description: "Update an existing agent's information. Only the fields you send are written; the rest keep their current value.",
     inputSchema: {
         id: z.string().describe("Agent ID to update"),
         name: z.string().optional(),
         email: z.string().email().optional(),
         phone: z.string().optional(),
+        profile_photo_url: z
+            .string()
+            .url()
+            .optional()
+            .describe("URL of an already-hosted headshot photo. To upload a local file instead, call upload_agent_photo."),
+        license_number: z.string().optional(),
+        website: z.string().optional(),
+        area: z.string().optional(),
+        team_name: z.string().optional(),
+        company_name: z.string().optional(),
+        brokerage_phone: z.string().optional(),
+        bio: z.string().optional(),
+        logo_url: z.string().url().optional(),
+        team_logo_url: z.string().url().optional(),
+        company_logo_url: z.string().url().optional(),
         voice_id: z.string().optional().describe("New default voice ID"),
         metadata: z.record(z.string(), z.unknown()).optional(),
+        options: z.string().max(4096).optional().describe("Free-form text for LLM field extraction"),
     },
-}, async ({ id, name, email, phone, voice_id, metadata }) => toText(await vpropFetch(`/agents/${id}`, {
+}, async ({ id, name, email, phone, profile_photo_url, license_number, website, area, team_name, company_name, brokerage_phone, bio, logo_url, team_logo_url, company_logo_url, voice_id, metadata, options }) => toText(await vpropFetch(`/agents/${id}`, {
     method: "PATCH",
-    body: JSON.stringify({ name, email, phone, voice_id, metadata }),
+    body: JSON.stringify({ name, email, phone, profile_photo_url, license_number, website, area, team_name, company_name, brokerage_phone, bio, logo_url, team_logo_url, company_logo_url, voice_id, metadata, options }),
 })));
 server.registerTool("delete_agent", {
     description: "Delete an agent by their ID.",
@@ -266,8 +384,9 @@ server.registerTool("delete_agent", {
     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.",
+    description: "Upload a headshot photo from a local file (JPEG/PNG/WebP) for an agent. " +
+        "Required for the avatar and lipsync features in video projects. " +
+        "If the photo is already hosted at a URL, pass `profile_photo_url` in create_agent or update_agent instead.",
     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"),
@@ -309,20 +428,84 @@ server.registerTool("create_project", {
         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)"),
-        language: z.enum(["en", "es", "ko", "zh-Hans"]).optional().describe("Narration + caption language (default: en). Use list_voices to find a voice whose verified_languages includes your chosen language."),
+        theme: z
+            .enum(["modern", "classic", "bold", "elegant", "luxe", "basic", "rosewood", "keystone", "pixel", "editorial", "sketch"])
+            .optional()
+            .describe("Visual theme (default: modern). `basic` is an unbranded template."),
+        background: z
+            .enum(["black", "white"])
+            .optional()
+            .describe("Scene background color. Defaults to the theme's natural background (white for `pixel`, black otherwise)."),
+        resolution: z
+            .enum(["portrait", "landscape"])
+            .optional()
+            .describe("Video orientation. portrait = 1080×1920 (Reels/TikTok); landscape = 1920×1080. Default: portrait."),
+        caption: z
+            .enum(["none", "keyword", "description"])
+            .optional()
+            .describe("Caption style. none = audio only; keyword = short pulses; description = full sentences. Default: keyword."),
+        language: z
+            .enum(["en", "es", "ko", "zh-Hans"])
+            .optional()
+            .describe("Narration + caption language (BCP-47). Default: en. " +
+            "Use list_voices and filter on verified_languages to find a matching voice."),
         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)"),
+        bgm_id: z.string().optional().describe("Background music ID (from list_bgms). Unknown IDs return 400."),
         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)"),
+        use_lipsync: z.boolean().optional().describe("Lipsync the avatar to the narration (default: false, adds render time)"),
+        background_music: z
+            .boolean()
+            .optional()
+            .describe("Play background music under the video. Default: true. Set false for a music-free render."),
+        narration_highlights: z
+            .string()
+            .max(2000)
+            .optional()
+            .describe("Free-text key points to emphasize in the narration script " +
+            "(e.g. 'newly renovated kitchen, corner lot, walking distance to BART'). " +
+            "The model weaves these into the relevant scenes."),
+        word_highlight: z
+            .boolean()
+            .optional()
+            .describe("Render gallery captions word-by-word, synced to the narration. " +
+            "Supported on all themes except `basic`. Default: false."),
+        display_info: z
+            .object({
+            name: z.boolean().optional(),
+            email: z.boolean().optional(),
+            logo: z.boolean().optional(),
+            contact: z.boolean().optional(),
+            license_number: z.boolean().optional(),
+            team_info: z.boolean().optional(),
+            company_info: z.boolean().optional(),
+            company_name: z.boolean().optional(),
+            brokerage_phone: z.boolean().optional(),
+        })
+            .optional()
+            .describe("Control which agent-card fields appear on screen. " +
+            "Each flag defaults to the platform default when omitted (most on; email off). " +
+            "Useful for MLS/compliance rules that require hiding specific fields."),
         metadata: z.record(z.string(), z.unknown()).optional(),
     },
-}, async ({ listing_id, agent_id, title, cta, theme, resolution, caption, language, voice_id, bgm_id, use_agent_avatar, use_lipsync, metadata, }) => {
-    const options = theme || resolution || caption || language || voice_id || bgm_id || use_agent_avatar !== undefined || use_lipsync !== undefined
-        ? { theme, resolution, caption, language, voice_id, bgm_id, use_agent_avatar, use_lipsync }
-        : undefined;
+}, async ({ listing_id, agent_id, title, cta, theme, background, resolution, caption, language, voice_id, bgm_id, use_agent_avatar, use_lipsync, background_music, narration_highlights, word_highlight, display_info, metadata, }) => {
+    // Build options object — use Object.values check so falsy booleans
+    // (background_music:false, word_highlight:false) are not silently dropped.
+    const optionFields = {
+        theme,
+        background,
+        resolution,
+        caption,
+        language,
+        voice_id,
+        bgm_id,
+        use_agent_avatar,
+        use_lipsync,
+        background_music,
+        narration_highlights,
+        word_highlight,
+        display_info,
+    };
+    const options = Object.values(optionFields).some((v) => v !== undefined) ? optionFields : undefined;
     return toText(await vpropFetch("/projects", {
         method: "POST",
         body: JSON.stringify({ listing_id, agent_id, title, cta, options, metadata }),
@@ -365,19 +548,71 @@ server.registerTool("list_projects", {
 // ── 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.",
+        "One active webhook per API key is allowed — re-registering replaces the previous one. " +
+        "The response includes a `secret` used to verify the `X-VProp-Signature` HMAC on each delivery; " +
+        "it is returned only once, so store it immediately. " +
+        "Use get_webhook to inspect the current registration, delete_webhook to stop deliveries, " +
+        "and rotate_webhook_secret to roll the signing secret.",
     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"),
+            .optional()
+            .describe("Event types to subscribe to. Omit to subscribe to all events."),
     },
 }, async ({ url, events }) => toText(await vpropFetch("/webhooks", {
     method: "POST",
     body: JSON.stringify({ url, events }),
 })));
+server.registerTool("get_webhook", {
+    description: "Get the current webhook registration for this API key. " +
+        "The signing secret is NOT returned here (it is shown only once, at registration or after rotate_webhook_secret). " +
+        "Returns 404 if no webhook is registered.",
+}, async () => toText(await vpropFetch("/webhooks")));
+server.registerTool("delete_webhook", {
+    description: "Deactivate (soft-delete) a webhook by its ID. After this, no further events are delivered. " +
+        "Idempotent-ish: a second delete of the same ID returns 404 (already inactive). " +
+        "Use get_webhook to find the current webhook ID.",
+    inputSchema: {
+        id: z.string().describe("Webhook ID (UUID, from register_webhook or get_webhook)"),
+    },
+}, async ({ id }) => toText(await vpropFetch(`/webhooks/${id}`, { method: "DELETE" })));
+server.registerTool("rotate_webhook_secret", {
+    description: "Issue a new HMAC signing secret for an existing webhook, keeping its URL and events unchanged. " +
+        "The new `secret` is returned once and the previous secret is immediately invalidated. " +
+        "Deliveries sent between rotation and your partner updating their stored secret will fail signature verification " +
+        "(they will be retried by the server). " +
+        "Use get_webhook to find the current webhook ID.",
+    inputSchema: {
+        id: z.string().describe("Webhook ID (UUID, from register_webhook or get_webhook)"),
+    },
+}, async ({ id }) => toText(await vpropFetch(`/webhooks/${id}/rotate-secret`, { method: "POST" })));
+// ── Usage ─────────────────────────────────────────────────────────────────────
+server.registerTool("get_usage", {
+    description: "Get this API key's usage statistics and credit balance. " +
+        "Returns counts of projects, listings, and agents created, plus credits consumed, over a time window. " +
+        "For prepaid keys, also returns the team's current `credit_balance`. " +
+        "Defaults to the last 30 days when `from`/`to` are omitted.",
+    inputSchema: {
+        from: z
+            .string()
+            .optional()
+            .describe("Start of the reporting window, ISO 8601 (e.g. '2026-06-01T00:00:00Z'). Default: 30 days ago."),
+        to: z
+            .string()
+            .optional()
+            .describe("End of the reporting window, ISO 8601. Default: now."),
+    },
+}, async ({ from, to }) => {
+    const params = new URLSearchParams();
+    if (from)
+        params.set("from", from);
+    if (to)
+        params.set("to", to);
+    const qs = params.size ? `?${params}` : "";
+    return toText(await vpropFetch(`/usage${qs}`));
+});
 // ── Start ─────────────────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vprop/mcp",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "MCP server for the vProp Public API — generate real-estate listing videos with AI",
   "type": "module",
   "bin": {