Ty_Tech/geolocal-io
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: MVP implementation — MCP server, partner one-pager, legal docs

Browse Source 
Code (code/):
- TypeScript MCP server with 5 tools (business info, hours, services, booking, related)
- PostgreSQL schema with pilot business seed data
- /.well-known/mcp-server manifest generator
- Railway deployment config (Dockerfile, railway.json)
- Multi-tenant gateway placeholder

GTM (docs/gtm/):
- Partner One-Pager: agency sales asset with economics, onboarding, competitive comparison

Legal (docs/legal/):
- Data Flow & Privacy: data collection, storage, sharing, GDPR/CCPA commitments
- Partnership Agreement Skeleton: template for agency/CoC partnerships
- IP Notes: well-known convention positioning, telemetry ownership, open-source strategy
This commit is contained in:
Ty
2026-07-16 14:10:21 -07:00
parent 4def4d0726
commit 2be10ce42c
22 changed files with 3419 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/legal/Data Flow & Privacy.md
+172
View File
@@ -0,0 +1,172 @@
# Data Flow & Privacy — geolocal.io
> Last updated: 2026-07-16
---
## 1. Overview
This document describes how data flows through the `geolocal.io` platform, what data we collect, how it's stored, who has access, and how we handle privacy obligations under GDPR and CCPA.
**Core principle:** We expose only public business data. We do not collect personal consumer data beyond what is necessary for booking transactions (handled by Cal.com and Stripe).
---
## 2. Data Collection Points
### 2.1 Business Data (Voluntary)
Businesses (or their agencies) voluntarily provide:
| Data | Source | Purpose |
|------|--------|---------|
| Business name, address, phone, website | Business owner / agency | AI discovery |
| Operating hours | Business owner / agency | AI recommendations |
| Services & pricing | Business owner / agency | AI recommendations |
| Story & narrative | Business owner / agency | Differentiation in AI responses |
| Photos & video | Business owner / agency | Visual discovery in AI |
| Cal.com booking link | Business owner / agency | Transaction loop |
**Note:** This data is already publicly available on the business's website or Google Business Profile. We do not scrape it without consent.
### 2.2 Telemetry Data (MCP Interactions)
Every MCP tool call generates:
| Data Point | Example |
|-----------|---------|
| Query terms | "best mechanic in Frisco TX" |
| Business slug referenced | "frisco-german-auto" |
| Tool called | "get_business_info" |
| AI platform used | ChatGPT, Gemini, Claude |
| Timestamp | 2026-07-16T14:23:00Z |
| Response time | 45ms |
### 2.3 Booking Data (via Cal.com / Stripe)
**We do NOT handle this directly.** Cal.com and Stripe are the providers of record. We pass booking requests to their APIs.
- Cal.com handles: appointment scheduling, calendar data, customer contact info
- Stripe handles: payment processing, billing data, financial records
---
## 3. Data Storage
| Data Type | Where It Lives | Retention |
|-----------|---------------|-----------|
| Business profiles | PostgreSQL (Railway) | Until business opts out |
| Telemetry logs | PostgreSQL + Redis (cached) | 24 months, then anonymized |
| Photos / media | CDN (Cloudflare R2 / AWS S3) | Until business opts out |
| Booking data | Cal.com / Stripe (external) | Per their retention policies |
---
## 4. Data Sharing
| Recipient | What We Share | Why |
|-----------|--------------|-----|
| AI agents (ChatGPT, Gemini, etc.) | Business profile data via MCP | Core product function |
| Partner agencies | Their client's analytics & commission data | Partner economics |
| Chambers of Commerce | Member analytics (aggregate) | CoC dashboard |
| Third-party data buyers (DaaS) | Anonymized telemetry only | Data-as-a-Service revenue |
**We never sell identifiable consumer data.** All DaaS products use aggregated, anonymized telemetry.
---
## 5. Bi-Directional MCP Data Flow
The "related businesses" handshake creates a bi-directional data exchange:
```
AI Agent ──┐
├──→ geolocal.io MCP Server ──→ Business Database
│ ↓
│ related_businesses()
│ ↓
│ Returns: list of related businesses
│ ↓
AI Agent ◄─┘───────────────────────────────────┘
```
**Verification flow:** AI agents can report data discrepancies back through the MCP protocol. We log these reports and flag business profiles for review.
---
## 6. Privacy Commitments
### 6.1 GDPR Principles
- **Lawful basis:** Processing is based on business consent (they opt in) and legitimate interest (telemetry for service improvement)
- **Data minimization:** We only collect what's needed for AI discovery and booking
- **Right to be forgotten:** Businesses can request full data deletion
- **Data portability:** Businesses can export their profile data at any time
- **DPIA:** Data Protection Impact Assessment will be completed before EU data processing
### 6.2 CCPA Principles
- **Notice at collection:** Clear disclosure of what data we collect
- **Right to delete:** Businesses can request deletion of their data
- **Right to opt out of sale:** We do not sell personal data
- **Non-discrimination:** We do not discriminate against users who exercise their rights
### 6.3 What We Do NOT Do
- We do not collect consumer PII beyond what Cal.com/Stripe handle
- We do not track individual consumers across sessions
- We do not use cookies for behavioral tracking
- We do not sell individual-level data
---
## 7. Security
| Measure | Status |
|---------|--------|
| PostgreSQL connection via SSL | ✅ MVP |
| Rate limiting on MCP endpoints | ✅ MVP |
| Input validation (Zod schemas) | ✅ MVP |
| OAuth 2.1 with PKCE for partner auth | Phase 2 |
| Regular security audits | Phase 3 |
| SOC 2 compliance | Future |
---
## 8. Incident Response
In the event of a data breach:
1. **Detect:** Automated alerts on anomalous MCP traffic patterns
2. **Contain:** Rate-limit or disable affected endpoints
3. **Notify:** Affected businesses notified within 72 hours (GDPR)
4. **Remediate:** Patch vulnerability, audit for scope
5. **Document:** Log incident, update this document
---
## 9. Data Flow Diagram
```
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│ Business │ │ │ │ AI Agents │
│ Owner / │────→│ geolocal.io │←───→│ ChatGPT, │
│ Agency │ │ MCP Server │ │ Gemini, │
└──────────────┘ │ │ │ Claude, │
│ ┌────────────┐ │ │ Grok │
│ │ PostgreSQL │ │ └──────────────┘
│ └────────────┘ │
│ ┌────────────┐ │
│ │ Redis │ │
│ └────────────┘ │
│ ┌────────────┐ │
│ │ Telemetry │ │
│ └────────────┘ │
└──────┬───────────┘
│
┌───────┴────────┐
│ Cal.com API │
│ Stripe API │
└────────────────┘
```
---
*This document must reference NORTH_STAR.md for principles. Updates require review against current privacy regulations.*
docs/legal/IP Notes.md
+122
View File
@@ -0,0 +1,122 @@
# IP Notes — geolocal.io
> Last updated: 2026-07-16
---
## 1. The `/.well-known/mcp-server` Pattern
### Positioning
The `/.well-known/mcp-server` convention is an adaptation of IETF's RFC 8615 (`/.well-known` URI space) for MCP server discovery. We position this as an **open standard** — not a proprietary geolocal.io invention.
**Rationale:**
- The more adopters use this convention, the more AI agents learn to look for it
- An open standard creates network effects that favor us as the infrastructure provider, even though we don't own the convention
- Competitors who copy the convention still need our hosted MCP server
### Risk
If another company claims to have "invented" `/.well-known/mcp-server`, we lose the narrative advantage. **Mitigation:** Document our first use and publish the convention publicly before competitors.
### Action Items
- [ ] Publish a technical blog post: "Introducing `/.well-known/mcp-server` for AI Discovery"
- [ ] File a design document on the MCP GitHub repository as a community proposal
- [ ] Include the convention in our public README before launch
---
## 2. Trademark
**Mark:** geolocal.io
**Status:** To be registered
**Action Items:**
- [ ] File USPTO trademark application for "GeoLocal" (Class 42: Cloud computing services; Class 35: Business consulting)
- [ ] Monitor for conflicting marks in adjacent categories
- [ ] Register domain variations (geolocal.com, geolocal.ai) to prevent confusion
---
## 3. MCP Protocol Usage
**Governance:** The MCP protocol is governed by Anthropic (as of 2026). It is open-source and permissively licensed.
**Our usage:**
- We implement the MCP protocol as specified — this is permitted
- We do not modify the core protocol — we extend it with our own tools and data schema
- Our proprietary value is in the **data layer** and **hosting infrastructure**, not the protocol itself
**Risk:** If MCP governance changes (e.g., becomes copyleft, or a competing protocol emerges), we need to be ready to migrate. Our data layer is protocol-agnostic, so this is manageable.
---
## 4. Telemetry Data Ownership
**We own the telemetry data** generated by MCP interactions on our platform:
- Query patterns
- Tool usage statistics
- Response times
- Business recommendation patterns
- AI platform usage breakdown
**We do NOT own:**
- Business profile data (owned by the businesses)
- Booking data (owned by Cal.com/Stripe)
- Consumer PII (we don't collect it)
**Commercialization:** Anonymized, aggregated telemetry may be licensed as a Data-as-a-Service product. This is subject to our privacy commitments (see Data Flow & Privacy.md).
---
## 5. Open Source Considerations
**Current code:** Proprietary (closed-source)
**Rationale for closed-source:**
- The competitive advantage is in the data and distribution, not the code
- However, closing the source may slow adoption if agencies want to audit the infrastructure
- **Potential strategy:** Release a reference implementation (the JSON manifest generator) as open source, while keeping the MCP server and telemetry pipeline proprietary
**Recommendation:** Evaluate open-sourcing the manifest generator / `/.well-known/mcp-server` convention documentation as a growth strategy. This positions geolocal.io as the authority without giving away proprietary infrastructure.
---
## 6. Business Data Rights
**Clear chain of title:**
```
Business Owner → (voluntarily provides) → geolocal.io MCP Server → (exposed via) → AI Agents
```
- Businesses retain full ownership of their profile data
- Businesses grant geolocal.io a non-exclusive license to host and expose that data via MCP
- Businesses may revoke this license at any time (data deletion request)
- Businesses may export their data at any time
**Partner agencies:**
- Agencies act as data processors on behalf of businesses
- Agencies do not own the business data they submit
- Businesses must authorize agencies to submit their data on their behalf
---
## 7. IP Audit Checklist
Before launch, verify:
- [ ] No third-party code with restrictive licenses (GPL, AGPL) in the MCP server
- [ ] All dependencies use permissive licenses (MIT, Apache 2.0, BSD)
- [ ] Trademark application filed
- [ ] `/.well-known/mcp-server` convention documented and published
- [ ] Privacy policy references data ownership clearly
- [ ] Terms of Service include IP clauses
- [ ] No open source code mixed with proprietary code without clear separation
---
*This document must reference NORTH_STAR.md for principles. Consult IP counsel before making final decisions.*
docs/legal/Partnership Agreement Skeleton.md
+125
View File
@@ -0,0 +1,125 @@
# Partnership Agreement Skeleton — geolocal.io
> **Template — NOT LEGAL ADVICE.** Consult qualified counsel before execution.
> Last updated: 2026-07-16
---
## Parties
**Provider:** geolocal.io (the "Platform")
**Partner:** [Partner Name / Agency / Chamber of Commerce] (the "Partner")
**Effective Date:** [Date]
---
## 1. Scope of Partnership
Partner is authorized to:
1. Offer `geolocal.io` MCP endpoints to their clients/members
2. Use `geolocal.io` branding and marketing materials (subject to brand guidelines)
3. Access the Partner Dashboard for client management and analytics
4. Earn recurring commissions as specified in Section 4
Partner is NOT authorized to:
1. Resell `geolocal.io` as a white-label product without Strategic-tier status
2. Modify or redistribute `geolocal.io` software code
3. Claim ownership of `geolocal.io` data or telemetry
---
## 2. Data Ownership
- **Businesses own their data.** All business profile data (name, services, photos, story, booking info) remains the intellectual property of the business that provided it.
- **geolocal.io owns the platform.** The MCP server infrastructure, telemetry data (anonymized), and platform code are owned by geolocal.io.
- **Partner owns their client relationships.** Partner retains all rights to their client relationships and may migrate clients off the platform at any time.
- **Data export.** Upon request, businesses may export their full profile data in JSON format.
---
## 3. Term & Termination
- **Term:** This agreement is effective until terminated by either party.
- **Termination for convenience:** Either party may terminate with 30 days written notice.
- **Termination for cause:** Either party may terminate immediately for material breach, fraud, or illegal activity.
- **Effect of termination:**
- Partner commissions cease on the termination date
- Business client data remains on the platform until businesses migrate off (grace period: 90 days)
- Partner loses access to Partner Dashboard on termination date
- geolocal.io retains anonymized telemetry data
---
## 4. Commission Structure
| Tier | Requirements | Commission Rate |
|------|-------------|-----------------|
| **Affiliate** | Signed partner agreement | 20% of MRR |
| **Partner** | 10+ active clients | 25% of MRR |
| **Strategic** | 50+ active clients | 30% of MRR |
- Commissions are calculated on net revenue (after payment processing fees)
- Commissions paid monthly, payable on the 15th of each month
- Partner may access commission reports via Partner Dashboard
---
## 5. Confidentiality
Both parties agree to keep confidential:
- Business client data and analytics
- Telemetry data and insights
- Commission rates and partnership terms
- Platform technical architecture and API endpoints
Confidentiality obligations survive termination for 24 months.
---
## 6. Liability
- **Limitation of liability:** Neither party is liable for indirect, consequential, or punitive damages arising from this agreement.
- **Maximum liability:** Provider's total liability is capped at the Partner's commissions earned in the preceding 12 months.
- **No warranty:** The platform is provided "as is" without warranty of merchantability or fitness for a particular purpose.
- **Partner indemnification:** Partner agrees to indemnify geolocal.io against claims arising from Partner's misuse of the platform or misrepresentation to clients.
---
## 7. Compliance
Both parties agree to:
- Comply with applicable data protection laws (GDPR, CCPA)
- Not use the platform for fraudulent or deceptive purposes
- Report data breaches within 24 hours of discovery
- Maintain accurate business data for enrolled clients
---
## 8. Dispute Resolution
- **Governing law:** [State/Jurisdiction]
- **Good faith negotiation:** 30-day period before formal action
- **Arbitration:** Binding arbitration if negotiation fails
- **Venue:** [City, State]
---
## 9. Amendment
This agreement may be amended by mutual written consent of both parties. geolocal.io may update platform terms (pricing, features) with 30 days written notice.
---
**Provider:** ___________________ **Date:** ___________
**Partner:** ___________________ **Date:** ___________
---
*This template must reference NORTH_STAR.md for principles. Consult legal counsel before use.*