内容
# Partle 市场 MCP 服务器
[模型上下文协议](https://modelcontextprotocol.io/) 服务器，用于 Partle 本地市场 — 在您附近的实体店铺中找到产品，要求 AI 为您添加列表，所有操作无需离开您的助手。
**130,000+ 产品**，涵盖 **~16,000 家店铺**。读取操作无需身份验证，写入操作需要 `pk_…` API 密钥。
## 两种运行方式
### 远程（推荐 — 零设置）
将您的 MCP 客户端指向：
```
https://partle.rubenayla.xyz/mcp/
```
就这样。支持流式 HTTP 传输，MCP 规范 2025-06-18。每个客户端的安装说明：[`/documentation/mcp-setup/`](https://partle.rubenayla.xyz/documentation/mcp-setup/)。
### 本地标准输入输出（适用于偏好可安装服务器的客户端，或用于 Glama / Smithery 评分）
```bash
pip install partle-mcp
partle-mcp
```
或使用 `uvx`（无需安装）：
```bash
uvx partle-mcp
```
或使用 Docker：
```bash
docker run --rm -i ghcr.io/rubenayla/partle-mcp
```
标准输入输出软件包代理到公共 REST API `https://partle.rubenayla.xyz`，因此您不需要数据库或本地后端。
#### Claude 桌面版 / Claude 代码（标准输入输出）
```json
{
"mcpServers": {
"partle": {
"command": "uvx",
"args": ["partle-mcp"]
}
}
}
```
## 工具（共 20 个）
### 读取（无需身份验证）
| 工具 | 用途 |
|------|---------|
| `search_products` | 按名称、价格范围、标签、店铺搜索目录。支持跨语言语义搜索。 |
| `get_product` | 按 ID 获取一个产品的完整记录。 |
| `search_stores` | 按名称或地址搜索/列出店铺。 |
| `get_store` | 按 ID 获取一个店铺的完整记录。 |
| `get_stats` | 平台范围内的总数。 |
| `search_wanted` | 浏览 `/wanted` 上的公共 **购买请求** — 浏览人们正在寻找但尚未找到的商品。可以与 `search_products` 交叉引用以提供匹配结果。 |
### 写入（身份验证）
两种身份验证方式，按优先级排序：
1. **OAuth（推荐）** — 当您在 claude.ai 或任何支持 OAuth 的 MCP 客户端中添加 Partle 作为自定义连接器时，客户端会引导您完成一次性同意屏幕，并自动附加 bearer token。作用域：`products:read`、`products:write`、`inventory:read`、`inventory:write`。在 [/account](https://partle.rubenayla.xyz/account) → **Connected apps** 中撤销。RFC 9728 元数据在 [`/.well-known/oauth-protected-resource`](https://partle.rubenayla.xyz/.well-known/oauth-protected-resource)；RFC 7591 动态客户端注册在 `/oauth/register`。
2. **API 密钥（备用）** — 将 `api_key` 参数传递给任何写入工具。在 [/account](https://partle.rubenayla.xyz/account) → **API Keys** 中生成。当您的客户端不支持 OAuth（原始脚本、程序化代理）时使用。
**产品** — 公共目录列表。
| 工具 | 用途 |
|------|---------|
| `create_product` | 添加新列表。设置 `verified=false` 时，AI 代表未确认的人类提出。 |
| `update_product` | 编辑您拥有的列表。 |
| `delete_product` | 删除您拥有的列表。 |
| `upload_product_image` | 附加图像（base64 或 URL）。 |
| `delete_product_image` | 从产品中删除图像。 |
| `get_my_products` | 列出您创建的产品。 |
> 远程 HTTP 服务器还提供 `get_upload_url`（为现有产品重新获取签名上传 URL）。此标准输入输出软件包中未公开 — 如果需要，请使用远程服务器。
**库存** — 私人工作坊跟踪（已拥有 / 想要 / 待售 / 已售 / 已丢弃）。私有；**不会**出现在公共 `/wanted` 源中。
| 工具 | 用途 |
|------|---------|
| `get_my_inventory` | 列出您的库存项目。可按状态、项目、自由文本筛选。 |
| `add_inventory_item` | 在任何生命周期状态下添加一行。 |
| `update_inventory_item` | 修补任何字段。 |
| `delete_inventory_item` | 永久删除一行。 |
| `mark_for_sale` | 方便：翻转 `owned` 项目为 `for_sale` 并设置要价。 |
| `mark_sold` | 方便：翻转 `for_sale` 项目为 `sold`。 |
**购买请求** — `/wanted` 上的公共需求侧帖子。与个人库存独立。
| 工具 | 用途 |
|------|---------|
| `create_buy_request` | 发布公共购买请求（标题、描述、数量、选定 `max_price` 和 `contact`）。 |
### 反馈
| 工具 | 用途 |
|------|---------|
| `submit_feedback` | 发送关于您的集成体验的自由格式反馈。 |
## 公共 REST API
相同的数据，也可以通过普通 HTTP 访问，供不支持 MCP 的客户端使用：
- `GET /v1/public/products?q=cerrojo&limit=10` — 搜索产品
- `GET /v1/public/stores?q=Madrid&limit=10` — 搜索店铺
- `GET /v1/public/wanted?q=bolt&limit=10` — 列出公开的购买请求
- `GET /v1/public/stats` — 平台总数
- `POST /v1/public/feedback` — 提交反馈
基准 URL：`https://partle.rubenayla.xyz`。速率限制为每小时 100 次请求/ IP 地址。
完整文档：[`/documentation/`](https://partle.rubenayla.xyz/documentation/) · OpenAPI：[`/openapi.json`](https://partle.rubenayla.xyz/openapi.json) · 发现：[`/.well-known/mcp.json`](https://partle.rubenayla.xyz/.well-known/mcp.json)。
## 示例
> **您：** “使用 Partle 查找一款低于 €50 的钻头。”
>
> **Claude：** *(调用 `search_products(query="drill", max_price=50)`)*
>
> 返回 Blackspur 13pc 高速钻头套装，€4.99（Lenehans，IE），Flotec 钻泵 225 GPH，€17.14（Kooyman Megastore，NL），以及其他几个 — 每个都有一个 `partle_url` 来查看列表。
更多示例请参见[设置指南](https://partle.rubenayla.xyz/documentation/mcp-setup/#example-queries)。
## 许可证
Apache-2.0 — 请参阅 [LICENSE](LICENSE)。
