v1.4.0 — Connector improvements + production timeout fix

v1.4.0 — Reviewer compliance + production bug fix

This release addresses feedback from our external connector review process plus improvements surfaced during a related audit. It's a coordinated MCP-only release: no API or documentation changes ship alongside it. Everything is additive — existing tool inputs continue to work, existing tool return shapes gain new optional fields (_warnings, report_key on scan submission), no field names are removed or renamed.

Production bug fixed

Silent failures on long-running scan submissions are eliminated. A .includes('timeout') check in the scan-submission error path was missing the actual error string "Request timed out" (two words, not one). The effect was that scans that took longer than 15 seconds to submit — common on larger grid sizes or under normal queue load — surfaced as tool errors to the agent instead of the intended success-with-processing response. The agent had no signal that the scan was actually running. This bug was surfaced by a comprehensive audit triggered by external review feedback; the fix is a one-line regex change, shipped isolated as the first commit in this release so it can be cherry-picked to a hotfix if needed.

New capabilities

Eager scan submission now returns report_key immediately. The MCP now sends eager=1 to LF.api's run-scan endpoint, which shortens the server's completion-wait from 360 seconds to 20 seconds and always populates data.report_key in the response — even when the scan hasn't finished processing. Before: agents submitting a scan had to poll listLocalFalconScanReports repeatedly to discover the new report's key. After: the submission response carries the key directly, and the agent can immediately call getLocalFalconReport to check status. The MCP timeout was raised from 15s to 25s to keep a 5s margin over the server's 20s eager budget — this ensures the report_key is captured rather than lost to a network timeout fallback.

_warnings array surfaces unrecognized fieldmask entries. When a fieldmask request includes paths that don't resolve in the response (e.g., a typo, a stale field name, a guess), the MCP tool response now includes a _warnings array listing the unrecognized entries as human-readable messages: "Unknown field in fieldmask: <path>". Previously, such entries were silently dropped and the agent had no signal that its fieldmask was partially ignored. This surfaces information the API has been emitting via the response wrapper for some time; the MCP was unwrapping and discarding it.

Richer 4xx error messages. MCP errors on 4xx responses now include specific guidance per status code. A 404 becomes "Report not found. The reportKey may not exist, may have expired, or may belong to a different account. Verify the reportKey is correct." A 403 becomes "Access denied. This resource belongs to a different account, or the API key / OAuth token lacks permission." 401 and 429 have similarly specific messages. Non-JSON error bodies (some endpoints return plain text) are handled with a generic prefix and passthrough. The underlying server message is preserved as a (Server: ...) suffix on every case.

Input validation tightened

9 tool parameters that take URL-path identifiers now validate their inputs at the Zod schema layer before any network call:

• getLocalFalconReport.reportKey and 6 other reportKey parameters — require 15-character lowercase hex (e.g., ad412d968a25a84). Previously, empty strings silently degraded into list-endpoint calls.
• getLocalFalconGuardReport.placeId — requires non-empty. No regex because Place IDs span multiple formats (Google, Apple, brand).
• getLocalFalconKnowledgeBaseArticle.articleId — requires digits with optional KB prefix (70, KB70).

Malformed inputs now fail fast with a descriptive error before the API call.

Tool documentation overhaul

Tool descriptions have been rewritten against verified response shapes, with particular attention to the new insights.solv_competitors metrics from recent LF API work:

