Metadata-Version: 2.4
Name: publicmcp
Version: 0.4.1
Summary: Build a PUBLICMCP-compliant business identity MCP server in minutes
Project-URL: Homepage, https://www.sltcreative.com/publicmcp
Project-URL: Repository, https://gitlab.com/salt-creative-group/publicmcp
Project-URL: Spec, https://gitlab.com/salt-creative-group/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.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.10
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

**Build and self-host a PUBLICMCP business identity MCP server.**

[![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.4.1-green)](SPEC.md)

PUBLICMCP is an open standard for public-facing business identity MCP servers: structured,
read-only business data that any AI agent or MCP client can query. This repository holds the
specification ([SPEC.md](SPEC.md)) and a reference Python package.

PUBLICMCP is **self-hosted only**. Each business runs its own server. There is no central
registry, hosted service, or verification program.

---

## What's new in 0.4.1 (2026-10-25)

- **Self-hosted only.** The central registry, directory, verification badges, hosted service and
  public library are retired. publicmcp.org is no longer used. The standard's home is
  [sltcreative.com/publicmcp](https://www.sltcreative.com/publicmcp).
- **Spec 0.4.1** is an editorial revision of v0.4: the registry section is removed, the spec URL
  now points to [SPEC.md](SPEC.md) on GitLab, and Appendix A covers self-hosting. Servers still
  declare `publicmcp_version: "0.4"`.
- **Package:** the `publicmcp router` command and its registry tools are removed. `init` and
  `serve` are unchanged.

---

## Quickstart

Requires Python 3.10+.

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

Point your MCP client at `http://localhost:8000/mcp`.

---

## What the reference package does

`publicmcp serve` starts a [FastMCP](https://github.com/jlowin/fastmcp) server that exposes your
`business.json` as read-only MCP tools. Browsers that open `/mcp` (or any path other than `/`, `/info`
and `/.well-known/publicmcp.json`) are redirected to the `publicmcp_page` set in `business.json`;
AI agents get MCP.

| Tool | In spec | Description |
|------|---------|-------------|
| `get_info` | Required | Name, tagline, description, contact, hours, social profiles |
| `get_services` | Required | Services with pricing and details |
| `get_location` | Required | Headquarters, offices, service areas |
| `get_portfolio` | Recommended | Portfolio items, filterable by market and category |
| `get_sales_context` | Extension | Objection handling, pain points, ideal client profile (needs `sales_agent` in business.json) |
| `qualify_prospect` | Extension | Fit score and service recommendation (needs `primary_markets` in business.json) |

Plus one prompt: `sales_workflow`, a tool-chaining guide for sales agents.

**Not yet in the package:** `get_markets`, `get_products`, `search_site_content`,
`get_page_content`, `list_site_pages`, `check_project_fit` and `/.well-known/agents.json`. The
package also still declares an earlier `publicmcp_version`, names itself `publicmcp-server`
(spec 3.1 expects `{business-slug}-publicmcp`), sends no server instructions (3.2), and its
`get_portfolio` filters and response shape differ from spec 5.1. For full v0.4 compliance, add these
yourself or build your own server against [SPEC.md](SPEC.md).

---

## 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. Always pass it in
    production: the default comes from the business.json website field, without www.
```

---

## Endpoints

| Path | Method | Description |
|------|--------|-------------|
| `/mcp` | POST | MCP (streamable HTTP), for AI agents |
| `/.well-known/publicmcp.json` | GET | PUBLICMCP compliance fingerprint |
| `/info` | GET | Plain-text server summary |
| `/` | GET | Discovery payload (JSON) |

---

## Discovery

Servers should publish `/.well-known/publicmcp.json` and `/.well-known/agents.json`
([spec section 11](SPEC.md#11-agentsjson--open-agent-discovery-standard)). Sites on hosted platforms (Duda, Shopify, Wix, Squarespace) that
can't serve files can use a DNS TXT record instead:

```
_agents.yourdomain.com.  TXT  "v=agents0.1; type=publicmcp; endpoint=https://mcp.yourdomain.com/mcp; version=0.4"
```

---

## Production deployment

Run behind a reverse proxy with TLS on a dedicated subdomain. With Caddy:

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

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

Add CORS headers (`Access-Control-Allow-Origin: *`) at the proxy so browser-based agents can
read your endpoints.

**Example deployment:** Salt Creative self-hosts its server at `https://mcp.sltcreative.com/mcp`.

---

## Links

- **Spec:** [SPEC.md](SPEC.md)
- **PyPI:** [pypi.org/project/publicmcp](https://pypi.org/project/publicmcp/)
- **Maintainer:** [Salt Creative](https://www.sltcreative.com/publicmcp)

---

## License

Apache 2.0. See [LICENSE](LICENSE).
