# Product & Technical Roadmap

## 1. The Guiding Principle

`geolocal.io` is an **infrastructure platform**, not a destination site.

Everything we build must follow a single principle: **make it dead simple for a partner to deploy an MCP endpoint for a local business, and make that endpoint compelling enough that AI agents prefer it.**

This means:
- **No coding required** for the business or partner to set up
- **Centralized MCP hosting** (multi-tenant) with a simple JSON pointer for each business
- **Rich, structured data** that gives AI agents a reason to trust and use our endpoints
- **A self-reinforcing network** where more data attracts more agents, which generates more data

---

## 2. Technical Architecture Overview

### 2.1 High-Level System Components

| Component | Description | Technology Stack |
| :--- | :--- | :--- |
| **MCP Gateway** | Multi-tenant router that directs requests to the correct business MCP server | Node.js/TypeScript, FastMCP framework |
| **Business MCP Server** | Hosts the actual MCP tools for each business; dynamically generated from database | TypeScript, MCP SDK |
| **Business Database** | Stores business profiles, metadata, structured content, and telemetry | PostgreSQL, Supabase / Railway |
| **JSON Manifest Generator** | Generates the `/.well-known/mcp-server` JSON file for each business | Static file generation |
| **Partner Dashboard** | Agency-facing portal for onboarding, management, and analytics | React/Next.js, Tailwind |
| **CoC Dashboard** | Chamber-facing portal for member management and analytics | React/Next.js, Tailwind |
| **Business Dashboard** | SMB-facing portal for profile management and analytics | React/Next.js, Tailwind |
| **Telemetry Pipeline** | Captures and processes MCP interaction data for analytics and DaaS | Postgres, Redis, Webhooks |

### 2.2 Data Flow
AI Agent → MCP Gateway → Business MCP Server → Database / Cal.com / Stripe
↓
Telemetry Pipeline → Dashboards / Analytics

---

## 3. Technical Enablers: MCP Patterns You Can Leverage

### 3.1 Orchestration Pattern

Multiple MCP servers can be composed into a single endpoint, exposing tools from multiple sources to the AI as a unified interface.

**Relevance to you:** Your gateway will handle orchestration, enabling you to pull in tools from Cal.com's MCP or your own proprietary tools seamlessly.

### 3.2 Deployment Modes

| Mode | Description | Best For |
| :--- | :--- | :--- |
| **Managed-Shared** | Single MCP server instance serves multiple users simultaneously | **Your scenario:** Centralizing data from many businesses into one server |
| **Managed-Dedicated** | Each business gets their own container instance | High-security or high-traffic businesses |
| **Remote** | MCP server hosted by a third party; you just get a URL | Cal.com's MCP server integration |

### 3.3 Transport Options

| Transport | Description | Best For |
| :--- | :--- | :--- |
| **SSE (Server-Sent Events)** | Simple, server-push capable, easier for older clients | Quick start, simple use cases |
| **Streamable HTTP** | More efficient, supports larger payloads, recommended for production | **Recommended for your platform** |

### 3.4 Tool Design Best Practices

| Best Practice | Example |
| :--- | :--- |
| **Granular tools** | `get_business_info`, `check_availability`, `book_appointment` (not one giant `do_everything` tool) |
| **Clear descriptions** | Descriptions help the AI decide which tool to call |
| **Structured inputs** | Use JSON Schema for parameters |
| **Rich outputs** | Include links to visuals, booking confirmation, etc. |

---

## 4. Phase 1: MVP (90 Days)

### 4.1 MVP Scope

| Component | Features | Priority |
| :--- | :--- | :--- |
| **MCP Gateway** | Single multi-tenant MCP endpoint; basic routing by tenant | Must-have |
| **Business Database** | Store: business name, address, hours, services, description, photos URLs, Cal.com link | Must-have |
| **MCP Tools** | `get_business_info`, `get_hours`, `get_services`, `get_booking_link` | Must-have |
| **Cal.com Integration** | Redirect to Cal.com booking page (Phase 1: no deep API integration) | Must-have |
| **JSON Manifest Generator** | Generate `/.well-known/mcp-server` file for each business | Must-have |
| **Partner Dashboard** | Partner sign-up, client onboarding (add client → generate manifest) | Must-have |
| **Telemetry** | Basic logging: request counts, tool calls, response times | Nice-to-have |

### 4.2 Implementation Plan: 90-Day Sprint

| Week | Deliverable |
| :--- | :--- |
| **1-2** | Stand up PostgreSQL database; define schema; build business CRUD API |
| **3-4** | Build MCP server using TypeScript + MCP SDK; implement first tools (get_business_info, get_hours) |
| **5-6** | Implement JSON manifest generator; test discovery flow |
| **7-8** | Build Partner Dashboard (sign-up, client management, manifest download) |
| **9-10** | Integrate Cal.com (redirect); test end-to-end flow |
| **11-12** | Onboard 10 pilot businesses; collect feedback; iterate |

### 4.3 Hosting Infrastructure Decision

| Option | Pros | Cons | Recommended? |
| :--- | :--- | :--- | :--- |
| **Railway** | One-click deployment, free tier, simple | Less control, scaling limits | ✅ **Recommended for MVP** |
| **CreateOS** | Native MCP auto-discovery, persistent Postgres, marketplace | Newer platform, smaller community | Consider for production |
| **AWS ECS / Fargate** | Full control, enterprise-grade | Operational overhead, more complex | Later stage |
| **Google Cloud Run** | Serverless, scales well | Cold starts, less MCP-specific tooling | Later stage |

**Recommendation:** Start with **Railway** for MVP speed. Plan to migrate to **CreateOS** or **AWS** for production scale.

---

