Metadata-Version: 2.5
Name: mcp-url-locator
Version: 0.1.0
Summary: 根据用户输入返回对应网页 URL 的 MCP 工具集（可部署到魔搭/ModelScope 社区）
Project-URL: Homepage, https://github.com/example/mcp-url-locator
Project-URL: Repository, https://github.com/example/mcp-url-locator
Project-URL: Documentation, https://github.com/example/mcp-url-locator#readme
Project-URL: Issues, https://github.com/example/mcp-url-locator/issues
Author: URL Locator Contributors
License: MIT
License-File: LICENSE
Keywords: agent,mcp,modelcontextprotocol,search,url,webpage
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.2.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# mcp-url-locator · 网页 URL 定位 MCP 工具

一套符合 [MCP 协议](https://modelcontextprotocol.io) 的智能体工具：**根据用户输入
返回对应网页的 URL**。Agent 只需给出关键词或自然语言问题，即可拿到匹配网页的标题、
可点击链接与摘要，便于继续打开或引用原文。

## 工具列表

| 工具 | 用途 | 关键参数 |
| --- | --- | --- |
| `find_webpage_url` | 根据用户输入返回对应网页的 URL（标题 + 链接 + 摘要） | `query`、`max_results`、`site` |

`query` 为用户检索词（如「西北农林科技大学 招生」）；`max_results` 默认 10、上限 30；
`site` 用于限定站点域名（如 `nwafu.edu.cn`），只返回该站内网页，留空则不限定。

## 快速开始（本地）

```powershell
cd mcp-url-locator
uv sync --extra dev
uv run mcp-url-locator
```

验证工具是否已注册：

```powershell
uv run python -m url_locator.tools_probe
```

## 部署到魔搭社区（可托管部署）

魔搭 STDIO 托管只支持 `npx` / `uvx`，且只能拉取**已发布到 PyPI 的包**。服务配置如下：

```json
{
  "mcpServers": {
    "url-locator": {
      "command": "uvx",
      "args": ["mcp-url-locator"],
      "env": {
        "URL_LOCATOR_SEARCH": "duckduckgo",
        "URL_LOCATOR_MAX_RESULTS": "10",
        "URL_LOCATOR_TIMEOUT": "15"
      }
    }
  }
}
```

创建步骤：

1. 打开 [创建 MCP 服务](https://modelscope.cn/mcp/servers/create)，保持
   「从 GitHub 仓库快速创建」。
2. GitHub 地址填本仓库地址，英文名称填 `url-locator`，托管类型选
   「可托管部署」。
3. 平台会自动解析本 README 的首个服务配置并执行部署检测
   （`uvx` 安装包 → 连接 → `list_tools`），通过后即可在工具页测试使用。

同一份配置也可直接用于 Claude Desktop / Cursor 等本地客户端。

## 环境变量

| 变量 | 说明 |
| --- | --- |
| `URL_LOCATOR_SEARCH` | 搜索引擎后端：`duckduckgo`（默认）或 `bing` |
| `URL_LOCATOR_MAX_RESULTS` | 默认返回条数（默认 10） |
| `URL_LOCATOR_MAX_RESULTS_CAP` | 单次返回上限（默认 30） |
| `URL_LOCATOR_TIMEOUT` | 单请求超时秒数（默认 15） |
| `URL_LOCATOR_SITE_RESTRICT` | 逗号分隔的站点白名单，进一步收敛结果 |
| `URL_LOCATOR_USER_AGENT` | 自定义 User-Agent（默认内置 UA） |
| `URL_LOCATOR_TRANSPORT` | `stdio`（默认）或 `streamable-http` |

## 远程 HTTP 部署（Docker / Serverless）

```powershell
uv run mcp-url-locator --transport streamable-http --port 8000 --auth-token 换成随机长令牌
```

或使用仓库 `Dockerfile` 构建镜像，健康检查端点位于 `GET /healthz`。

## 合规说明

仅检索公开可见的网页，不绕过登录 / 权限校验；内置随机 User-Agent、超时与限速，
请勿高频抓取。重要信息请以原始网页为准。
