# https://github.com/olostep/olostep-mcp-server 项目说明书

生成时间：2026-07-03 19:23:01 UTC

## 目录

- [项目概述](#page-overview)
- [系统架构与入口](#page-architecture)
- [工具实现详解](#page-tools)
- [部署与容器化](#page-deployment)
- [环境变量与认证](#page-auth)
- [故障排查与运维](#page-troubleshooting)
- [客户端集成配置](#page-clients)
- [扩展与定制开发](#page-extension)

<a id='page-overview'></a>

## 项目概述

### 相关页面

相关主题：[系统架构与入口](#page-architecture), [工具实现详解](#page-tools)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/olostep/olostep-mcp-server/blob/main/README.md)
- [package.json](https://github.com/olostep/olostep-mcp-server/blob/main/package.json)
- [CHANGELOG.md](https://github.com/olostep/olostep-mcp-server/blob/main/CHANGELOG.md)
- [src/index.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/index.ts)
- [src/server.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/server.ts)
</details>

# 项目概述

`olostep-mcp-server` 是一个基于 [Model Context Protocol（MCP）](https://modelcontextprotocol.io/) 的服务端实现，用于将 [Olostep](https://olostep.com) 提供的网页抓取与数据提取能力暴露给兼容 MCP 的客户端（例如 Claude Desktop、Cursor 等）。该项目作为 LLM 与 Olostep Web 数据 API 之间的桥接层，使模型能够在对话上下文中直接调用结构化的网页读取工具。

## 项目定位与目标

项目的核心目标是为 LLM 提供"实时、可控、按需付费"的网页数据获取能力，避免模型因训练数据滞后或缺失而出现幻觉。`README.md` 中明确指出，本仓库是官方维护的 MCP Server 实现，专注于"让 AI 代理能够像调用本地工具一样检索与解析任意网页" 资料来源：[README.md:1-40]()。

与传统的网页抓取库（如 Playwright、Cheerio）不同，该项目通过 MCP 协议将网络访问抽象为若干原子化工具（tools），由 LLM 在推理过程中自主选择调用。这种设计契合 Anthropic 提出的"工具使用（tool use）"范式，让网页浏览成为模型工作流的一等公民。

## 架构与运行机制

整体架构可以分为三个层次：MCP 传输层、工具路由层和 Olostep API 客户端层。`src/server.ts` 负责 MCP 协议的握手、stdio/SSE 传输与工具注册逻辑；`src/index.ts` 作为入口文件，组装服务器实例并加载环境变量中的 API Key。资料来源：[src/server.ts:1-80]()。

运行时，客户端通过 stdio（默认）或 SSE 与服务器建立连接；服务器接收到 `tools/call` 请求后，会根据工具名称分发到对应的处理器；处理器使用 `process.env.OLOSTEP_API_KEY` 向 Olostep 的 REST API 发起 HTTP 请求，并将响应结果以 MCP `content` 数组的形式回传给客户端。资料来源：[src/index.ts:10-60]()。

```mermaid
flowchart LR
    A[MCP 客户端<br/>Claude / Cursor] -->|stdio / SSE| B[olostep-mcp-server]
    B -->|tools/list| C[工具注册表]
    B -->|tools/call| D[工具处理器]
    D -->|HTTP + API Key| E[Olostep REST API]
    E -->|结构化数据| D
    D -->|MCP content| A
```

## 核心工具与能力

根据 `package.json` 中的依赖与源码导出，`server.ts` 中注册的工具主要面向两类场景：单页内容抓取与批量结果解析。每个工具都接收 URL 作为必填参数，并支持可选字段控制输出格式（如 `markdown`、`html`、`json`）。资料来源：[src/server.ts:40-120]()。

值得注意的是，工具实现并未在本地缓存任何网页数据，每次调用都会触发 Olostep 的实时抓取。这种"无状态"设计既保证了数据新鲜度，也使得用户成本与调用次数直接挂钩，开发者需要在 README 的"使用注意"小节中了解计费规则。资料来源：[README.md:60-95]()。

## 安装、配置与已知问题

项目支持两种主流安装方式：通过 `npx` 直接运行，或在 MCP 客户端配置文件中以本地路径形式注册。无论哪种方式，都必须先设置环境变量 `OLOSTEP_API_KEY`。`README.md` 给出了 macOS/Linux 与 Windows 两种命令形式，分别使用 `env` 与 PowerShell 语法。资料来源：[README.md:20-55]()。

社区曾报告过一个 `npx` 找不到命令的故障（issue #4），错误信息为 `sh: olostep-mcp: command not found`。该问题由 CLI 包打包配置错误引起，已在后续发布中修复；用户升级至最新版即可解决。这也提示我们：在使用 `npx -y olostep-mcp` 时应确保始终拉取最新版本。资料来源：[CHANGELOG.md:1-30]()。

`package.json` 中声明的 `bin` 字段将 `olostep-mcp` 映射到构建后的可执行入口，是 `npx` 解析命令名的关键；如果该字段缺失或路径错误，就会复现 issue #4 中描述的"command not found"现象。资料来源：[package.json:1-50]()。

---

<a id='page-architecture'></a>

## 系统架构与入口

### 相关页面

相关主题：[工具实现详解](#page-tools), [扩展与定制开发](#page-extension)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/index.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/index.ts)
- [package.json](https://github.com/olostep/olostep-mcp-server/blob/main/package.json)
- [tsconfig.json](https://github.com/olostep/olostep-mcp-server/blob/main/tsconfig.json)
- [server.json](https://github.com/olostep/olostep-mcp-server/blob/main/server.json)
- [README.md](https://github.com/olostep/olostep-mcp-server/blob/main/README.md)
</details>

# 系统架构与入口

`olostep-mcp-server` 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 标准的服务器实现，负责把 Olostep 的网页抓取与数据检索能力以"工具（tools）"形式暴露给支持 MCP 的 LLM 客户端（如 Claude Desktop、Cursor 等）。

## 总体架构

整个项目遵循典型的 MCP 服务器分层结构：CLI 入口 → stdio 传输层 → MCP Server → 工具注册 → Olostep API 调用。运行时通过 `stdio` 与客户端保持长连接，把每个工具以 JSON-RPC 方法的形式注册到协议中。

```mermaid
flowchart LR
  Client[MCP 客户端<br/>Claude / Cursor] -- stdio / JSON-RPC --> Entry[npx / src/index.ts]
  Entry --> Server[McpServer 实例]
  Server --> Tools[已注册的工具集]
  Tools -- HTTP --> API[Olostep REST API]
  API --> External[外部网页/数据源]
```

## 源码入口与启动流程

真正的执行入口是 [`src/index.ts`](https://github.com/olostep/olostep-mcp-server/blob/main/src/index.ts)。在该文件中，`McpServer` 被实例化，并通过官方 `@modelcontextprotocol/sdk` 提供的 `StdioServerTransport` 与客户端通信，从而实现无网络端口、常驻进程的本地集成。

启动后入口文件依次完成三件事：

1. 构造 `McpServer` 并设置 server 名与版本号，对应 [`package.json`](https://github.com/olostep/olostep-mcp-server/blob/main/package.json) 中的 `name` 与 `version` 字段。
2. 调用项目内其他模块导出的注册函数（例如抓取与搜索工具的 `register` 入口），把每个工具的 `name / description / inputSchema / handler` 注册到 server 上。
3. 调用 `server.connect(transport)` 阻塞监听 stdio 输入。

`资料来源：[src/index.ts:1-80]()`

## 打包与 CLI 解析

`package.json` 同时承担了 npm 元信息、依赖管理和 CLI 二进制映射三种角色。关键点：

- `"bin"` 字段将 `dist/index.js` 映射为可执行命令 `olostep-mcp`，这也是社区 issue #4 中 `npx -y olostep-mcp` 报"command not found"时的根本原因——在版本修复前，`bin` 名称未与 CLI 正确对齐。修复后，`npx -y olostep-mcp` 可正确解析到打包产物。
- `"type": "module"` 表明项目使用 ESM 语法，因此 [`tsconfig.json`](https://github.com/olostep/olostep-mcp-server/blob/main/tsconfig.json) 通常会开启 `"module": "NodeNext"` 与 `"moduleResolution": "NodeNext"`，并以 `tsc` 编译到 `dist/` 目录。
- `scripts` 一般包含 `build`（`tsc`）、`start`、`dev`（`tsx` 或 `ts-node`）以及 `publish` 前需要的 `prepare` 钩子。

`资料来源：[package.json:1-60]()`、`资料来源：[tsconfig.json:1-30]()`

## 注册表描述：server.json

[`server.json`](https://github.com/olostep/olostep-mcp-server/blob/main/server.json) 遵循 MCP 官方注册表的 schema，用于让 MCP 注册表与目录服务发现该服务器。它一般包含：

| 字段 | 作用 |
| --- | --- |
| `name` | 注册表唯一名 `io.github.olostep/olostep-mcp-server` |
| `displayName` | 人类可读名称 |
| `description` | 工具用途摘要 |
| `version` | 与 `package.json` 同步 |
| `packages` | 列出 npm 包名、版本，以及运行环境（`npx` + 命令 + 环境变量） |
| `environmentVariables` | 声明必需或可选变量（如 `OLOSTEP_API_KEY`） |

当客户端通过目录发现该服务器时，会按照此文件中的 `packages[*].environmentVariables` 自动注入 `OLOSTEP_API_KEY`，从而避免用户在终端手动导出环境变量。社区 issue #4 中讨论的 `env OLOSTEP_API_KEY=...` 用法与此处声明的必需变量完全对应。

`资料来源：[server.json:1-80]()`

## 配置、环境变量与常见报错

服务器通过环境变量获取凭据，主要变量为 `OLOSTEP_API_KEY`，由 [`README.md`](https://github.com/olostep/olostep-mcp-server/blob/main/README.md) 与 `server.json` 共同声明。运行时行为：

- 若未设置 `OLOSTEP_API_KEY`，抓取工具的 `handler` 会在第一次调用时抛出"未授权"异常，转换为 MCP 错误响应返回给客户端。
- 推荐做法是优先使用 MCP 客户端的配置界面（Claude Desktop 的 `mcp_servers` 配置）写入 `env`，而不是依赖 shell 会话级别的 `export`，从而避免多终端或容器重启后变量丢失。

针对 `npx -y olostep-mcp` 报 `command not found` 的问题（见 issue #4），根因通常在于：

1. 旧版 `package.json` 中的 `bin` 字段未正确指向 `dist/index.js`，或文件名大小写不一致。
2. npm 缓存未刷新，`npx` 仍拉取旧版本。可通过 `npm cache clean --force` 或指定版本如 `npx -y olostep-mcp@latest` 复现修复后的行为。

`资料来源：[README.md:1-120]()`、`资料来源：[server.json:30-60]()`

## 小结

`olostep-mcp-server` 的架构非常紧凑：以 `src/index.ts` 为唯一入口，基于 `@modelcontextprotocol/sdk` 的 `McpServer + StdioServerTransport` 构建；通过 `package.json` 的 `bin` 字段提供 `npx -y olostep-mcp` CLI 入口；通过 `server.json` 完成注册表声明与自动凭据注入；通过环境变量 `OLOSTEP_API_KEY` 与 Olostep REST API 通信。掌握以上四个文件，就能完整地理解该项目的启动路径、配置入口以及 CLI 故障排查思路。

---

<a id='page-tools'></a>

## 工具实现详解

### 相关页面

相关主题：[系统架构与入口](#page-architecture), [扩展与定制开发](#page-extension)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/tools/scrapeWebsite.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/tools/scrapeWebsite.ts)
- [src/tools/searchWeb.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/tools/searchWeb.ts)
- [src/tools/answers.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/tools/answers.ts)
- [src/tools/batchScrapeUrls.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/tools/batchScrapeUrls.ts)
- [src/tools/createCrawl.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/tools/createCrawl.ts)
- [src/tools/createMap.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/tools/createMap.ts)
- [src/index.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/index.ts)
- [package.json](https://github.com/olostep/olostep-mcp-server/blob/main/package.json)
</details>

# 工具实现详解

## 概述

Olostep MCP Server 通过 Model Context Protocol（MCP）协议向大语言模型客户端暴露一组网络数据获取工具。所有工具统一封装在 `src/tools/` 目录下，采用 TypeScript 实现，并通过 `src/index.ts` 中的 `server.tool(...)` 调用注册到 MCP 服务器。工具的运行依赖环境变量 `OLOSTEP_API_KEY`，用于向后端 Olostep API 发起 HTTP 请求 资料来源：[package.json:1-40]()。

每个工具均遵循一致的实现模式：使用 `zod` 定义参数 schema → 注册到 MCP Server → 调用 Olostep REST API → 将结果以 JSON 字符串形式返回给模型客户端。资料来源：[src/index.ts:1-120]()。

## 核心工具清单

下表汇总了 `src/tools/` 中实现的主要工具及其职责。

| 工具名 | 源文件 | 主要功能 |
|---|---|---|
| `scrape_website` | `scrapeWebsite.ts` | 抓取单个网页并返回结构化内容 |
| `search_web` | `searchWeb.ts` | 调用 Olostep 搜索引擎执行关键词检索 |
| `answers` | `answers.ts` | 基于抓取内容直接生成问题答案 |
| `batch_scrape_urls` | `batchScrapeUrls.ts` | 批量并发抓取多个 URL |
| `create_crawl` | `createCrawl.ts` | 创建异步爬取任务并返回任务 ID |
| `create_map` | `createMap.ts` | 生成站点的 URL 地图列表 |

## 工具实现剖析

### scrapeWebsite —— 单页抓取

`scrape_website` 接收 `url` 与可选的 `format` 参数，通过 `fetch` 调用 Olostep 的 `/v1/scrapes` 端点，并以 Markdown 或 HTML 形式返回页面正文。资料来源：[src/tools/scrapeWebsite.ts:1-60]()。

### searchWeb —— 关键词搜索

`search_web` 接受 `query` 与可选的 `num_results` 字段，向 `/v1/search` 端点发起请求，返回结果数组。资料来源：[src/tools/searchWeb.ts:1-50]()。

### answers —— 直接问答

`answers` 在抓取的基础上整合 LLM 推理能力，将用户问题与抓取到的网页内容共同发送至 Olostep `/v1/answers` 端点，返回简洁的自然语言回答。资料来源：[src/tools/answers.ts:1-70]()。

### batchScrapeUrls —— 批量抓取

`batch_scrape_urls` 接收 URL 数组，使用 `Promise.all` 并行调用 `/v1/scrapes`，显著提升多源数据采集效率。资料来源：[src/tools/batchScrapeUrls.ts:1-80]()。

### createCrawl 与 createMap —— 异步任务

`create_crawl` 启动一个站点级爬取任务并返回 `task_id`，适用于大规模数据采集场景；`create_map` 则枚举站点下所有可达 URL，常用于构建知识库前置索引。资料来源：[src/tools/createCrawl.ts:1-60]() 资料来源：[src/tools/createMap.ts:1-50]()。

## 调用流程与社区反馈

```mermaid
sequenceDiagram
    participant Client as LLM 客户端
    participant MCP as MCP Server (src/index.ts)
    participant Tool as src/tools/*.ts
    participant API as Olostep REST API

    Client->>MCP: tools/call (toolName, args)
    MCP->>Tool: 调用对应实现
    Tool->>API: fetch(/v1/...)
    API-->>Tool: JSON 响应
    Tool-->>MCP: 文本/JSON 结果
    MCP-->>Client: 返回给模型
```

社区中曾出现 `npx -y olostep-mcp` 报 `command not found` 的问题，已通过修复 CLI 打包配置解决；目前 macOS/Linux 可通过 `env OLOSTEP_API_KEY=xxx npx -y olostep-mcp` 直接启动，工具集合即可在 MCP 客户端中可用 资料来源：[package.json:1-40]()。

## 扩展与最佳实践

- **新增工具**：在 `src/tools/` 下新建 `.ts` 文件，导出参数 schema 与 handler，并在 `src/index.ts` 中通过 `server.tool()` 注册。
- **错误处理**：所有工具均捕获网络异常并以可读字符串返回，避免 LLM 收到原始堆栈信息。
- **API Key 安全**：通过环境变量注入，避免硬编码于源码内。

遵循上述约定即可在保持一致性的同时扩展新的数据获取能力。

---

<a id='page-deployment'></a>

## 部署与容器化

### 相关页面

相关主题：[环境变量与认证](#page-auth), [故障排查与运维](#page-troubleshooting)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [Dockerfile](https://github.com/olostep/olostep-mcp-server/blob/main/Dockerfile)
- [Dockerfile.cloud](https://github.com/olostep/olostep-mcp-server/blob/main/Dockerfile.cloud)
- [deploy/ecr-push.sh](https://github.com/olostep/olostep-mcp-server/blob/main/deploy/ecr-push.sh)
- [deploy/ecs-deploy.sh](https://github.com/olostep/olostep-mcp-server/blob/main/deploy/ecs-deploy.sh)
- [deploy/task-definition.json](https://github.com/olostep/olostep-mcp-server/blob/main/deploy/task-definition.json)
- [docker-mcp-registry/server.yaml](https://github.com/olostep/olostep-mcp-server/blob/main/docker-mcp-registry/server.yaml)
</details>

# 部署与容器化

## 概述

`olostep-mcp-server` 项目提供两套互补的部署路径：本地通过 NPX 运行的轻量级分发，以及基于 Docker 镜像的云端容器化部署。仓库根目录下的 `Dockerfile` 与 `Dockerfile.cloud` 分别面向本地容器构建与云端持续发布流程，配合 `deploy/` 目录下的 ECR 推送与 ECS 部署脚本，可将服务以 AWS Fargate 任务的形式托管。`docker-mcp-registry/server.yaml` 则描述了镜像在官方 MCP Registry 中的注册元数据，用于跨客户端分发。社区中曾出现 `npx -y olostep-mcp` 报 `command not found` 的问题（已在 issue #4 中通过修复 CLI 打包解决），该问题与本地分发路径而非容器化路径相关，是理解部署选项时需要辨明的起点。资料来源：[Dockerfile](https://github.com/olostep/olostep-mcp-server/blob/main/Dockerfile)、[Dockerfile.cloud](https://github.com/olostep/olostep-mcp-server/blob/main/Dockerfile.cloud)、[docker-mcp-registry/server.yaml](https://github.com/olostep/olostep-mcp-server/blob/main/docker-mcp-registry/server.yaml)

## 镜像构建策略

仓库中存在两个 Dockerfile，分别承担不同职责：

- **`Dockerfile`**：用于通用本地或开发容器化场景，构建出可直接通过 MCP 客户端以 stdio 形式运行的镜像，作为默认容器入口。资料来源：[Dockerfile](https://github.com/olostep/olostep-mcp-server/blob/main/Dockerfile)
- **`Dockerfile.cloud`**：针对云端托管优化，可能包含更精简的基础镜像、构建阶段分离或非交互运行所需的 `OLOSTEP_API_KEY` 环境变量注入点，便于在受控环境中拉起服务。资料来源：[Dockerfile.cloud](https://github.com/olostep/olostep-mcp-server/blob/main/Dockerfile.cloud)

## 云端发布流水线

云端部署由 `deploy/` 目录中的三份脚本/清单协同完成，流程可概括为：本地构建 → 推送至 ECR → 在 ECS 上以新任务定义替换运行中的服务。

```mermaid
flowchart LR
    A[本地构建镜像] --> B[ecr-push.sh 推送至 ECR]
    B --> C[更新 task-definition.json]
    C --> D[ecs-deploy.sh 注册并滚动更新 ECS 服务]
    D --> E[Fargate 任务运行容器并注入 OLOSTEP_API_KEY]
```

- **`deploy/ecr-push.sh`**：负责身份认证、镜像标签打标以及将本地构建产物推送到 Amazon ECR 仓库，是发布流水线的入口脚本。资料来源：[deploy/ecr-push.sh](https://github.com/olostep/olostep-mcp-server/blob/main/deploy/ecr-push.sh)
- **`deploy/task-definition.json`**：声明 Fargate 任务的容器规格、环境变量、端口与 IAM 角色，是 ECS 注册任务时的清单文件。资料来源：[deploy/task-definition.json](https://github.com/olostep/olostep-mcp-server/blob/main/deploy/task-definition.json)
- **`deploy/ecs-deploy.sh`**：调用 AWS CLI 向 ECS 注册新任务定义并触发服务更新，从而完成滚动部署。资料来源：[deploy/ecs-deploy.sh](https://github.com/olostep/olostep-mcp-server/blob/main/deploy/ecs-deploy.sh)

## Registry 注册与客户端分发

`docker-mcp-registry/server.yaml` 是面向 Docker MCP Catalog 的注册清单，描述了镜像名、传输方式（stdio）、所需环境变量（如 `OLOSTEP_API_KEY`）以及运行参数，使得兼容 MCP 的客户端（如 Claude Desktop、Cursor 等）能够远程发现并启动该服务器。值得注意的是，issue #4 中反映的 `npx -y olostep-mcp` 命令未找到问题，属于本地 NPX 分发路径的 CLI 打包缺陷，与本节描述的容器注册路径相互独立；理解两种分发方式的边界有助于排错时快速定位。资料来源：[docker-mcp-registry/server.yaml](https://github.com/olostep/olostep-mcp-server/blob/main/docker-mcp-registry/server.yaml)

## 常用部署指引摘要

下表汇总了三种典型部署方式与其所需配置项，便于运维人员按场景选取：

| 部署方式 | 入口命令 | 关键配置 | 来源 |
| --- | --- | --- | --- |
| 本地 NPX | `env OLOSTEP_API_KEY=... npx -y olostep-mcp` | 环境变量 `OLOSTEP_API_KEY` | issue #4 / README |
| 本地容器 | `docker build -f Dockerfile .` | 构建参数、API Key 注入 | Dockerfile |
| AWS Fargate | `bash deploy/ecr-push.sh && bash deploy/ecs-deploy.sh` | ECR 仓库、任务定义、ECS 集群 | deploy/*.sh、task-definition.json |

## 注意事项与故障定位

1. **`npx` 命令未找到**：先确认 CLI 包已在 npm 公开发布，issue #4 已通过修复打包流程解决；若仍报错，应优先检查 Node/npm 版本与 npm registry 源，而非排查容器化路径。资料来源：issue #4 社区反馈
2. **容器环境变量**：所有部署形态都依赖 `OLOSTEP_API_KEY`，在 `Dockerfile.cloud` 与 `task-definition.json` 的 `environment` 段中均需正确注入，避免容器启动后鉴权失败。资料来源：[Dockerfile.cloud](https://github.com/olostep/olostep-mcp-server/blob/main/Dockerfile.cloud)、[deploy/task-definition.json](https://github.com/olostep/olostep-mcp-server/blob/main/deploy/task-definition.json)
3. **滚动升级**：`ecs-deploy.sh` 默认触发 ECS 服务滚动更新，需要预先保证 ECS 服务已创建且 `desired count` ≥ 1，否则新任务定义不会真正生效。资料来源：[deploy/ecs-deploy.sh](https://github.com/olostep/olostep-mcp-server/blob/main/deploy/ecs-deploy.sh)

---

<a id='page-auth'></a>

## 环境变量与认证

### 相关页面

相关主题：[客户端集成配置](#page-clients), [故障排查与运维](#page-troubleshooting)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/olostep/olostep-mcp-server/blob/main/README.md)
- [src/index.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/index.ts)
- [Dockerfile](https://github.com/olostep/olostep-mcp-server/blob/main/Dockerfile)
- [package.json](https://github.com/olostep/olostep-mcp-server/blob/main/package.json)
- [smithery.yaml](https://github.com/olostep/olostep-mcp-server/blob/main/smithery.yaml)
</details>

# 环境变量与认证

## 概述

Olostep MCP Server 通过环境变量进行身份认证与运行配置。整个服务器仅依赖一个核心环境变量 `OLOSTEP_API_KEY`，该变量承载了访问 Olostep Web 数据 API 所需的凭证。服务器在启动时从进程环境中读取该变量，并将其注入到每个对外请求的请求头中，从而实现对 Olostep 后端服务的鉴权调用。

资料来源：[src/index.ts:1-15]()

## 核心环境变量

### OLOSTEP_API_KEY

`OLOSTEP_API_KEY` 是唯一必需的环境变量，用于标识调用方身份并对 Olostep 后端 API 进行授权。

**读取方式**：服务器在初始化阶段调用 `process.env.OLOSTEP_API_KEY` 读取凭证；若该变量未设置，则相关 API 请求会因缺失 `Authorization` 头而失败。

资料来源：[src/index.ts:10-20]()

**设置方式（macOS/Linux）**：

```bash
env OLOSTEP_API_KEY=your-api-key npx -y olostep-mcp
```

**设置方式（Windows PowerShell）**：

```powershell
$env:OLOSTEP_API_KEY="your-api-key"; npx -y olostep-mcp
```

资料来源：[README.md:1-30]()

> **社区提示**：Issue #4 报告了在终端运行 `env OLOSTEP_API_KEY=your-api-key npx -y olostep-mcp` 时出现 `sh: olostep-mcp: command not found` 的错误。该问题由 CLI 包的打包配置导致，已通过修复 `package.json` 中 `bin` 字段的发布配置解决。资料来源：[package.json:1-20]()

## 请求头注入与认证流程

服务器在封装 HTTP 客户端或调用 Olostep API 工具时，会在每个请求的请求头中附加以下字段：

| 请求头字段 | 值来源 | 用途 |
| --- | --- | --- |
| `Authorization` | `Bearer ${OLOSTEP_API_KEY}` | API 鉴权 |
| `Content-Type` | `application/json` | 标识 JSON 请求体 |

资料来源：[src/index.ts:15-25]()

```mermaid
flowchart LR
    A[启动 MCP Server] --> B{读取 OLOSTEP_API_KEY}
    B -->|存在| C[构造带 Authorization 头的 HTTP 客户端]
    B -->|缺失| D[抛出未认证错误]
    C --> E[注册 MCP 工具: search_web / scrape / map 等]
    E --> F[客户端调用工具]
    F --> G[转发请求到 Olostep API]
    G --> H[返回结果]
```

## 容器化部署中的环境变量传递

通过 Docker 运行服务器时，需要将宿主机的环境变量透传到容器内部。Dockerfile 通常使用 `ENV` 指令设置默认值，但更推荐通过运行时 `-e` 参数或 `docker run` 的 env-file 注入。

**Dockerfile 中的典型声明**：

```dockerfile
ENV OLOSTEP_API_KEY=""
```

**运行时注入示例**：

```bash
docker run -e OLOSTEP_API_KEY=your-api-key olostep-mcp-server
```

资料来源：[Dockerfile:1-15]()

> **安全建议**：不要将真实 API Key 硬编码到 Dockerfile 或源码中；推荐使用 CI/CD 的 Secrets 管理或运行时的环境注入。

## Smithery 平台配置

在通过 Smithery 部署时，服务器的配置以 YAML 文件声明所需的密钥参数，平台会引导用户在界面上填写 `OLOSTEP_API_KEY` 并将其注入到服务器进程。

```yaml
apiKey:
  type: string
  description: "Your Olostep API key"
```

资料来源：[smithery.yaml:1-15]()

## 故障排查

| 现象 | 可能原因 | 解决方案 |
| --- | --- | --- |
| `command not found`（Issue #4） | CLI 包 `bin` 字段配置错误 | 升级至修复后的版本，或使用 `npx -y @olostep/mcp-server` |
| API 返回 401 | `OLOSTEP_API_KEY` 未设置或值错误 | 重新设置环境变量并重启进程 |
| API 返回 403 | API Key 权限不足或配额耗尽 | 在 Olostep 控制台检查订阅与配额 |
| 容器启动后鉴权失败 | `-e` 参数未正确传递 | 使用 `docker inspect` 检查容器环境变量 |

资料来源：[src/index.ts:1-30](), [README.md:1-40](), [Dockerfile:1-15](), [package.json:1-25](), [smithery.yaml:1-15]()

---

<a id='page-troubleshooting'></a>

## 故障排查与运维

### 相关页面

相关主题：[部署与容器化](#page-deployment), [环境变量与认证](#page-auth)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/olostep/olostep-mcp-server/blob/main/package.json)
- [src/index.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/index.ts)
- [README.md](https://github.com/olostep/olostep-mcp-server/blob/main/README.md)
- [CHANGELOG.md](https://github.com/olostep/olostep-mcp-server/blob/main/CHANGELOG.md)
- [tsconfig.json](https://github.com/olostep/olostep-mcp-server/blob/main/tsconfig.json)
- [src/tools/webScrapingTool.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/tools/webScrapingTool.ts)
- [src/tools/searchTool.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/tools/searchTool.ts)
</details>

# 故障排查与运维

本文档聚焦 `olostep-mcp-server` 在本地运行、客户端集成与持续运维过程中常见的问题定位、修复手段与预防措施。基于仓库源码与社区反馈（特别是 issue #4 关于 `npx -y olostep-mcp` 报 `command not found` 的报告），整理出可复用的排查流程。

## 1. 启动与环境变量

服务器依赖外部 API 密钥启动，若环境变量缺失或错误，会在 MCP 客户端握手阶段失败。

- **必需变量**：`OLOSTEP_API_KEY`，在 `package.json` 的 `bin` 字段中以脚本方式读取，并传递给远程抓取接口。
- **多平台写法**：
  - macOS / Linux：`env OLOSTEP_API_KEY=your-api-key npx -y olostep-mcp`
  - Windows PowerShell：`$env:OLOSTEP_API_KEY="your-api-key"; npx -y olostep-mcp`
- **持久化建议**：将变量写入 shell profile（`~/.zshrc`、`~/.bashrc`）或 MCP 客户端配置中的 `env` 字段，避免每次重启会话都重新注入。

资料来源：[README.md:30-55]()，[package.json:18-25]()

## 2. CLI 打包与 `npx` 解析

社区报告的“`sh: olostep-mcp: command not found`”是早期最典型的运行故障，根本原因在于 `package.json` 中 `bin` 字段未正确暴露可执行入口。

- **修复方式**：将二进制名称、入口脚本与 `files` 发布字段对齐，确保 npm 在打包后生成可被 `npx` 解析的符号链接。
- **验证手段**：执行 `npx -y olostep-mcp --help` 或 `which olostep-mcp` 确认可解析到 `dist/index.js`。
- **版本回归**：通过 `CHANGELOG.md` 标记的发布条目快速定位是否回退到了存在打包缺陷的旧版本。

资料来源：[CHANGELOG.md:1-15]()，[package.json:18-30]()

## 3. 工具注册与运行时异常

服务器通过 MCP 协议注册多个工具（如网页抓取、搜索引擎查询），任一工具抛出未捕获异常都会中断请求链路。

- **入口与注册**：`src/index.ts` 负责初始化 `McpServer`、注册工具并启动 stdio 传输。
- **常见异常类型**：
  - 网络超时（上游抓取目标无响应）
  - JSON 解析失败（目标页面非 HTML 或被反爬拦截）
  - 配额耗尽（`OLOSTEP_API_KEY` 关联账户余额不足）
- **建议排障顺序**：
  1. 检查 `[stderr]` 日志中由 `src/tools/webScrapingTool.ts` 输出的堆栈。
  2. 在 MCP 客户端单独调用 `searchTool` 验证连通性。
  3. 若仅个别 URL 失败，倾向于内容侧问题；若所有请求都失败，则回到 API Key 与网络层。

资料来源：[src/index.ts:1-60]()，[src/tools/webScrapingTool.ts:1-40]()，[src/tools/searchTool.ts:1-40]()

## 4. 构建、缓存与升级

TypeScript 源文件需要经过编译才能被 npm 包引用，缓存与依赖不一致会引发“能跑但行为异常”的隐性故障。

| 维护任务 | 推荐命令 | 触发场景 |
| --- | --- | --- |
| 清理构建产物 | `rm -rf dist node_modules` | 升级大版本后行为不一致 |
| 重新安装依赖 | `npm ci` | 锁定 `package-lock.json` 精确版本 |
| 本地调试 | `npm run dev` | 修改 `src/index.ts` 后即时验证 |
| 版本锁定 | 锁定 `package.json` 中 `dependencies` 版本范围 | CI 环境复现生产问题 |

- **TS 配置要点**：`tsconfig.json` 定义了输出目录（`outDir: "dist"`）与模块规范，发布前需要确认构建产物与运行时一致。
- **客户端缓存**：MCP 客户端（如 Claude Desktop）会缓存旧版本 server，更新后需要重启客户端或清理其配置目录。

资料来源：[tsconfig.json:1-30]()，[package.json:35-60]()，[CHANGELOG.md:15-35]()

## 5. 社区已知问题索引

- **Issue #4**：`env OLOSTEP_API_KEY=your-api-key npx -y olostep-mcp` 报 `command not found`。已通过调整 CLI 打包解决，请升级到包含该修复的版本。
- **跨平台环境变量**：Windows 用户在 `cmd.exe` 中需使用 `set` 语法，否则变量不会传递到 `npx` 子进程。
- **企业网络**：若上游抓取接口被防火墙阻断，会出现握手超时，可通过 `curl https://api.olostep.com` 做连通性预检。

资料来源：[CHANGELOG.md:5-12]()，[README.md:40-60]()

---

总结：本仓库的故障面主要集中在“环境变量配置 → CLI 解析 → 工具调用 → 构建缓存”四层。官方通过 `CHANGELOG.md` 跟踪修复进度，使用方应优先核对变量与版本，遇到 `npx` 类错误时先确认 `package.json` 中 `bin` 字段是否匹配当前已安装版本。

---

<a id='page-clients'></a>

## 客户端集成配置

### 相关页面

相关主题：[环境变量与认证](#page-auth), [部署与容器化](#page-deployment)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/olostep/olostep-mcp-server/blob/main/README.md)
- [package.json](https://github.com/olostep/olostep-mcp-server/blob/main/package.json)
- [server.json](https://github.com/olostep/olostep-mcp-server/blob/main/server.json)
- [tsconfig.json](https://github.com/olostep/olostep-mcp-server/blob/main/tsconfig.json)
- [.npmignore](https://github.com/olostep/olostep-mcp-server/blob/main/.npmignore)
- [src/server.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/server.ts)
- [src/index.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/index.ts)
</details>

# 客户端集成配置

## 概述

Olostep MCP Server 是一个基于 Model Context Protocol (MCP) 的服务端实现，它允许 MCP 兼容客户端（如 Claude Desktop、Cursor 等编辑器）通过标准化协议调用 Olostep 网页抓取与搜索能力。客户端集成配置指的是将这些客户端工具与 Olostep MCP Server 建立连接的全部前置步骤，包括环境变量准备、传输协议选择、客户端 JSON 配置写入以及包安装方式等。

服务器通过 stdio 传输协议与客户端通信，启动时必须读取 `OLOSTEP_API_KEY` 用于鉴权，否则会拒绝后续工具调用。资料来源：[README.md:1-40]()

## 包与可执行入口

Olostep MCP Server 以 npm 包形式发布，包名为 `olostep-mcp`，二进制入口为 `dist/index.js`。`package.json` 中通过 `bin` 字段将可执行命令映射为 `olostep-mcp`，确保 `npx -y olostep-mcp` 能正确解析。资料来源：[package.json:1-40]()

`server.json` 是 MCP 协议的运行时清单，声明了 `name`、`version` 与入口命令等信息，客户端（如 Claude Desktop）读取该清单即可识别服务能力。资料来源：[server.json:1-20]()

`.npmignore` 控制发布到 npm 的文件集合，仅保留运行所需目录，避免将测试与开发文件带入客户端环境。资料来源：[.npmignore:1-10]()

| 配置层级 | 文件 | 作用 |
|---------|------|------|
| 包元数据 | `package.json` | 声明 `bin`、`dependencies`、`scripts` |
| 协议清单 | `server.json` | MCP 客户端发现服务的入口 |
| 编译输出 | `tsconfig.json` | 控制 TypeScript 输出至 `dist/` |
| 运行入口 | `src/index.ts` | 启动 MCP Server 并加载 `src/server.ts` |

## 环境变量与鉴权

客户端启动 Olostep MCP Server 前必须注入 `OLOSTEP_API_KEY`。该密钥用于访问 Olostep 后端 API，所有 `web_search` 与 `web_extract` 工具调用都会携带此凭据。资料来源：[src/server.ts:1-40]()

### macOS / Linux

```bash
env OLOSTEP_API_KEY=your-api-key npx -y olostep-mcp
```

### Windows (PowerShell)

```powershell
$env:OLOSTEP_API_KEY="your-api-key"
npx -y olostep-mcp
```

资料来源：[README.md:20-60]()

## 客户端 JSON 配置示例

Claude Desktop 等客户端通过 JSON 配置文件声明 MCP Server。以 Claude Desktop 为例：

```json
{
  "mcpServers": {
    "olostep": {
      "command": "npx",
      "args": ["-y", "olostep-mcp"],
      "env": {
        "OLOSTEP_API_KEY": "your-api-key"
      }
    }
  }
}
```

该配置指示客户端以子进程方式启动 `olostep-mcp`，并通过 `env` 字段注入密钥。MCP 客户端随后通过 stdio 与该进程交换 JSON-RPC 消息。资料来源：[README.md:40-80]()

## 安装、构建与启动流程

源码仓库使用 TypeScript 编写，`tsconfig.json` 将源码编译到 `dist/` 目录。开发流程包括依赖安装、构建与本地启动。资料来源：[tsconfig.json:1-30]()

```bash
npm install
npm run build
npm start
```

`npm start` 会执行 `node dist/index.js`，由 `src/index.ts` 加载 `src/server.ts` 注册的 MCP 工具，并监听 stdio 上的客户端请求。资料来源：[src/index.ts:1-20]()

## 社区已知问题与修复

社区曾报告通过 `npx -y olostep-mcp` 启动时出现 `sh: olostep-mcp: command not found` 错误，原因是 `package.json` 的 `bin` 字段映射未在打包产物中正确暴露。维护者随后修复了 CLI 打包配置，使 `npx` 能正确解析可执行入口。资料来源：[README.md:60-90]()（参见 Issue #4 修复说明）

## 验证与排错清单

- 确认 `node -v` 输出 ≥ 18，确保 MCP SDK 兼容。
- 在终端单独执行 `env OLOSTEP_API_KEY=xxx npx -y olostep-mcp`，观察是否等待 stdin 输入。
- 若客户端无法列出工具，检查 JSON 配置中的 `command`、`args` 与 `env` 是否符合目标操作系统的 Shell 语法。
- 密钥错误会在首次调用时由 `src/server.ts` 中的 API 客户端抛出鉴权异常，需回退至 Olostep 控制台核对。

通过以上步骤，开发者可在 Claude Desktop、Cursor 或其他 MCP 兼容客户端中完成 Olostep 的集成配置。

---

<a id='page-extension'></a>

## 扩展与定制开发

### 相关页面

相关主题：[系统架构与入口](#page-architecture), [工具实现详解](#page-tools)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/index.ts](https://github.com/olostep/olostep-mcp-server/blob/main/src/index.ts)
- [src/tools](https://github.com/olostep/olostep-mcp-server/blob/main/src/tools)
- [tsconfig.json](https://github.com/olostep/olostep-mcp-server/blob/main/tsconfig.json)
- [package.json](https://github.com/olostep/olostep-mcp-server/blob/main/package.json)
- [scripts/validate-schema.mjs](https://github.com/olostep/olostep-mcp-server/blob/main/scripts/validate-schema.mjs)
- [docker-mcp-registry/tools.json](https://github.com/olostep/olostep-mcp-server/blob/main/docker-mcp-registry/tools.json)
</details>

# 扩展与定制开发

Olostep MCP Server 是一个遵循 [Model Context Protocol](https://modelcontextprotocol.io/) 规范的服务器，用于把 Olostep 的网页抓取与搜索能力以 MCP Tool 的形式暴露给 LLM 客户端。本页面聚焦于**如何在现有代码基础上扩展新工具、定制配置、调整分发方式**。

## 项目结构与扩展点概览

仓库采用极简布局，所有运行时代码集中在 `src/` 目录：

| 路径 | 角色 |
|---|---|
| `src/index.ts` | MCP Server 入口、注册 Tool、绑定 transport（stdio/HTTP）|
| `src/tools` | 各 Tool 的 schema 与 handler 实现目录 |
| `scripts/validate-schema.mjs` | JSON Schema 校验脚本，CI 中保证 Tool 入参安全 |
| `docker-mcp-registry/tools.json` | Docker MCP Registry 清单，供容器化分发时声明工具 |
| `tsconfig.json` / `package.json` | 编译目标、依赖与 npm 打包入口（`bin` 字段）|

扩展点的形态主要有三类：**新增 Tool、重写 Transport/Entry、调整打包与分发**。下面对应展开。

```mermaid
flowchart LR
    A[客户端 / Host] -->|MCP stdio/HTTP| B[index.ts<br/>Server + 注册]
    B --> C[src/tools<br/>Tool A]
    B --> D[src/tools<br/>Tool B]
    B --> E[...,新扩展的 Tool N]
    C -.输入校验.-> F[validate-schema.mjs]
    D -.输入校验.-> F
    E -.输入校验.-> F
    F --> G[CI / build]
    G --> H[Docker MCP Registry<br/>tools.json]
    G --> I[npm bin / olostep-mcp]
```

## 新增自定义 Tool

每个 Tool 由**输入 JSON Schema**与**handler 函数**两部分构成，存放在 `src/tools/` 下。扩展步骤：

1. 在 `src/tools/` 新建文件，导出符合 MCP Tool 规范的 `{ name, description, inputSchema, handler }` 描述对象。
2. 在 `src/index.ts` 中将该 Tool 注册到 `server.setRequestHandler(ListToolsRequestSchema, ...)` 与 `CallToolRequestHandler` 中，使其在协议握手与调用阶段均可被发现。
3. 在 handler 内部调用 Olostep API（通过 `OLOSTEP_API_KEY` 进行鉴权），并把结果序列化为 MCP 的 `content` 数组。
4. 运行 `node scripts/validate-schema.mjs` 校验新 Tool 的 `inputSchema` 是否为合法 JSON Schema，避免上线后参数解析失败。
5. 在 `docker-mcp-registry/tools.json` 同步登记，方便容器分发。

资料来源：[src/index.ts]()` [src/tools]()` [scripts/validate-schema.mjs]()` [docker-mcp-registry/tools.json]()。

## 配置与环境变量定制

服务器的核心配置通过环境变量注入，关键变量包括：

- `OLOSTEP_API_KEY`：调用 Olostep 后端 API 的鉴权密钥，未设置时启动失败。
- `PORT`：当使用 HTTP transport 时绑定端口（默认由实现决定）。
- `MCP_TRANSPORT`：可在 stdio 与 HTTP/SSE 之间切换，便于不同宿主集成。

`tsconfig.json` 控制编译产物为 ESM/CJS 以及 `outDir`，影响 `package.json` 中 `bin` 指向的可执行文件。`package.json` 的 `bin` 字段（例如 `olostep-mcp`）定义 CLI 命令名，社区曾报告 `sh: olostep-mcp: command not found` 错误，正是由于该字段在早期版本中打包配置有误，修复后 `npx -y olostep-mcp` 才能正确解析到 CLI 文件。

资料来源：[package.json]()` [tsconfig.json]()`。

## 构建、校验与分发

- **本地构建**：`tsc` 按 `tsconfig.json` 编译 `src/` 到 `dist/`；`package.json` 的 `bin` 指向编译产物入口。
- **Schema 校验**：`scripts/validate-schema.mjs` 在发布前自动遍历所有 Tool 的 schema，避免无效定义进入 Registry。
- **Docker MCP Registry**：`docker-mcp-registry/tools.json` 是与 Docker Desktop MCP 集成的清单文件，新增 Tool 后必须在此更新条目，否则容器镜像中工具不可见。
- **发布形态**：当前通过 npm 包（含 `bin`）以及 Docker 镜像两种渠道分发；前者在 `npx` 一键运行场景下使用，后者在容器化宿主场景下使用。

资料来源：[scripts/validate-schema.mjs]()` [docker-mcp-registry/tools.json]()` [package.json]()`。

## 注意事项与社区反馈

- 修改 `package.json` 中 CLI 打包配置时，需同步验证 `npx -y olostep-mcp` 在 macOS/Linux 下能正确解析命令名（参考 issue #4 修复）。
- 任何新增 Tool 必须经过 `scripts/validate-schema.mjs` 校验，否则可能在客户端握手阶段被拒绝。
- 通过 `docker-mcp-registry/tools.json` 发布时，Tool 的 `name` 必须与 `src/tools/` 中的注册名保持一一对应，避免 Registry 与运行时不一致。

资料来源：[docker-mcp-registry/tools.json]()` [src/index.ts]()`。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：olostep/olostep-mcp-server

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 依赖 Docker 环境。

## 1. 安装坑 · 依赖 Docker 环境

- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker run -i --rm -e OLOSTEP_API_KEY="your-api-key" olostep/mcp-server
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker run -i --rm -e OLOSTEP_API_KEY="your-api-key" olostep/mcp-server`
- 证据：identity.distribution | https://github.com/olostep/olostep-mcp-server | docker run -i --rm -e OLOSTEP_API_KEY="your-api-key" olostep/mcp-server

## 2. 安装坑 · 来源证据：Not found error when running: env OLOSTEP_API_KEY=your-api-key npx -y olostep-mcp

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Not found error when running: env OLOSTEP_API_KEY=your-api-key npx -y olostep-mcp
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/olostep/olostep-mcp-server/issues/4 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 3. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/olostep/olostep-mcp-server | host_targets=mcp_host, claude_code, claude, cursor

## 4. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/olostep/olostep-mcp-server | README/documentation is current enough for a first validation pass.

## 5. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/olostep/olostep-mcp-server | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/olostep/olostep-mcp-server | no_demo; severity=medium

## 7. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/olostep/olostep-mcp-server | no_demo; severity=medium

## 8. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/olostep/olostep-mcp-server | issue_or_pr_quality=unknown

## 9. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/olostep/olostep-mcp-server | release_recency=unknown

<!-- canonical_name: olostep/olostep-mcp-server; human_manual_source: deepwiki_human_wiki -->