olostep-mcp-server 是一个基于 Model Context Protocol（MCP） 的服务端实现，用于将 Olostep 提供的网页抓取与数据提取能力暴露给兼容 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。

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。

总体架构

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

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。在该文件中，McpServer 被实例化，并通过官方 @modelcontextprotocol/sdk 提供的 StdioServerTransport 与客户端通信，从而实现无网络端口、常驻进程的本地集成。

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

1. 构造 McpServer 并设置 server 名与版本号，对应 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 通常会开启 "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 遵循 MCP 官方注册表的 schema，用于让 MCP 注册表与目录服务发现该服务器。它一般包含：

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

资料来源：server.json:1-80

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

服务器通过环境变量获取凭据，主要变量为 OLOSTEP_API_KEY，由 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 故障排查思路。

概述

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/ 中实现的主要工具及其职责。

工具实现剖析

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。

调用流程与社区反馈

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 安全：通过环境变量注入，避免硬编码于源码内。

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

概述

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、Dockerfile.cloud、docker-mcp-registry/server.yaml

镜像构建策略

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

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

云端发布流水线

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

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
• deploy/task-definition.json：声明 Fargate 任务的容器规格、环境变量、端口与 IAM 角色，是 ECS 注册任务时的清单文件。资料来源：deploy/task-definition.json
• deploy/ecs-deploy.sh：调用 AWS CLI 向 ECS 注册新任务定义并触发服务更新，从而完成滚动部署。资料来源：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

常用部署指引摘要

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

注意事项与故障定位

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

概述

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）：

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

设置方式（Windows 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 工具时，会在每个请求的请求头中附加以下字段：

资料来源：src/index.ts:15-25

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 中的典型声明：

ENV OLOSTEP_API_KEY=""

运行时注入示例：

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 并将其注入到服务器进程。

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

资料来源：smithery.yaml:1-15

故障排查

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

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 包引用，缓存与依赖不一致会引发“能跑但行为异常”的隐性故障。

• 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

概述

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

环境变量与鉴权

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

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

资料来源：README.md:20-60

客户端 JSON 配置示例

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

{
  "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

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 的集成配置。

项目结构与扩展点概览

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

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

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。

Pitfall Log / 踩坑日志

项目：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