• getLocalFalconReport — full rewrite. Platform-specific response shapes documented explicitly (Maps scans return solv and an insights object with solv_competitors.{total, active}, osolv.{yours, top}, solv_distance.{yours, average}; AI scans return saiv and a sources array; unique_competitors is universal on both platform groups). Size hints added for agents on context-limited models (scan reports can be 100–300KB uncompressed). ai_analysis.summary called out as a surgical fieldmask alternative to the whole ai_analysis object (which is a structured {summary, problem, success, vulnerable, competitors, citations} object, not an HTML string).
• getLocalFalconCampaignReport — removes arp_move, atrp_move, solv_move from the recommended fieldmask. These delta fields appear on listLocalFalconCampaignReports items but not on this single-get endpoint. Documented the distinction inline.
• getLocalFalconCompetitorReport — recommended fieldmask split into Maps and AI variants (swap businesses.*.solv for businesses.*.saiv on AI). Documented the leaner per-competitor shape and possible empty-businesses case on AI scans.
• listLocalFalconReviewsAnalysisReports — corrected recommended fieldmask to reference review_date (the shipped field name) instead of date.
• getLocalFalconTrendReport, getLocalFalconLocationReport, getLocalFalconKeywordReport, getLocalFalconReviewsAnalysisReport — added stronger fieldmask-recommendation language with size rationale (e.g., reviews analysis reports can exceed 100KB given sentiment/topic breakdowns across up to 1M reviews).
• Shared fieldmask parameter description (19 tools) — replaced misleading "wildcards for arrays" example with explicit guidance covering the three cases: arrays (scans.*.arp), dicts of objects (places.*.solv), and dicts of scalars (rankings.by_arp — request by path alone; wildcard can't descend into scalar values). Folds in the "strongly recommended on every call" signal.
• Interpretation guidance — removed bullet points referencing fields that don't exist at any path (Opportunity SoLV, Competition SoLV as top-level metrics). Replaced with guidance that uses the real shipped insights.osolv.{yours, top} and insights.solv_competitors.{total, active}.

Acknowledgments

Thanks to the Local Falcon API team for the recent API-side work this release surfaces through the MCP: field_mask_warnings (enables the new _warnings array), structured 4xx status codes (enables the richer error messages), and the insights.solv_competitors metrics (reflected in the new tool description recipes).

Rollback plan

If v1.4.0 surfaces production issues, rollback is: (1) npm unpublish @local-falcon/mcp@1.4.0 --force to remove from registry, (2) git revert the merge commit on main to restore v1.3.1 code, (3) redeploy. Render auto-deploys on main push. Total rollback time ~5 minutes. No data migration, no schema changes, no external dependency changes — this is a pure MCP code release.

Full commit list

• fix: handle "timed out" and "timeout" error message variants in runLocalFalconScan
• feat: adopt eager scan submission to surface report_key immediately
• feat: preserve API wrapper siblings — surface _warnings and richer 4xx errors
• fix: align tool descriptions with actual API response shapes
• feat: tighten input schemas — fieldmask help-text + URL-path ID validation
• docs: strengthen fieldmask recommendation with size-aware guidance

v1.3.1

Fixes

• Credential management: Move OAuth client secret from hardcoded string to OAUTH_CLIENT_SECRET environment variable (#10)
• openWorldHint: Set openWorldHint: true on all 37 tools — server makes external API calls to api.localfalcon.com (#10)

Addresses Anthropic MCP Directory review blockers.

v1.3.0

Widget Polish, Session Recovery, OpenAI Metadata, Accessibility, Rate Limiting

Ported from mcplabs dev environment after full audit, fix, polish, and pre-flight verification cycles.

Changes

• HTTP rate limiting on MCP and auth endpoints
• readOnlyHint annotations on all write tools
• GET / returns 200 JSON (was 400)
• Session auto-recovery extended to GET handler
• Dark mode map noise suppression
• Font stack aligned to design system (SF Pro Text fallback)
• Text colors and borders aligned to design system
• Pin scaling based on grid size
• Distance banner dark mode variant
• ARIA accessibility labels
• OpenAI widget metadata (outputTemplate, widgetDescription, widgetCSP)
• Brand scan CSS grid fallback for 0,0 coordinates
• GAIO "no AI overview" prohibited icon
• Mobile detail panel scroll CSS
• Date format descriptions corrected to YYYY-MM-DD (ISO 8601)
• CORS wildcard documented

v1.2.1 — Remove built assets from npm package

Built widget files (dist/) are now excluded from the npm tarball. These files contain build-time environment variables (e.g., Google Maps API key) and should be built at deploy time by the hosting environment, not shipped in the npm package.

v1.2.0 — MCP Apps Interactive Widgets & ChatGPT Compatibility

What's New

Interactive Geo-Grid Heatmap Widget

• MCP Apps support via @modelcontextprotocol/ext-apps — getLocalFalconReport now renders an interactive Google Maps widget in supported clients (Claude, ChatGPT)
• Colored rank pins (green → yellow → red), clickable detail panels with business listings, ratings, reviews, and AI scrape content
• Built as a single-file HTML application with Vite and vite-plugin-singlefile

ChatGPT MCP Connector Compatibility

• OAuth 2.1 metadata updated to advertise refresh_token grant and offline_access scope
• Token endpoint returns full scope: "api offline_access" to prevent ChatGPT re-auth loops
• Widget sandbox domain configured for stable iframe origin
• Multi-tier tool result parsing handles ChatGPT's structuredContent.text and double-encoded content[0].text formats
• patchNullMeta workaround for MCP SDK _meta: null serialization issue

OAuth 2.1 Refresh Token Support

• Refresh tokens issued on every token exchange (30-day TTL, automatic rotation)
• refresh_token grant type fully implemented with API key re-validation
• Periodic cleanup of expired refresh tokens

Tool Annotations

• openWorldHint: false added to all 37 tools — signals that tools operate within the Local Falcon platform only
• Existing readOnlyHint and destructiveHint annotations preserved

Security

• HTML sanitizer for AI scrape content — allowlist of safe tags, attributes, and image domains
• Generic error messages in tool handlers — raw error.message no longer exposed to users
• Expanded CSP resourceDomains for AI scrape images (OpenAI, Foursquare, AWS)

Infrastructure

• build:ui script for building MCP App widgets
• vite.ui.config.ts with Google Maps API key injection at build time
• OpenAI domain verification token endpoint

v1.1.1

Fixes

• npm package cleanup — excluded build artifacts (.mcpb, bun.lock, .github/, nul) from npm tarball. Package size reduced from 7.7MB to 216KB.

v1.1.0

What's New

• Claude Code plugin structure — .claude-plugin/plugin.json and .mcp.json enable auto-discovery as a Claude Code plugin
• Local Visibility skill — added skills/local-visibility-skill/ with AI visibility & local SEO strategy guidance, metrics glossary, prompt templates, and platform analysis
• Skills directory rename — skill/ → skills/ to match Claude Code plugin conventions

Fixes

• Removed invalid giao platform from runLocalFalconScan Zod enum and tool description

v1.0.1

What's Changed

• Icons: Updated light-theme icons with white backgrounds (512px, 32px, 16px)
• README: Added npm version, Node.js, and TypeScript badges; clarified that end users only need Node.js and npm
• Acknowledgments: Added @modelcontextprotocol/sdk (Anthropic MCP SDK)
• CLAUDE.md: Added release/deployment docs, MCPB build steps, updated file reference
• MCPB: Rebuilt Desktop Extension bundle for v1.0.1

Install

One-click: Download local-falcon-mcp.mcpb below and open it in Claude Desktop.

npm:

npm i @local-falcon/mcp

Full Changelog: v1.0.0...v1.0.1

v1.0.0

Local Falcon MCP Server v1.0.0

First stable release of the Local Falcon MCP server for submission to Anthropic's Connector Directory.

What's New

• 37 MCP tools covering scan reports, trend analysis, campaign management, Falcon Guard monitoring, reviews analysis, competitor intelligence, and knowledge base access
• Full MCP tool annotations — all tools have readOnlyHint and destructiveHint annotations for safe auto-execution
• OAuth 2.1 support — Dynamic Client Registration (RFC 7591), PKCE enforcement, RFC 8414/9728 metadata endpoints
• Multiple transport modes — STDIO, SSE, Streamable HTTP
• 8 platform support — Google Maps, Apple Maps, Google AI Overviews, ChatGPT, Gemini, Grok, AI Mode, Immersive AI Overviews
• SKILL.md with 11 workflow patterns and 3 reference guides for AI client integration

Fixes in This Release

• Fixed environment variable name in README STDIO examples (LOCALFALCON_API_KEY → LOCAL_FALCON_API_KEY)
• Fixed broken bold markup in README SSE legacy note
• Added complete package.json metadata (author, repository, homepage, bugs, keywords)
• Removed debug test.ts from repo
• Expanded .npmignore to exclude internal files (_spec/, skill/, CLAUDE.md, Dockerfile)

Installation

See README.md for setup instructions via OAuth, Bearer Token, or STDIO.

npm i @local-falcon/mcp

v0.2.0

What's New

Major update bringing the npm package in sync with recent GitHub development. This release includes ~10 days of improvements:

• Enhanced tool descriptions with detailed usage guidance, recommended fieldmasks, and warnings
• Fieldmask support across all 20 get/list tools for controlling response size
• Automatic data_points stripping on trend and competitor reports to save context tokens
• MCP tool annotations (readOnlyHint, destructiveHint) for safer AI client auto-execution
• OAuth 2.1 improvements for remote transport modes (SSE, HTTP)
• CLAUDE.md added for comprehensive project documentation
• Automated npm publishing via GitHub Actions on release creation

Infrastructure

• Added .github/workflows/npm-publish.yml for automated npm publishing
• Future releases will automatically publish to npm — no more version drift