publicmcp 0.2.0__tar.gz

publicmcp-0.2.0/LICENSE

@@ -0,0 +1,128 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file, you must include a
+          readable copy of the attribution notices contained within such
+          NOTICE file, in at least one of the following places: within a
+          NOTICE text provided with the Derivative Works; within the Source
+          form or documentation, if provided along with the Derivative Works;
+          or, within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work (and each Contributor
+      provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES
+      OR CONDITIONS OF ANY KIND, either express or implied.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law, shall any Contributor be liable
+      to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a result
+      of this License or out of the use or inability to use the Work.
+
+   9. Accepting Warranty or Liability. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a fee
+      for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may offer such obligations only on
+      Your own behalf and on a sole responsibility basis.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Joseph Provence / Salt Creative LLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0

publicmcp-0.2.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: publicmcp
+Version: 0.2.0
+Summary: Build a PUBLICMCP-compliant business identity MCP server in minutes
+Project-URL: Homepage, https://publicmcp.org
+Project-URL: Repository, https://github.com/joeprovence/publicmcp
+Project-URL: Spec, https://github.com/joeprovence/publicmcp/blob/main/SPEC.md
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,business,fastmcp,identity,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: fastmcp>=3.2
+Requires-Dist: starlette>=0.40
+Requires-Dist: uvicorn>=0.30

publicmcp-0.2.0/publicmcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

publicmcp-0.2.0/publicmcp/cli.py

@@ -0,0 +1,199 @@
+"""
+publicmcp/cli.py — CLI entry point.
+
+Commands:
+    publicmcp init   — create a starter business.json
+    publicmcp serve  — start the PUBLICMCP server
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from pathlib import Path
+
+import click
+import uvicorn
+
+from publicmcp import __version__
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="publicmcp")
+def cli():
+    """PUBLICMCP — business identity MCP server.
+
+    Build a spec-compliant MCP server for your business in minutes.
+
+    \b
+    Quickstart:
+        publicmcp init            # create business.json
+        publicmcp serve           # start server on :8000
+
+    Spec: https://github.com/joeprovence/publicmcp/blob/main/SPEC.md
+    """
+
+
+# ---------------------------------------------------------------------------
+# publicmcp init
+# ---------------------------------------------------------------------------
+
+@cli.command()
+@click.option(
+    "--output", "-o",
+    default="business.json",
+    show_default=True,
+    help="Output path for the business.json template.",
+)
+@click.option(
+    "--force", "-f",
+    is_flag=True,
+    default=False,
+    help="Overwrite existing file without prompting.",
+)
+def init(output: str, force: bool) -> None:
+    """Create a starter business.json template.
+
+    Generates a spec-compliant business.json with placeholder values.
+    Edit the file, then run 'publicmcp serve' to start your server.
+    """
+    output_path = Path(output)
+
+    if output_path.exists() and not force:
+        click.confirm(
+            f"{output_path} already exists. Overwrite?",
+            abort=True,
+        )
+
+    template_path = Path(__file__).parent / "templates" / "business.json"
+    shutil.copy(template_path, output_path)
+
+    click.echo(f"Created {output_path}")
+    click.echo("")
+    click.echo("Next steps:")
+    click.echo(f"  1. Edit {output_path} with your business details")
+    click.echo("  2. Run: publicmcp serve")
+    click.echo("  3. Connect your AI client to: http://localhost:8000/mcp")
+    click.echo("")
+    click.echo("Spec: https://github.com/joeprovence/publicmcp/blob/main/SPEC.md")
+
+
+# ---------------------------------------------------------------------------
+# publicmcp serve
+# ---------------------------------------------------------------------------
+
+@cli.command()
+@click.option(
+    "--business", "-b",
+    default="business.json",
+    show_default=True,
+    help="Path to your business.json file.",
+)
+@click.option(
+    "--host",
+    default="0.0.0.0",
+    show_default=True,
+    help="Host to bind to.",
+)
+@click.option(
+    "--port", "-p",
+    default=8000,
+    show_default=True,
+    type=int,
+    help="Port to listen on.",
+)
+@click.option(
+    "--domain",
+    default="",
+    help=(
+        "Public domain name (e.g. mcp.yourdomain.com). "
+        "Used in the discovery endpoint URL. "
+        "Defaults to the domain in your business.json website field."
+    ),
+)
+@click.option(
+    "--reload",
+    is_flag=True,
+    default=False,
+    help="Enable auto-reload on business.json changes (dev mode).",
+)
+def serve(
+    business: str,
+    host: str,
+    port: int,
+    domain: str,
+    reload: bool,
+) -> None:
+    """Start the PUBLICMCP server.
+
+    Reads business.json and starts a FastMCP server with 6 tools and 1 prompt.
+    Browsers are redirected to your publicmcp_page landing. AI agents get MCP.
+
+    \b
+    Endpoints:
+        /mcp                       — MCP (streamable-http)
+        /.well-known/publicmcp.json — discovery
+        /info                      — plain-text summary
+    """
+    business_path = Path(business)
+
+    if not business_path.is_file():
+        click.echo(
+            f"Error: {business_path} not found.\n"
+            "Run 'publicmcp init' to create a starter business.json.",
+            err=True,
+        )
+        sys.exit(1)
+
+    # Validate JSON before starting
+    try:
+        with open(business_path) as f:
+            biz = json.load(f)
+    except json.JSONDecodeError as exc:
+        click.echo(f"Error: Invalid JSON in {business_path}: {exc}", err=True)
+        sys.exit(1)
+
+    # Resolve domain: CLI flag > website field > localhost
+    if not domain:
+        website = biz.get("website", "")
+        domain = (
+            website
+            .removeprefix("https://")
+            .removeprefix("http://")
+            .removeprefix("www.")
+            .rstrip("/")
+            or "localhost"
+        )
+
+    # Spec compliance pre-check
+    missing = [
+        field for field in ("name", "services", "locations")
+        if not biz.get(field)
+    ]
+    if missing:
+        click.echo(
+            f"Warning: business.json is missing required fields: {', '.join(missing)}\n"
+            "Server will start but may not pass spec compliance.",
+            err=True,
+        )
+
+    # Import here to keep startup fast
+    from publicmcp.server import build_app
+
+    app = build_app(business_path=business_path, domain=domain)
+
+    click.echo(f"PUBLICMCP v{__version__} — {biz.get('name', 'unnamed')}")
+    click.echo(f"  MCP endpoint : http://{host}:{port}/mcp")
+    click.echo(f"  Discovery    : http://{host}:{port}/.well-known/publicmcp.json")
+    click.echo(f"  Info         : http://{host}:{port}/info")
+    click.echo(f"  Business     : {business_path.resolve()}")
+    click.echo(f"  Domain       : {domain}")
+    click.echo("")
+
+    uvicorn.run(
+        app,
+        host=host,
+        port=port,
+        reload=reload,
+        log_level="info",
+    )

publicmcp-0.2.0/publicmcp/server.py

@@ -0,0 +1,721 @@
+"""
+publicmcp/server.py — PUBLICMCP v0.2 single-tenant FastMCP server.
+
+Reads one business.json file and exposes 6 tools + 1 prompt over MCP.
+Configured via build_app(business_path, domain) before calling uvicorn.run().
+
+Spec: https://github.com/joeprovence/publicmcp/blob/main/SPEC.md
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from fastmcp import FastMCP
+from starlette.applications import Starlette
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, PlainTextResponse, RedirectResponse
+from starlette.routing import Mount, Route
+
+
+# ---------------------------------------------------------------------------
+# Module-level config — set once by build_app() before uvicorn starts.
+# ---------------------------------------------------------------------------
+
+_business_path: Path = Path("business.json")
+_domain: str = "localhost"
+
+_BROWSER_TOKENS = ("mozilla", "chrome", "safari", "firefox", "msie", "trident", "edge")
+_PASSTHROUGH_PATHS = frozenset(["/.well-known/publicmcp.json", "/", "/info"])
+
+_VERTICAL_KEYWORDS: dict[str, list[str]] = {
+    "functional_medicine": [
+        "functional medicine", "integrative medicine", "naturopath",
+        "holistic", "acupuncture", "wellness clinic",
+    ],
+    "therapy_practices": [
+        "therapy", "therapist", "counseling", "counselor",
+        "mental health", "psychologist", "psychiatrist", "behavioral health",
+    ],
+    "vacation_rentals": [
+        "vacation rental", "airbnb", "vrbo", "short term rental",
+        "short-term rental", "cabin rental", "lodge", "retreat center",
+    ],
+    "civil_engineering": [
+        "civil engineering", "engineering firm", "infrastructure",
+        "municipal services", "surveying",
+    ],
+    "real_estate": [
+        "real estate", "realtor", "realty", "real estate agent",
+        "real estate broker", "property management", "property manager",
+    ],
+    "healthcare": [
+        "healthcare", "medical", "clinic", "hospital", "doctor", "dental",
+        "dentist", "physician", "pediatric", "chiropractic", "optometry",
+        "urgent care", "family medicine",
+    ],
+    "construction": [
+        "construction", "contractor", "general contractor", "builder",
+        "plumber", "plumbing", "electrician", "electrical", "hvac",
+        "roofing", "concrete", "masonry", "landscaping", "excavation",
+        "remodeling", "home improvement",
+    ],
+    "ecommerce": [
+        "ecommerce", "e-commerce", "online store", "shopify",
+        "retail", "boutique", "product shop",
+    ],
+}
+
+
+# ---------------------------------------------------------------------------
+# Business data loader
+# ---------------------------------------------------------------------------
+
+def _load_business() -> dict:
+    try:
+        with open(_business_path) as f:
+            return json.load(f)
+    except FileNotFoundError:
+        raise RuntimeError(
+            f"business.json not found at: {_business_path}\n"
+            "Run 'publicmcp init' to create one, or pass --business <path>."
+        ) from None
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"Invalid JSON in {_business_path}: {exc}") from exc
+
+
+def _extract_city(market_str: str) -> str:
+    parts = market_str.split()
+    return " ".join(parts[:-1]).lower()
+
+
+# ---------------------------------------------------------------------------
+# Browser redirect middleware — browsers go to the publicmcp_page landing
+# ---------------------------------------------------------------------------
+
+class _BrowserRedirectMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        ua = request.headers.get("user-agent", "").lower()
+        accept = request.headers.get("accept", "").lower()
+        is_browser = any(token in ua for token in _BROWSER_TOKENS)
+        wants_json = "application/json" in accept
+        in_passthrough = request.url.path in _PASSTHROUGH_PATHS
+        if is_browser and not wants_json and not in_passthrough:
+            biz = _load_business()
+            landing = biz.get(
+                "publicmcp_page",
+                f"https://www.{_domain.removeprefix('mcp.')}",
+            )
+            return RedirectResponse(landing, status_code=301)
+        return await call_next(request)
+
+
+# ---------------------------------------------------------------------------
+# FastMCP instance
+# ---------------------------------------------------------------------------
+
+mcp = FastMCP("publicmcp-server")
+
+
+# ---------------------------------------------------------------------------
+# Prompt: sales_workflow
+# ---------------------------------------------------------------------------
+
+@mcp.prompt()
+def sales_workflow() -> str:
+    """
+    Workflow guide for qualifying a prospect using this PUBLICMCP server.
+    Load at session start to ensure correct tool chaining order.
+    """
+    return """\
+You are a consultative sales assistant connected to a PUBLICMCP-compliant server.
+
+## Tool Chaining Order
+
+1. get_info()
+   Confirm you are connected to the correct business before calling anything else.
+
+2. qualify_prospect(description="<prospect description>")
+   Pass a brief description including industry, location, and current website
+   status if known. Returns fit_score, detected_vertical, recommended_service,
+   and discovery questions. Start here for prospect qualification.
+   Note: only available on servers with primary_markets data configured.
+
+3. get_sales_context(vertical="<detected_vertical>")
+   Call after qualify_prospect when fit_score is "strong" or "possible".
+   Returns full objection handling, pain points, and ideal client profile.
+   Note: only available on servers with sales_agent data configured.
+
+4. get_services(category="design" or "marketing")
+   Call when the prospect asks about specific services or pricing.
+   Never fabricate pricing — only quote what this tool returns.
+
+5. get_location(market="<city>")
+   Confirm the business serves the prospect's market if location is ambiguous.
+
+6. get_portfolio(market="<city>", category="<type>")
+   Use when the prospect wants to see relevant past work.
+
+## Rules
+
+- Always confirm location early — not all businesses serve all markets.
+- If qualify_prospect returns fit_score "poor", ask clarifying questions.
+- Never invent services, pricing, or portfolio items not returned by tools.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Tool: get_info
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def get_info() -> str:
+    """
+    Return core identity information about this business (PUBLICMCP v0.2).
+
+    Includes business name, tagline, description, founding year, website,
+    business type, legal name, logo, price range, contact details,
+    structured opening hours, and social profiles.
+
+    Returns:
+        JSON object conforming to PUBLICMCP v0.2 get_info schema.
+    """
+    biz = _load_business()
+
+    raw_contact = biz.get("contact", {})
+    contact = {k: v for k, v in raw_contact.items() if k != "phone"}
+    if "phone" in raw_contact and "telephone" not in contact:
+        contact["telephone"] = raw_contact["phone"]
+
+    social_profiles = biz.get("social_profiles") or biz.get("social", {})
+
+    return json.dumps(
+        {
+            "publicmcp_version": "0.2",
+            "name": biz.get("name", ""),
+            "tagline": biz.get("tagline", ""),
+            "description": biz.get("description", ""),
+            "founded": biz.get("founded"),
+            "founder": biz.get("founder", ""),
+            "co_founder": biz.get("co_founder", ""),
+            "website": biz.get("website", ""),
+            "business_type": biz.get("business_type", []),
+            "legal_name": biz.get("legal_name", ""),
+            "logo": biz.get("logo", ""),
+            "price_range": biz.get("price_range", ""),
+            "contact": contact,
+            "opening_hours": biz.get("opening_hours", []),
+            "social_profiles": social_profiles,
+        },
+        indent=2,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tool: get_services
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def get_services(category: str = "") -> str:
+    """
+    Return services offered by this business.
+
+    Args:
+        category: Optional filter. Leave empty to return all services.
+                  Common values: 'design', 'marketing', 'hair', 'color',
+                  'styling', 'extensions' — depends on the business.
+
+    Returns:
+        JSON array of service objects with name, category, description,
+        highlights, pricing, and timeline.
+    """
+    biz = _load_business()
+    services = biz.get("services", [])
+
+    if category:
+        services = [s for s in services if s.get("category", "") == category.lower()]
+
+    if not services:
+        return json.dumps({"error": f"No services found for category: {category!r}"})
+
+    return json.dumps(services, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Tool: get_location
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def get_location(market: str = "") -> str:
+    """
+    Return geographic presence and service coverage (PUBLICMCP v0.2).
+
+    Includes headquarters, geo coordinates, service radius, remote capability,
+    office locations, and full service area list.
+
+    Args:
+        market: Optional city filter (e.g. 'Boise', 'Spokane').
+                Leave empty to return all offices and service areas.
+
+    Returns:
+        JSON object conforming to PUBLICMCP v0.2 get_location schema.
+    """
+    biz = _load_business()
+    locations = biz.get("locations", [])
+    service_areas = biz.get("service_areas", [])
+
+    if market:
+        locations = [
+            loc for loc in locations
+            if (
+                market.lower() in loc.get("city", "").lower()
+                or market.lower() in loc.get("market", "").lower()
+            )
+        ]
+
+    headquarters = biz.get("headquarters")
+    if not headquarters:
+        primary = next(
+            (loc for loc in biz.get("locations", []) if loc.get("primary")),
+            biz.get("locations", [{}])[0] if biz.get("locations") else {},
+        )
+        city = primary.get("city", "")
+        state = primary.get("state", "")
+        headquarters = f"{city}, {state}".strip(", ") if city or state else ""
+
+    return json.dumps(
+        {
+            "headquarters": headquarters,
+            "geo": biz.get("geo"),
+            "geo_radius": biz.get("geo_radius"),
+            "remote_capable": biz.get("remote_capable", True),
+            "offices": locations,
+            "service_areas": service_areas,
+        },
+        indent=2,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tool: get_portfolio
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def get_portfolio(market: str = "", category: str = "") -> str:
+    """
+    Return portfolio highlights from this business.
+
+    Args:
+        market: Optional market filter (e.g. 'Boise', 'Meridian').
+                Leave empty for all markets.
+        category: Optional category filter (e.g. 'web design', 'color').
+                  Leave empty for all categories.
+
+    Returns:
+        JSON array of portfolio items with title, description, category,
+        and markets list.
+    """
+    biz = _load_business()
+    items = biz.get("portfolio", [])
+
+    if market:
+        items = [
+            item for item in items
+            if any(market.lower() in m.lower() for m in item.get("markets", []))
+        ]
+
+    if category:
+        items = [
+            item for item in items
+            if category.lower() in item.get("category", "").lower()
+        ]
+
+    if not items:
+        return json.dumps({"message": "No portfolio items match those filters."})
+
+    return json.dumps(items, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Tool: get_sales_context  (managed-service extension)
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def get_sales_context(vertical: str = "") -> str:
+    """
+    Return consultative sales context for a specific business vertical.
+
+    Use this after qualify_prospect returns a detected_vertical. Returns pain
+    points, objection handling, competitive positioning, ideal client profile,
+    qualifying questions, and social proof for that vertical.
+
+    Only available on servers with sales_agent data configured in business.json.
+
+    Args:
+        vertical: The prospect's industry vertical. Common values: real_estate,
+                  healthcare, construction, functional_medicine, vacation_rentals,
+                  ecommerce, therapy_practices, civil_engineering.
+                  Leave empty for general context.
+
+    Returns:
+        JSON object with pain_point, objection_responses,
+        competitive_positioning, ideal_client_profile, discovery_questions,
+        qualifying_questions, and social_proof.
+    """
+    biz = _load_business()
+    agent = biz.get("sales_agent")
+
+    if not agent:
+        return json.dumps({
+            "message": (
+                "Sales context is not configured for this server. "
+                "Add a 'sales_agent' block to your business.json to enable it."
+            )
+        })
+
+    profiles = biz.get("ideal_client_profiles", [])
+    qualifying = biz.get("qualifying_questions", {})
+
+    vertical_key = (
+        vertical.lower().replace(" ", "_").replace("-", "_") if vertical else ""
+    )
+
+    pain_point = None
+    profile = None
+
+    if vertical_key:
+        pain_point = agent.get("pain_points_by_vertical", {}).get(vertical_key)
+        profile = next(
+            (
+                p for p in profiles
+                if vertical_key in p["persona"].lower().replace(" ", "_")
+                or any(
+                    vertical_key in e.lower().replace(" ", "_")
+                    for e in p.get("examples", [])
+                )
+            ),
+            None,
+        )
+
+    result: dict = {}
+
+    if pain_point:
+        result["pain_point"] = pain_point
+    elif vertical_key:
+        result["pain_point"] = (
+            f"No specific pain point data for '{vertical}'. "
+            "Use general positioning from competitive_positioning below."
+        )
+
+    result["objection_responses"] = agent.get("objections", {})
+    result["competitive_positioning"] = agent.get("competitive_positioning", {})
+    result["social_proof"] = agent.get("social_proof", {})
+    result["discovery_questions"] = agent.get("discovery_questions", [])
+    result["qualifying_questions"] = qualifying.get("questions", [])
+
+    if profile:
+        result["ideal_client_profile"] = profile
+    else:
+        result["ideal_client_profiles"] = profiles
+
+    result["project_fit"] = biz.get("project_fit", {})
+
+    return json.dumps(result, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Tool: qualify_prospect  (managed-service extension)
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def qualify_prospect(description: str) -> str:
+    """
+    Assess whether a prospect is a good fit for this business.
+
+    Analyzes a free-text prospect description to detect vertical, location,
+    and intent signals. Returns a structured fit assessment with recommended
+    service and discovery questions.
+
+    Only available on servers with primary_markets data in business.json.
+
+    Args:
+        description: Free-text description of the prospect. Include location,
+                     industry, current situation, and goals if known.
+                     Example: "pediatric dentist in Spokane, currently on Wix,
+                     4-person practice, wants more new patient leads".
+
+    Returns:
+        JSON object with fit_score (strong/possible/poor), fit_reason,
+        detected_vertical, location_match, matched_market,
+        recommended_service, pricing_hint, discovery_questions,
+        vertical_pain_point (if available), and next_step.
+    """
+    if not description or not description.strip():
+        return json.dumps({"error": "description is required."})
+
+    biz = _load_business()
+    primary_markets: list = biz.get("primary_markets") or []
+
+    if not primary_markets:
+        return json.dumps({
+            "message": (
+                "qualify_prospect requires 'primary_markets' in business.json. "
+                "Add a list of your target markets to enable this tool."
+            )
+        })
+
+    desc = description.lower()
+    service_areas: list = biz.get("service_areas") or []
+
+    detected_vertical = None
+    for vertical, keywords in _VERTICAL_KEYWORDS.items():
+        if any(kw in desc for kw in keywords):
+            detected_vertical = vertical
+            break
+
+    location_match = "out_of_market"
+    matched_market = None
+
+    for market in primary_markets:
+        if _extract_city(market) in desc:
+            location_match = "primary_market"
+            matched_market = market
+            break
+
+    if location_match == "out_of_market":
+        for area in service_areas:
+            city = _extract_city(area)
+            if len(city) > 3 and city in desc:
+                location_match = "service_area"
+                matched_market = area
+                break
+
+    has_no_website = any(s in desc for s in [
+        "no website", "don't have a website", "dont have a website",
+        "need a website", "starting from scratch", "never had a website",
+    ])
+    needs_redesign = any(s in desc for s in [
+        "redesign", "outdated", "old website", "rebuild", "wix",
+        "squarespace", "godaddy website", "diy site", "not working",
+        "needs work", "looks bad",
+    ])
+    wants_seo = any(s in desc for s in [
+        "seo", "ranking", "rank on google", "google search",
+        "organic traffic", "search traffic", "show up on google", "leads",
+    ])
+
+    in_service_area = location_match in ("primary_market", "service_area")
+    has_vertical = detected_vertical is not None
+
+    if in_service_area and has_vertical:
+        fit_score = "strong"
+        fit_reason = (
+            f"Served market ({matched_market}) with clear vertical match "
+            f"({detected_vertical.replace('_', ' ')})."
+        )
+    elif in_service_area:
+        fit_score = "possible"
+        fit_reason = (
+            f"Served market ({matched_market}) confirmed but industry vertical "
+            "is unclear — ask about their business type."
+        )
+    elif has_vertical:
+        fit_score = "possible"
+        fit_reason = (
+            f"Vertical match ({detected_vertical.replace('_', ' ')}) detected "
+            "but location not confirmed in service area — verify their market."
+        )
+    else:
+        fit_score = "poor"
+        fit_reason = (
+            "Neither location nor vertical could be confirmed from the "
+            "description. More detail needed before routing to a quote."
+        )
+
+    services = biz.get("services", [])
+    default_service = services[0]["name"] if services else "Core Service"
+
+    if has_no_website:
+        recommended_service = f"{default_service} — New Build"
+        pricing_hint = "Contact for quote"
+    elif needs_redesign and wants_seo:
+        recommended_service = f"{default_service} + SEO / Growth Package"
+        pricing_hint = "Contact for quote"
+    elif needs_redesign:
+        recommended_service = f"{default_service} — Redesign"
+        pricing_hint = "Contact for quote"
+    elif wants_seo:
+        recommended_service = "SEO / Growth Service"
+        pricing_hint = "Contact for quote"
+    else:
+        recommended_service = default_service
+        pricing_hint = "Contact for quote"
+
+    if services:
+        pricing = services[0].get("pricing", {})
+        if isinstance(pricing, dict) and pricing.get("project_range"):
+            pricing_hint = pricing["project_range"]
+
+    questions = biz.get("qualifying_questions", {}).get("questions", [])
+    discovery_questions = [q["question"] for q in questions[:3]]
+
+    contact_url = biz.get("contact", {}).get("quote_url") or biz.get("website", "")
+    if fit_score == "strong":
+        next_step = f"Route to a project quote: {contact_url}"
+    elif fit_score == "possible":
+        next_step = (
+            "Gather more details on location and goals, then route to a quote "
+            "if confirmed in service area."
+        )
+    else:
+        next_step = (
+            "Clarify location and industry before proceeding. "
+            "Call get_location() to review service areas."
+        )
+
+    result: dict = {
+        "fit_score": fit_score,
+        "fit_reason": fit_reason,
+        "detected_vertical": (
+            detected_vertical
+            or "unknown — include industry in description for better results"
+        ),
+        "location_match": location_match,
+        "matched_market": matched_market,
+        "recommended_service": recommended_service,
+        "pricing_hint": pricing_hint,
+        "discovery_questions": discovery_questions,
+        "next_step": next_step,
+    }
+
+    if detected_vertical:
+        pain_point = (
+            biz.get("sales_agent", {})
+            .get("pain_points_by_vertical", {})
+            .get(detected_vertical)
+        )
+        if pain_point:
+            result["vertical_pain_point"] = pain_point
+
+    return json.dumps(result, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Static endpoints
+# ---------------------------------------------------------------------------
+
+async def _info_handler(request: Request) -> PlainTextResponse:
+    biz = _load_business()
+    services_list = biz.get("services", [])
+    service_names = ", ".join(s["name"] for s in services_list[:4])
+    text = (
+        f"Business: {biz.get('name')}\n"
+        f"Tagline:  {biz.get('tagline')}\n"
+        f"Website:  {biz.get('website')}\n"
+        f"\nServices: {service_names}\n"
+        f"\nTools: get_info, get_services, get_location, get_portfolio, "
+        f"get_sales_context, qualify_prospect\n"
+        f"Prompt:   sales_workflow\n"
+        f"\nMCP endpoint:  https://{_domain}/mcp\n"
+        f"Discovery:     https://{_domain}/.well-known/publicmcp.json\n"
+        f"Spec:          https://github.com/joeprovence/publicmcp/blob/main/SPEC.md\n"
+    )
+    return PlainTextResponse(text, headers={"Access-Control-Allow-Origin": "*"})
+
+
+def _discovery_payload() -> dict:
+    biz = _load_business()
+    has_sales = bool(biz.get("sales_agent"))
+    has_markets = bool(biz.get("primary_markets"))
+
+    tools_list = [
+        {"name": "get_info",      "version": "0.2", "required": True},
+        {"name": "get_services",  "version": "0.2", "required": True},
+        {"name": "get_location",  "version": "0.2", "required": True},
+        {"name": "get_portfolio", "version": "0.2", "required": False},
+    ]
+    if has_sales:
+        tools_list.append({"name": "get_sales_context", "version": "0.2", "required": False})
+    if has_markets:
+        tools_list.append({"name": "qualify_prospect",  "version": "0.2", "required": False})
+
+    tool_guide = {
+        "get_info":      "Core identity — name, description, founders, contact",
+        "get_services":  "Service list with pricing, timeline, and highlights",
+        "get_location":  "Office locations and service areas",
+        "get_portfolio": "Portfolio highlights by market and category",
+    }
+    if has_sales:
+        tool_guide["get_sales_context"] = (
+            "Consultative sales brief by vertical — pain points, objections, "
+            "ideal client profile, qualifying questions"
+        )
+    if has_markets:
+        tool_guide["qualify_prospect"] = (
+            "Pass a free-text prospect description to receive fit_score, "
+            "detected_vertical, and recommended_service."
+        )
+
+    return {
+        "publicmcp_version": "0.2",
+        "auth": "none",
+        "note": (
+            "This is a Model Context Protocol (MCP) server that lets AI agents "
+            "query structured business data. Use the tools below to learn about "
+            f"{biz.get('name', 'this business')} and assess fit for a prospect."
+        ),
+        "name": f"{biz.get('name', _domain).lower().replace(' ', '-')}-publicmcp",
+        "business": f"{biz.get('name')} — {biz.get('tagline', '')}",
+        "endpoint": f"https://{_domain}/mcp",
+        "prompts": {
+            "sales_workflow": (
+                "Load at session start — defines correct tool chaining order "
+                "for prospect qualification."
+            ),
+        },
+        "tools": tools_list,
+        "tool_guide": tool_guide,
+        "spec": "https://github.com/joeprovence/publicmcp/blob/main/SPEC.md",
+        "registry": (
+            "https://github.com/joeprovence/publicmcp"
+            "/blob/main/registry/servers.yaml"
+        ),
+    }
+
+
+_CORS_HEADERS = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET",
+}
+
+
+async def _well_known_handler(request: Request) -> JSONResponse:
+    return JSONResponse(_discovery_payload(), headers=_CORS_HEADERS)
+
+
+async def _root_handler(request: Request) -> JSONResponse:
+    return JSONResponse(_discovery_payload(), headers=_CORS_HEADERS)
+
+
+# ---------------------------------------------------------------------------
+# App factory — called by cli.py before uvicorn.run()
+# ---------------------------------------------------------------------------
+
+def build_app(business_path: Path, domain: str = "localhost") -> Starlette:
+    global _business_path, _domain
+    _business_path = Path(business_path).resolve()
+    _domain = domain
+
+    mcp_app = mcp.http_app(transport="streamable-http")
+    app = Starlette(
+        lifespan=mcp_app.lifespan,
+        routes=[
+            Route("/",                          _root_handler,      methods=["GET"]),
+            Route("/info",                      _info_handler,      methods=["GET"]),
+            Route("/.well-known/publicmcp.json", _well_known_handler, methods=["GET"]),
+            Mount("/", app=mcp_app),
+        ],
+    )
+    app.add_middleware(_BrowserRedirectMiddleware)
+    return app

publicmcp-0.2.0/publicmcp/templates/business.json

@@ -0,0 +1,75 @@
+{
+  "name": "Your Business Name",
+  "tagline": "Your tagline here",
+  "description": "A brief description of what your business does and who it serves.",
+  "founded": 2020,
+  "founder": "Founder Name",
+  "website": "https://www.yourdomain.com",
+  "publicmcp_page": "https://www.yourdomain.com/publicmcp",
+  "business_type": ["LocalBusiness"],
+  "legal_name": "Your Business LLC",
+  "logo": "https://www.yourdomain.com/logo.png",
+  "price_range": "$$",
+  "contact": {
+    "email": "hello@yourdomain.com",
+    "telephone": "",
+    "quote_url": "https://www.yourdomain.com/contact"
+  },
+  "opening_hours": [
+    {
+      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
+      "opens": "09:00",
+      "closes": "17:00"
+    }
+  ],
+  "social_profiles": {
+    "twitter": "",
+    "facebook": "",
+    "linkedin": ""
+  },
+  "headquarters": "Your City, ST",
+  "geo": {
+    "lat": 0.0,
+    "lng": 0.0
+  },
+  "remote_capable": true,
+  "locations": [
+    {
+      "city": "Your City",
+      "state": "ST",
+      "market": "Your City ST",
+      "primary": true
+    }
+  ],
+  "service_areas": [
+    "Your City ST"
+  ],
+  "services": [
+    {
+      "name": "Your Primary Service",
+      "category": "primary",
+      "description": "Describe what you offer and who it is for.",
+      "highlights": [
+        "Key benefit 1",
+        "Key benefit 2",
+        "Key benefit 3"
+      ],
+      "pricing": {
+        "project_range": "Contact for quote"
+      },
+      "timeline": "2-4 weeks"
+    }
+  ],
+  "portfolio": [
+    {
+      "title": "Sample Project",
+      "description": "Brief description of a past project and its outcome.",
+      "category": "primary",
+      "markets": ["Your City ST"]
+    }
+  ],
+  "project_fit": {
+    "ideal_client": "Describe your ideal client here.",
+    "not_a_fit": "Describe who you do not serve here."
+  }
+}

publicmcp-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "publicmcp"
+version = "0.2.0"
+description = "Build a PUBLICMCP-compliant business identity MCP server in minutes"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+keywords = ["mcp", "ai", "business", "identity", "agents", "fastmcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "fastmcp>=3.2",
+    "uvicorn>=0.30",
+    "starlette>=0.40",
+    "click>=8.0",
+]
+
+[project.urls]
+Homepage = "https://publicmcp.org"
+Repository = "https://github.com/joeprovence/publicmcp"
+Spec = "https://github.com/joeprovence/publicmcp/blob/main/SPEC.md"
+
+[project.scripts]
+publicmcp = "publicmcp.cli:cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["publicmcp"]