Metadata-Version: 2.4
Name: publicmcp
Version: 0.3.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: httpx>=0.27
Requires-Dist: starlette>=0.40
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

# publicmcp

<!-- mcp-name: org.publicmcp/publicmcp -->

**Build a PUBLICMCP-compliant business identity MCP server in minutes.**

[![PyPI](https://img.shields.io/pypi/v/publicmcp)](https://pypi.org/project/publicmcp/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Spec](https://img.shields.io/badge/spec-v0.2-green)](https://github.com/joeprovence/publicmcp/blob/main/SPEC.md)

PUBLICMCP is an open standard for public-facing business identity MCP servers — structured, AI-readable business data that any AI agent or MCP client can query. This package is the reference implementation.

**Full spec and registry:** [github.com/joeprovence/publicmcp](https://github.com/joeprovence/publicmcp)

---

## Quickstart

```bash
pip install publicmcp
publicmcp init          # create business.json
publicmcp serve         # start server on :8000
```

Point your MCP client at `http://localhost:8000/mcp`. That's it.

---

## What it does

`publicmcp serve` starts a [FastMCP](https://github.com/jlowin/fastmcp) server that exposes your `business.json` as structured MCP tools. AI agents (Claude, Gemini, GPT, Continue, etc.) can call these tools to learn about your business, qualify a prospect, or pull your service and portfolio data — without hallucinating.

Browsers hitting the root URL are redirected to your `publicmcp_page` landing page. AI agents get MCP.

---

## CLI reference

```
publicmcp init [--output business.json] [--force]
    Create a starter business.json template.

publicmcp serve [--business business.json] [--host 0.0.0.0] [--port 8000] [--domain your.domain.com]
    Start the server. --domain sets the URL in the discovery endpoint.
```

---

## Endpoints

| Path | Method | Description |
|------|--------|-------------|
| `/mcp` | POST | MCP (streamable-http) — for AI agents |
| `/.well-known/publicmcp.json` | GET | Discovery endpoint |
| `/info` | GET | Plain-text server summary |
| `/` | GET | Discovery payload (JSON) |

---

## Tools (PUBLICMCP v0.2)

All tools are read-only. Data comes from your `business.json` — no external calls.

| Tool | Required | Description |
|------|----------|-------------|
| `get_info` | ✓ | Name, tagline, description, contact, founders, hours, social profiles |
| `get_services` | ✓ | Services with pricing, highlights, and timeline |
| `get_location` | ✓ | Offices, service areas, headquarters, geo |
| `get_portfolio` | — | Portfolio items, filterable by market and category |
| `get_sales_context` | — | Objection handling, pain points, ideal client profile (requires `sales_agent` in business.json) |
| `qualify_prospect` | — | Fit score, vertical detection, service recommendation (requires `primary_markets` in business.json) |

Plus one prompt: `sales_workflow` — tool chaining guide for consultative sales AI agents.

---

## business.json

`publicmcp init` creates a starter template. The minimum required fields for spec compliance:

```json
{
  "name": "Your Business",
  "services": [...],
  "locations": [...]
}
```

A full v0.2 schema is in the [spec](https://github.com/joeprovence/publicmcp/blob/main/SPEC.md).

---

## Discovery

Every server exposes a `/.well-known/publicmcp.json` endpoint so AI agents can auto-discover capabilities:

```json
{
  "publicmcp_version": "0.2",
  "auth": "none",
  "endpoint": "https://mcp.yourdomain.com/mcp",
  "tools": [...]
}
```

---

## Production deployment

For production, run behind a reverse proxy (Caddy or nginx) with SSL:

```
# Caddyfile
mcp.yourdomain.com {
    reverse_proxy 127.0.0.1:8000
}
```

Then run with your public domain:

```bash
publicmcp serve --business business.json --host 127.0.0.1 --port 8000 --domain mcp.yourdomain.com
```

---

## Registry

Live deployments are listed in the [PUBLICMCP registry](https://github.com/joeprovence/publicmcp/blob/main/registry/servers.yaml). 15 servers active across the US and Canada as of April 2026.

To register your server, open a PR to `registry/servers.yaml`.

---

## Links

- **Spec:** [SPEC.md](https://github.com/joeprovence/publicmcp/blob/main/SPEC.md)
- **Registry:** [registry/servers.yaml](https://github.com/joeprovence/publicmcp/blob/main/registry/servers.yaml)
- **Standard:** [publicmcp.org](https://publicmcp.org)
- **PyPI:** [pypi.org/project/publicmcp](https://pypi.org/project/publicmcp/)

---

## License

Apache 2.0 — see [LICENSE](LICENSE).
