内容
# kp-mcp
**塞尔维亚语** · [🇬🇧 英语](README.en.md)
[](https://github.com/OpenSource03/kp-mcp/actions/workflows/deploy.yml)
[](https://www.npmjs.com/package/@opensource03/kp-mcp)
[](https://www.npmjs.com/package/@opensource03/kp-mcp)
[](LICENSE)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
MCP（模型上下文协议）服务器，用于 [kupujemprodajem.com](https://www.kupujemprodajem.com) — 塞尔维亚最大的分类广告平台。它允许任何支持MCP的AI助手（Claude、ChatGPT、Cursor、Continue、Cline、Windsurf、Zed等）搜索KP分类广告并读取单个广告的完整详细信息。
## 功能
三个工具，均可通过一个MCP端点访问：
| 工具 | 功能 |
|---|---|
| `list_kp_categories` | KP分类法搜索 — **必须首先调用** 以获取正确的`categoryId` / `groupId`。88个类别，~1170个分组，已内置于服务器。 |
| `search_kp` | 分类广告搜索，支持筛选：价格（欧元/塞尔维亚第纳尔）、状态、排序、分页、范围（标题/描述）。 |
| `fetch_listing` | 单个广告的完整详细信息：描述、所有图片、卖家资料（评论、验证）、汽车/房地产规格。 |
所有工具均在支持MCP应用规格的主机（Claude Desktop、claude.ai等）上渲染交互式UI小部件；否则则回退到纯文本。
## 使用 — 通过托管端点（推荐）
最简单的方法 — 使用托管在具有塞尔维亚IP地址的基础设施上的公共端点（KP服务在国内IP地址上提供更好的结果）：
**`https://kp.osrc.io/mcp`**
将其添加为AI主机（claude.ai → 设置 → 连接器，Cursor → MCP服务器等）中的“自定义连接器”。无需授权。
## 本地运行（npx，无需安装）
最简单的本地变体 — 无需克隆，无需构建。仅需Node 20+：
```jsonc
// .mcp.json（Claude Code）或 claude_desktop_config.json
{
"mcpServers": {
"kp": {
"command": "npx",
"args": ["-y", "@opensource03/kp-mcp"]
}
}
}
```
适用于Cursor / Continue / Cline / Windsurf / Zed等 — 相同的格式，只需在它们的MCP配置文件中。第一次运行`npx`从npm下载包（~5秒）；之后缓存运行。
直接从终端运行（用于测试）：
```bash
npx -y @opensource03/kp-mcp # stdio 模式
PORT=3000 npx -y -p @opensource03/kp-mcp kp-mcp-http # HTTP 模式，端口3000
```
## 本地运行（从git源代码）
如果您想修改代码：
```bash
git clone https://github.com/OpenSource03/kp-mcp.git
cd kp-mcp && pnpm install && pnpm build
```
注册 — 使用到`dist/stdio.js`的绝对路径：
```jsonc
{ "mcpServers": { "kp": { "command": "node", "args": ["/absolute/path/to/kp-mcp/dist/stdio.js"] } } }
```
## 自托管HTTP
```bash
PORT=3000 pnpm start:http
```
端点：`POST/GET/DELETE http://localhost:3000/mcp`（可流式传输的HTTP）。健康检查在`/health`。
使用任何反向代理或隧道进行公开暴露。
## 使用提示
KP搜索有几个特定之处 — 工具已调整模型以创建良好的请求，但以下是需要注意的事项：
- **始终首先使用 `list_kp_categories`** — 显著提高结果质量。否则，“RTX 3090”按价格排序会返回27€的水冷块。
- **不要在搜索中添加“显卡”、“手机”、“汽车”**。模型代码是唯一的：'RTX 3090'有效，'RTX 3090 显卡'返回0。
- **跟踪 `priceFrom` 和 `currency`**。KP在同一列表中提供欧元和塞尔维亚第纳尔的广告。
- **`fetch_listing`** 几乎是推荐广告的必要条件 — 搜索结果不包含卖家评论、汽车年份或完整图片。
- **拉丁字母和西里尔字母** 都有效。变音符号无关紧要（'frizider' ≡ 'frižider'）。
## 开发
```bash
pnpm dev:stdio # tsx，无需rebuild循环
pnpm dev:http
pnpm typecheck
pnpm inspect # 在编译的dist/stdio.js上运行MCP Inspector
```
## 架构
- TypeScript，严格模式，无`any`，无`as`强制转换（仅在系统边界）
- 原生`fetch`，使用`__NEXT_DATA__`的正则表达式解析（无JSDOM — 在Node、边缘、Worker上运行）
- 内存cookie jar，用于与KP会话的稳定性
## 许可证
MIT
