mcp: Instructions file for Claude Code

CLAUDE.md — @local-falcon/mcp

Project Overview

This is the Local Falcon MCP Server (@local-falcon/mcp), a Model Context Protocol server that wraps the Local Falcon API. It enables AI agents to run geo-grid rank tracking scans, retrieve reports, manage campaigns, monitor Google Business Profiles, and analyze competitive positioning across AI search platforms, Google Maps, and Apple Maps.

Package: @local-falcon/mcp (npm) Version: 1.4.18 License: MIT Runtime: Node.js 18+ Language: TypeScript (strict mode)

Architecture

index.ts          → Entry point. Transport selection (STDIO, SSE, HTTP), session management, OAuth 2.1
server.ts         → MCP tool registrations. Exports getServer() with session-selected tool registration
localfalcon.ts    → API client layer. All fetch functions, rate limiting, retry logic, timeout handling
oauth/            → OAuth 2.1 authorization server (routes, provider, config, state/client stores)

Key Design Patterns

• server.ts exports a single getServer(sessionMapping) function that creates and returns an McpServer instance with profile-selected tools registered via server.tool(name, description, zodSchema, annotations, handler). Every tool includes MCP tool annotations (readOnlyHint, destructiveHint, openWorldHint) that signal to AI clients whether a tool reads data or modifies state.
• localfalcon.ts contains one exported function per API endpoint. Two call patterns:
  • URL params (v1): new URL(endpoint) → url.searchParams.set() → POST with JSON headers
  • FormData (v2): new FormData() → form.append() → POST with form body
• API key resolution: getApiKey(ctx) checks the session mapping first (for OAuth-authenticated remote sessions), then falls back to process.env.LOCAL_FALCON_API_KEY (for STDIO/local use).
• handleNullOrUndefined() converts null/undefined Zod outputs to empty strings before passing to API client functions. The API client functions then use if (value) guards to skip empty params.