内容
MCP 服务器
官方 [模型上下文协议](https://modelcontextprotocol.io) 服务器，为 [WellMarked.io](https://wellmarked.io) 提供服务 — 让您的 AI 将任何 URL 转换为干净，批量提取多页内容取整个网站，并在 Claude Desktop Code、Cursor 或任何 MCP 主机中搜索网络。
它 [`wellmarked`](https://.com/package/wellmarked) SDK 之上的一层薄，因此继承了 SDK 的身份验证错误、重试/回和多态作业轮询 工具列表
| 工具 | 功能描述 |
| ---| `extract` | 获取一个 URL 并返回其主要内容的 Markdown + 元数据。 `bulk` | 提交多个（Pro+）。默认情况下获取结果。 |
| `crawl` | 从根 URL 爬取站点到指定深度（Pro+）。返回异步作业。 |
| `search` | 搜索网络并返回每个结果页面为干净的 Markdown，单次调用（Pro+）。 |
| `get_job` | 按 ID 轮询批量/爬取。 |
| `wait_for | 阻塞直到，然后返回所有结果。 `get_usage` | 费周期配额、使用量、限制、剩余 |
`extract`、`bulk`、`crawl` 和 `search `format`（`markdown` / `json` /` / `html` / `links`）和每个请求的合规性覆盖（`allow_domains` / `deny_patterns` /_robots`）；`extract`、`bulk` 和 `crawl目标超时重试次数，以及 `crawl` 接受 ` 预算。
### 结构化输出
每个工具都声明Schema` 并返回 `structuredContent` — 类型化的 JSON，因此代理可以读取 `status`、`completed`、`ok` 或 `tokens 作为真正的字段，而不是从渲染的句子中模式匹配它们：
{
"kindcrawl",
"job "job_abc",
status": "done",
12,
" 12,
"done": true,
"truncated": false,
"results": [
": "https://", "depth": ok": true, "markdown": "# A" },
url": "https://", "depth": "ok": false, "error": "target_timeout" }
]
}
```
人类可读的在通常的文本块中不支持结构化输出的主机行为与以前完全相同。错误格式，仅限 API 的稳定。
> **未作为工具 API 密钥轮keys/rotate`）密钥轮换（`/webhook/rotate`）。两者都是破坏性和不可逆的 — 旧凭证在调用返回时立即失效流程 — 对于自主代理来说，这不是合适的形状。从仪表板 轮换。
## 设置
根据您的主机，有两种连接方式：
- **远程（托管，OAuth）** — 适用于 Claude.ai 和其他支持远程 MCP 服务器的主机。无需复制 API 密钥在浏览器中登录并授权。参见下面的[远程服务器](#remote-server-hosted--oauth)。
- **本地（stdio，API ** — 适用于 Claude Desktop、Claude Code 和任何启动本地服务器的主机。您通过环境提供 `wm_...。在 [wellmarked.io](https://wellmarked.io) 生成一个。
### 远程服务器（托管 — OAuth）
将 WellMarked 添加为**自定义连接器**，并指向：
```
https://mcp.wellmarked.io/mcp
```
您的主机自动发现授权服务器（通过 `/.well-known/oauth-protected-resource`），引导您登录 WellMarked 并批准连接，并接收限定范围、过期的令牌 — 无需粘贴密钥。连接器extract`、`bulkcrawl` 和 `search`；它不能创建或轮。
在 **Claude.ai** 中：设置 → 连接器连接器 → 粘贴上面的 URL → 按照登录提示进行操作。
远程服务器通过 Streamable HTTP 使用 MCP，在本地服务器相同的工具 — 工具表面相同（由 `test/` 中的奇偶校验测试强制执行）。
### Claude Desktop
在 `claude_desktop_config.json` 中添加（设置 → 开发者 → 编辑配置）：
```json
{
"mcpServers": {
"wellmarked": {
"command": "npx",
"args": ["-y", "wellmarked-mcp"],
"env": {
"WELLMARKED_API_KEY": "wm_your_key_here"
}
}
}
}
```
### Claude Code
```bash
claude mcp add wellmarked --env WELLMARKED_API_KEY=wm_your_key_here -- npx -y wellmarked-mcp
```
### Cursor / 其他 MCP 主机
任何通过 stdio 启动 MCP 服务器的主机都可以使用 — 指向 `npx -y wellmarked-mcp`，并在环境中设置 `WELLMARKED_API_KEY`。
## 环境变量
本地（stdio）服务器：
| 变量 | 是否必需 | 描述 |
| --- | --- | --- |
| `WELLMARKED_API_KEY` | 是 | 您的 `wm_...` API 密钥。 |
| `WELLMARKED_TIMEOUT_MS` | 否 | 每个请求的超时时间（毫秒）（默认为 `30000`）。 |
远程（Streamable HTTP）服务器 — 仅当您自行托管它时（`npm run start:http`）：变量 | 是否必需 || --- | --- | --- |
| `PORT` | 否监听端口（默认为 `300；Railway 设置）。 `MCP_PUBLIC_URL 否 | 此服务器的，用于受保护的资源元未设置，则从请求 Host 中派生。 |
|ELLMARKED_TIMEOUT_MS` 每个请求的超时）。 |
远程服务器 `WELLMARKED_API 每个请求都使用自己的 OAuth 承载令牌## 本地开发
npm install
build # 将 TypeScript 编译到 dist/
npm start # 在 stdio 上运行编译后的服务器
npm run start:http # 或者运行远程（Streamable HTTP）服务器
npm test # 跨两个入口点的工具列表奇偶校验
# 使用 MCP Inspector 交互式检查 stdio 服务器：
WELLMARKEDwm_... @modelcontext dist/index.js
```
## 许可证 参见 [LICENSE](./LICENSE)。
