# humanMCP Marketplace

[![smithery badge](https://smithery.ai/badge/kapoost/humanmcp-marketplace)](https://smithery.ai/servers/kapoost/humanmcp-marketplace)

A federated listings board across personal humanMCP servers.
No accounts. No algorithms. Just humans and their offers.

**Live:** https://marketplace.humanmcp.net
**MCP endpoint:** `POST https://marketplace.humanmcp.net/mcp`

## What it does

Every human can run their own [humanMCP](https://github.com/kapoost/humanmcp-go) server — publishing listings, offers, and trades. The marketplace crawls these servers and builds a single searchable index of listings.

Think of it as a town square where every stall is independently owned. The marketplace doesn't host content — it indexes and links back to the origin.

## Connect an agent

```json
{
  "mcpServers": {
    "humanmcp-marketplace": {
      "type": "http",
      "url": "https://marketplace.humanmcp.net/mcp"
    }
  }
}
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `search_marketplace` | Search listings across all servers — offers, trades, services |
| `list_servers` | All registered humanMCP instances |
| `get_server` | Server detail |

## REST API

```
GET  /servers              → list all registered servers
GET  /servers/{domain}     → server detail
GET  /search?q={query}     → full-text search across all listings
GET  /search?q=bread&type=trade → filter by listing type
GET  /feed                 → recent listings feed (JSON)
POST /register             → register a humanMCP instance
POST /mcp                  → MCP JSON-RPC 2.0 endpoint
```

## Agent discovery

```
GET  /.well-known/agent.json  → agent profile card
GET  /openapi.json            → OpenAPI 3.1 spec
GET  /healthz                 → status + server/listing counts
```

## Web UI

```
GET  /                  → homepage — listings + servers
GET  /q?q={query}       → search results
GET  /s/{domain}        → server page
```

Keyboard shortcuts: `/` search, `j/k` navigate, `Enter` open, `d` theme, `?` help.

## Register your server

Any humanMCP instance can join. No account needed — just your domain:

```bash
curl -X POST https://marketplace.humanmcp.net/register \
  -H "Content-Type: application/json" \
  -d '{"domain": "yourname-humanmcp.fly.dev"}'
```

The marketplace will:
1. Verify it's a real humanMCP (fetches `/.well-known/agent.json`)
2. Index all listings from `/listings/feed.json`
3. Add to crawl schedule (every 6 hours)

Requirements: your server must expose `/.well-known/agent.json` and `/listings/feed.json`.

## How crawling works

```
Your humanMCP server
    ↓
Marketplace fetches /.well-known/agent.json (identity)
    ↓
Fetches /api/profile (author name, bio, tags)
    ↓
Fetches /listings/feed.json (listings)
    ↓
Indexes in SQLite + FTS5
    ↓
Searchable within minutes, re-crawled every 6 hours
```

Listings stay on your server. Marketplace keeps a search index only.

## Configuration

| Source | Name | Default | Description |
|--------|------|---------|-------------|
| env | `PORT` | `8080` | Listen port |
| env | `DB_PATH` | `./marketplace.db` | SQLite database path |
| env | `SEED_SERVER` | — | Domain to crawl on startup |
| flag | `--addr` | `:8080` | Listen address |
| flag | `--db` | `./marketplace.db` | Database path |
| flag | `--seed` | — | Seed server domain |
| flag | `--crawl-interval` | `6h` | Re-crawl interval |

## Stack

- Go (stdlib + `modernc.org/sqlite`)
- SQLite + FTS5 for full-text search
- Fly.io single machine, 256MB
- No JS framework — server-rendered HTML with keyboard navigation

## Run locally

```bash
go build -o marketplace ./cmd/server/
./marketplace --seed kapoost.humanmcp.net
# open http://localhost:8080
```

## Deploy

```bash
fly apps create humanmcp-marketplace
fly volumes create marketplace_data --size 1 --region ams
fly deploy
```

## Key principles

1. **Listings only** — marketplace indexes offers, trades, services
2. **No content hosting** — index + link back, always
3. **Attribution** — author server visible on every result
4. **Opt-in** — register voluntarily
5. **Federated** — anyone can run their own marketplace instance
6. **Open protocol** — humanMCP REST API is the standard

Creative content (poems, essays, images) belongs on the author's server. A separate discovery service for that is planned.

## License

MIT