tutti-mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,54 +1,37 @@
-# tutti-mcp
+# 🇨🇭 tutti MCP
 
-> Search tutti.ch Swiss classifieds from an AI agent or a JSON CLI — anonymous and read-only.
+> Search tutti.ch Swiss classifieds from your AI agent or the command line — **anonymous and read-only by design**.
 
+[![npm version](https://img.shields.io/npm/v/tutti-mcp.svg)](https://www.npmjs.com/package/tutti-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/tutti-mcp.svg)](https://www.npmjs.com/package/tutti-mcp)
+[![license](https://img.shields.io/npm/l/tutti-mcp.svg)](./LICENSE)
 [![MCP](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io)
-[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
-`tutti-mcp` exposes the same compact tutti.ch search core through two entry points:
-
-- `tutti-mcp`: MCP stdio server for Claude, Codex, Cursor, and other MCP-capable clients
-- `tutti`: CLI with matching subcommands and JSON output
+A [Model Context Protocol](https://modelcontextprotocol.io) server that gives any MCP-capable agent (Claude, Codex, Cursor, …) the ability to search listings on [`tutti.ch`](https://www.tutti.ch), fetch listing details, browse categories, and resolve Swiss localities. The same search core also ships as a `tutti` CLI with JSON output — handy for scripts and shell-based agents.
 
 Ask your agent things like:
 
-- "Search tutti for a bike under 300 CHF in Zürich."
-- "Find free sofas near Bern."
-- "Get details for tutti listing 81828298."
-- "Show me the available tutti categories."
+- *"Search tutti for a bike under 300 CHF in Zürich."*
+- *"Find free sofas within 10 km of Bern."*
+- *"Get details for tutti listing 81828298."*
+- *"Which tutti categories are there for furniture?"*
 
-The package is intentionally anonymous read-only: no login, messaging, favorites, posting, caching, or bulk export.
+**Why read-only?** No login, no messaging, no favorites, no posting, no bulk export. Nothing this server does can touch your account or spam sellers — an agent can browse freely with zero risk. See [Safety model](#safety-model).
 
 ---
 
-## Quick Start
-
-After publishing to npm, run the MCP server directly with `npx`:
+## Quick start
 
-```sh
+```bash
 npx -y tutti-mcp
 ```
 
-Use the CLI through the `tutti` bin:
-
-```sh
-npx -y -p tutti-mcp tutti search velo --max 300 --limit 5
-```
-
-Run from a local checkout:
-
-```sh
-npm install
-npm run build
-node dist/cli.js search velo --max 300 --limit 5
-```
-
-The MCP server speaks stdio, so you normally let your client spawn it.
+The server speaks MCP over stdio, so you normally don't run it by hand — you point your MCP client at it and let the client spawn it. Pick your client below. Requires Node.js 20+.
 
 <details>
 <summary><strong>Claude Code</strong></summary>
 
-```sh
+```bash
 claude mcp add tutti -- npx -y tutti-mcp
 ```
 
@@ -58,7 +41,7 @@ Restart Claude Code or start a new session after adding the server, then check `
 <details>
 <summary><strong>Claude Desktop</strong></summary>
 
-Add this to `claude_desktop_config.json`:
+Add this to your `claude_desktop_config.json` (Settings → Developer → Edit Config):
 
 ```json
 {
@@ -77,11 +60,11 @@ Restart Claude Desktop after editing the file.
 <details>
 <summary><strong>Codex</strong></summary>
 
-```sh
+```bash
 codex mcp add tutti -- npx -y tutti-mcp
 ```
 
-Start a new Codex session after adding the server; MCP tools are injected when the session starts.
+Start a **new** Codex session after adding the server (MCP tools aren't injected into a running turn), then confirm with `/mcp` in the TUI.
 </details>
 
 <details>
@@ -101,83 +84,103 @@ Most clients accept a config of this shape:
 ```
 </details>
 
-Requires Node.js 20 or newer.
+No credentials, no configuration — the server works anonymously out of the box.
 
 ---
 
 ## Tools
 
-All listing URLs use `https://www.tutti.ch/de/vi/<listingID>`. Prices are returned as tutti.ch formats in CHF, for example `"40.-"`.
+All listing URLs use `https://www.tutti.ch/de/vi/<listingID>`. Prices are returned as tutti.ch formats them, in CHF — for example `"40.-"`.
 
 | Tool | Purpose | Auth required | Writes? |
 | --- | --- | :---: | :---: |
-| `search_listings` | Search listings by query, category, price, locality, radius, sort, and cursor. | No | No |
+| `search_listings` | Search listings by query, category, price range, locality, radius, sort, and cursor. | No | No |
 | `get_listing` | Fetch compact detail for one listing id, including description, seller, and up to five image URLs. | No | No |
 | `get_categories` | Return `{ id, label, children }` category nodes; ids are usable as `categoryId`. | No | No |
 | `search_localities` | Search Swiss locality names before using location filters. | No | No |
 
-`search_listings` returns `nextCursor` when another page is available. Pass that value back as `cursor`.
+`search_listings` returns `nextCursor` when another page is available — pass that value back as `cursor` to get the next page.
 
 When `location` is provided, the server resolves the text to the top matching Swiss locality. Use `search_localities` first when the place name is ambiguous or misspelled.
 
 ---
 
-## Suggested Workflows
+## Suggested workflows
 
 **Find listings near a place**
 
 1. `search_localities` for the place name if ambiguity matters.
 2. `search_listings` with `location`, optional `radiusKm`, and price filters.
 3. Follow `nextCursor` with another `search_listings` call for page 2.
-4. Use `get_listing` for the items that need full details.
+4. `get_listing` for the items that need full details.
 
 **Browse by category**
 
-1. `get_categories`.
-2. Pick a category `id`.
-3. `search_listings` with `categoryId`.
+1. `get_categories` → 2. pick a category `id` → 3. `search_listings` with `categoryId`.
 
-**Use from the CLI**
+---
 
-```sh
-node dist/cli.js search velo --max 300 --limit 5
-node dist/cli.js search velo --location "Zürich" --radius 10 --max 300
-node dist/cli.js get 81828298
-node dist/cli.js categories
-node dist/cli.js localities "zür"
-```
+## CLI
 
-Installed package bins:
+The package also installs a `tutti` bin with subcommands mirroring the MCP tools:
 
-```sh
+```bash
+# One-off with npx
 npx -y -p tutti-mcp tutti search velo --max 300 --limit 5
-npx -y -p tutti-mcp tutti get 81828298
 
-tutti search velo --max 300 --limit 5
+# Or install globally
+npm install -g tutti-mcp
+tutti search velo --location "Zürich" --radius 10 --max 300
 tutti get 81828298
 tutti categories
 tutti localities "zür"
 ```
 
-All CLI commands print JSON to stdout. Output is pretty-printed on a TTY and compact otherwise. Errors are written to stderr and return exit code 1.
+```
+Usage:
+  tutti search <query> [--category id] [--min n] [--max n] [--free] [--location name] [--radius km] [--sort timestamp] [--asc] [--cursor c] [--limit n]
+  tutti get <listingId>
+  tutti categories
+  tutti localities <query>
+```
+
+All commands print JSON to stdout — pretty-printed on a TTY, compact otherwise, so output pipes cleanly into `jq`. Errors go to stderr with exit code 1.
+
+```bash
+tutti search sofa --free --location Bern --radius 10 | jq '.listings[].title'
+```
 
 ---
 
-## Safety Model
+## Safety model
 
 This server performs anonymous read-only operations only.
 
 - No credentials are accepted or needed.
 - No listings are posted, edited, favorited, or messaged.
 - No HTTP server is exposed; MCP uses stdio only.
-- No raw `tutti-api` objects are returned to agents. Responses are mapped to compact project-owned payloads.
+- No raw upstream objects are returned to agents — responses are mapped to compact, project-owned payloads.
 - Upstream requests are throttled to avoid rapid repeated traffic and retried only for transient failures.
 
 ---
 
-## Develop From Source
+## Troubleshooting
 
-```sh
+| Symptom | Fix |
+| --- | --- |
+| MCP client doesn't show the tools | Restart the client or start a new session so it respawns the server. |
+| `location` matches the wrong place | Run `search_localities` first, then use a more specific place name. |
+| Search fails with a rate-limit message | Wait a few minutes before retrying; the upstream API is behind Cloudflare. |
+| CLI output is one line | Expected when stdout is not a TTY — pipe it through `jq` if needed. |
+| Live tests are skipped | Set `TUTTI_LIVE=1` explicitly. |
+| Inspector command opens a UI instead of running once | Add `--cli` and an explicit `--method`, as shown below. |
+
+---
+
+## Develop from source
+
+```bash
+git clone https://github.com/domwoe/tutti-mcp.git
 cd tutti-mcp
 npm install
 npm run build
@@ -185,62 +188,42 @@ npm run build
 
 Point a client at the built entrypoint:
 
-```sh
+```bash
 claude mcp add tutti -- node /absolute/path/to/tutti-mcp/dist/mcp.js
 ```
 
-Before publishing:
-
-```sh
-npm pack --dry-run
-npm publish
-```
-
 ### Verification
 
-```sh
+```bash
 npm run typecheck
 npm test
 npm run build
 ```
 
-Live smoke tests are skipped by default:
+Live smoke tests against the real upstream API are skipped by default:
 
-```sh
+```bash
 TUTTI_LIVE=1 npm test
 ```
 
-Manual MCP checks:
+Manual MCP checks with the inspector:
 
-```sh
+```bash
 npx @modelcontextprotocol/inspector --cli --method tools/list node dist/mcp.js
 npx @modelcontextprotocol/inspector --cli node dist/mcp.js --method tools/call --tool-name search_listings --tool-arg query=velo --tool-arg priceMax=300
 ```
 
 Manual CLI check:
 
-```sh
+```bash
 node dist/cli.js search velo --max 300 --limit 5
 ```
 
 ---
 
-## Troubleshooting
-
-| Symptom | Fix |
-| --- | --- |
-| MCP client does not show the tools | Restart the client or start a new session so it respawns the server. |
-| `location` matches the wrong place | Run `search_localities` first, then use a more specific place name. |
-| Search fails with a rate-limit message | Wait a few minutes before retrying; the upstream API is behind Cloudflare. |
-| CLI output is one line | Expected when stdout is not a TTY; pipe it through `jq` if needed. |
-| Live tests are skipped | Set `TUTTI_LIVE=1` explicitly. |
-| Inspector command opens a UI instead of running once | Add `--cli` and an explicit `--method`, as shown above. |
-
----
-
-## Legal Caveat
+## Legal caveat
 
-This package uses a reverse-engineered private API via the `tutti-api` npm package. tutti.ch has no official public API, and its Nutzungsbedingungen prohibit automated queries and reproduction of listings. This project is intended for personal and prototype use only. It does not provide bulk-export or scraping features. Use it responsibly and respect tutti.ch's terms and rate limits.
+This package uses a reverse-engineered private API via the [`tutti-api`](https://www.npmjs.com/package/tutti-api) npm package. tutti.ch has no official public API, and its Nutzungsbedingungen prohibit automated queries and reproduction of listings. This project is intended for personal and prototype use only — it deliberately provides no bulk-export or scraping features. Use it responsibly and respect tutti.ch's terms and rate limits.
 
 ## Disclaimer
 
@@ -248,4 +231,4 @@ This is an unofficial community project and is not affiliated with tutti.ch or S
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutti-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP server and CLI for searching tutti.ch classifieds.",
   "license": "MIT",
   "author": "domwoe",