## 5. Phase 2: Scale & Features (180 Days)

### 5.1 Expanded Scope

| Component | Features |
| :--- | :--- |
| **MCP Tools (Expanded)** | `check_availability` (via Cal.com API), `book_appointment` (via Cal.com API) |
| **Deep Cal.com Integration** | Direct API integration (not just redirect); availability checks; booking creation |
| **Stripe Integration** | Payment capture for deposits; account creation for businesses |
| **Rich Content Layer** | Story, owner bio, high-quality photos, video; structured for AI extraction |
| **Related Businesses Tool** | `get_related_businesses` handshake; competitive intelligence capture |
| **MCP Gateway (Advanced)** | Rate limiting, authentication, OAuth support |
| **Business Dashboard** | SMB-facing portal for profile management; basic analytics |
| **Partner Dashboard (Expanded)** | White-label support; client analytics; commission tracking |
| **CoC Dashboard** | Member management; group analytics; lead reporting |
| **Telemetry Pipeline** | Structured logging; event tracking; basic analytics dashboards |

### 5.2 Implementation Plan

| Phase | Month | Deliverable |
| :--- | :--- | :--- |
| **5.2.1** | **4** | Deep Cal.com API integration; Stripe payment capture; expanded MCP tools |
| **5.2.2** | **5** | Related Businesses tool; telemetry pipeline; basic analytics |
| **5.2.3** | **6** | Business Dashboard; CoC Dashboard; white-label support |

---

## 6. Phase 3: Ecosystem & Monetization (360 Days)

### 6.1 Expanded Scope

| Component | Features |
| :--- | :--- |
| **Data-as-a-Service (DaaS)** | Anonymized telemetry data for licensing; AI Local Demand Index; competitive benchmarks |
| **Plugin Ecosystem** | WordPress plugin; Webflow app; Framer plugin |
| **Chamber Partnership Portal** | White-labeled CoC onboarding; member analytics; lead reporting |
| **Multi-Vertical Support** | Auto repair, beauty, home services, wellness, etc. |
| **Developer API** | Public API for custom MCP server development |
| **OAuth & Authorization** | OAuth 2.1 with Dynamic Client Registration (DCR) for partner integrations |
| **Advanced Telemetry** | Agent behavior analysis; market trend identification; anomaly detection |
| **Feedback Loop** | Verification tools; AI agent conflict reporting; automated data correction |

### 6.2 Implementation Plan

| Phase | Month | Deliverable |
| :--- | :--- | :--- |
| **6.2.1** | **7-9** | WordPress plugin; Webflow app; Chamber Partnership Portal |
| **6.2.2** | **10-12** | DaaS product launch; multi-vertical support; OAuth/authorization layer |
| **6.2.3** | **12+** | Feedback loop; advanced telemetry; public developer API |

---

## 7. Technology Stack Recommendations

| Layer | Technology | Rationale |
| :--- | :--- | :--- |
| **Backend** | Node.js / TypeScript | MCP SDK is TypeScript-first; large ecosystem |
| **API Framework** | FastMCP | High-performance, minimal boilerplate for MCP servers |
| **Database** | PostgreSQL (Supabase / Railway) | Reliable, JSON support, hosted options |
| **Frontend** | React / Next.js | Modern, fast, server-side rendering for dashboards |
| **Hosting** | Railway (MVP) → CreateOS / AWS (prod) | Balance of speed, cost, and control |
| **Cache** | Redis | For rate limiting, session management |
| **Analytics** | Postgres / Custom | You control the telemetry; build your own analytics layer |
| **Payment** | Stripe | Mature, API-first, handles deposits and subscriptions |
| **Booking** | Cal.com API | MCP-aware, structured API, booking + payment integration |

---

## 8. Key Technical Risks & Mitigation

| Risk | Mitigation |
| :--- | :--- |
| **MCP protocol changes rapidly** | Follow the official MCP GitHub; use stable SDK versions; subscribe to release notes |
| **Cal.com API changes** | Build a small abstraction layer; use Cal.com's official MCP server where possible |
| **Scalability of multi-tenant MCP** | Design for horizontal scaling; use Redis for session management; monitor performance |
| **Latency from AI agents** | Optimize tool responses; use caching; prioritize frequent tools |
| **Security of OAuth flows** | Use OAuth 2.1 with PKCE; follow MCP's security recommendations; regular audits |
| **Data privacy concerns** | Design privacy-first; avoid storing sensitive PII; comply with GDPR/CCPA |
| **Telemetry volume growth** | Use cost-effective storage; batch writes; use data compression |

---

## 9. Technical Guiding Principles

| Principle | Why It Matters |
| :--- | :--- |
| **Standard-first** | Follow MCP standards; avoid proprietary customizations |
| **Simple over complex** | Start simple; add complexity only when needed |
| **Observable by design** | Log everything; make telemetry a first-class feature |
| **Security by default** | OAuth, rate limiting, data validation from day one |
| **Partner-first UX** | Dashboards and onboarding should prioritize partner ease over "consumer polish" |
| **Data ownership** | Capture telemetry; build a data moat |

---

## 10. Citation Table

| ID | Source |
| :--- | :--- |
| [1] | Anthropic, "Model Context Protocol GitHub Repository," 2024-2026 |
| [2] | MCP Documentation, "Server Deployment Modes," 2026 |
| [3] | MCP Documentation, "Transport Options," 2026 |
| [4] | MCP Documentation, "Tool Design Best Practices," 2026 |
| [5] | Railway, "MCP Server Deployment Guide," 2026 |
| [6] | CreateOS, "MCP Server Hosting Documentation," 2026 |
| [7] | Cal.com, "MCP Server Documentation," 2026 |