fless-mcp 1.1.0

package/README.md

@@ -0,0 +1,86 @@
+# 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

package/index.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * fless-mcp — stdio proxy for the Fless remote MCP server.
+ * Bridges local stdio MCP clients (Claude Desktop, etc.) to
+ * https://mcp.fless.io/mcp with zero configuration.
+ */
+import { createInterface } from 'node:readline';
+import { request } from 'node:https';
+import { request as httpRequest } from 'node:http';
+
+const REMOTE = process.env.FLESS_MCP_URL || 'https://mcp.fless.io/mcp';
+const UA = process.env.FLESS_MCP_UA || 'fless-mcp-npm/1.0.0 (+https://fless.io/ai-agents)';
+
+const rl = createInterface({ input: process.stdin });
+
+rl.on('line', (line) => {
+  line = line.trim();
+  if (!line) return;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    process.stderr.write(`fless-mcp: dropping non-JSON: ${line.slice(0, 80)}\n`);
+    return;
+  }
+
+  const url = new URL(REMOTE);
+  const mod = url.protocol === 'https:' ? request : httpRequest;
+  const req = mod(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json, text/event-stream',
+      'User-Agent': UA,
+    },
+    timeout: 120000,
+  }, (res) => {
+    let body = '';
+    res.on('data', (c) => { body += c; });
+    res.on('end', () => {
+      const ct = res.headers['content-type'] || '';
+      if (ct.includes('text/event-stream')) {
+        for (const sse of body.split('\n')) {
+          if (sse.startsWith('data:')) {
+            const payload = sse.slice(5).trim();
+            if (payload) process.stdout.write(payload + '\n');
+          }
+        }
+      } else if (body) {
+        process.stdout.write(body.replace(/\n$/, '') + '\n');
+      }
+      process.stdout.write('');
+    });
+  });
+
+  req.on('error', (e) => {
+    const err = { jsonrpc: '2.0', id: parsed.id ?? null,
+      error: { code: -32000, message: `fless-mcp proxy error: ${e.message}` } };
+    process.stdout.write(JSON.stringify(err) + '\n');
+  });
+
+  req.on('timeout', () => {
+    req.destroy();
+    const err = { jsonrpc: '2.0', id: parsed.id ?? null,
+      error: { code: -32000, message: 'fless-mcp proxy timeout (120s)' } };
+    process.stdout.write(JSON.stringify(err) + '\n');
+  });
+
+  req.write(line);
+  req.end();
+});
+
+rl.on('close', () => process.exit(0));

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "fless-mcp",
+  "version": "1.1.0",
+  "description": "Fless apartment-hunting MCP server — research cities, neighborhoods, rents, and build pre-filled hunt links. Stdio proxy to https://mcp.fless.io/mcp.",
+  "main": "index.mjs",
+  "type": "module",
+  "bin": {
+    "fless-mcp": "./index.mjs"
+  },
+  "keywords": ["mcp", "apartment", "hunting", "rental", "ai", "agent", "llm"],
+  "license": "MIT",
+  "homepage": "https://fless.io/ai-agents",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fless-io/skills"
+  }
+}