Metadata-Version: 2.4
Name: fless-mcp
Version: 1.1.0
Summary: Fless apartment-hunting MCP server (stdio proxy to https://mcp.fless.io/mcp) — research cities, neighborhoods, rents, and build pre-filled hunt links.
Author-email: Fless <dev@folyfoly.com>
License: MIT
Project-URL: Homepage, https://fless.io/ai-agents
Project-URL: Documentation, https://fless.io/hunt-how-to.md
Project-URL: Repository, https://github.com/fless-io/skills
Project-URL: Changelog, https://github.com/fless-io/skills/blob/main/CHANGELOG.md
Keywords: mcp,apartment,hunting,rental,ai,agent,llm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# fless-mcp

[Fless](https://fless.io) apartment-hunting tools for any MCP-capable AI agent — a zero-dependency stdio proxy to the hosted Fless MCP server at `https://mcp.fless.io/mcp`.

## What it does

Your agent researches apartments with live Fless data and hands you a pre-filled hunt link:

- **search_cities** — live + coming-soon cities
- **get_city_overview** — neighborhoods with median rents + WalkRating™ scores
- **get_neighborhood** — full detail (rents, scores, POI counts)
- **get_hunt_requirements** — every hunt field, enum, binary restriction (55+, pets, smoking), transparent pricing
- **build_hunt_link** — validate a brief → URL that pre-fills the entire hunt form
- **check_hunt_link** — created → opened → started lifecycle
- **search / fetch** — ChatGPT deep-research compatibility pair

All tools are read-only, no auth needed. Your human creates the account, verifies email, and pays — agents never do.

## Where we operate

Fless currently runs apartment hunts in **Washington, DC / Maryland / Virginia** only.

| ✅ Live now | 🚧 Coming soon |
|---|---|
| Alexandria, VA | Arlington, VA |
| Annapolis, MD | Baltimore, MD |
| Frederick, MD | Rockville, MD |
| Leesburg, VA | Silver Spring, MD |
| | Washington, DC |
| | Richmond, VA + more |

**Your city not listed?** We're expanding — check back, or join the waitlist at
[fless.io](https://fless.io). Agents: always call `search_cities` first.

## Install

### Claude Desktop / any stdio MCP client

```json
{
  "mcpServers": {
    "fless": {
      "command": "uvx",
      "args": ["fless-mcp"]
    }
  }
}
```

Or with pip:

```bash
pip install fless-mcp
fless-mcp   # speaks JSON-RPC on stdio
```

### Remote (no install needed)

Most clients connect to the hosted server directly:

```
https://mcp.fless.io/mcp
```

See per-assistant setup guides (Claude, ChatGPT, Perplexity, Grok, Mistral Vibe, Codex, OpenClaw, Hermes): **https://fless.io/ai-agents**

## Environment

| Variable | Default | Purpose |
|---|---|---|
| `FLESS_MCP_URL` | `https://mcp.fless.io/mcp` | Remote server (fallback: `https://www.fless.io/mcp`) |
| `FLESS_MCP_UA` | `fless-mcp/1.0.0 (+https://fless.io/ai-agents)` | User-Agent |

## The skill (recommended companion)

`fless-apartment-hunt` — an [Agent Skills](https://agentskills.io)-standard skill that teaches your agent the full workflow:

```bash
hermes skills install well-known:https://fless.io
# or from GitHub:
npx skills add fless-io/skills
```

## License

MIT
