# @devops-infinity/ownserp 中文文档

规范地址：https://npmcn.com/package/%40devops-infinity/ownserp/

版本：2\.4\.0
npm 元数据更新时间：2026-10-30T13:41:32.222Z
中文译文更新时间：2026-11-12T03:51:07.309Z
软件包许可：MIT OR Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40devops-infinity/ownserp
原文对照：https://npmcn.com/package/%40devops-infinity/ownserp/?lang=original
项目主页：https://github.com/devops-infinity/ownserp
源码仓库：https://github.com/devops-infinity/ownserp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：87 kB，10 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=14\.14
- 运行依赖：1 个
- 首次发布：2026-10-24T10:05:50.556Z
- 最新版本发布：2026-10-30T13:41:32.072Z
- 近 30 天下载量：4095（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

OwnSERP,用于Serper.dev搜索 API 的 MCP 服务器,超过 stdio和可流的 HTTP

## 安装

```sh
npm install @devops-infinity/ownserp
```

也可以使用：`pnpm add @devops-infinity/ownserp`、`yarn add @devops-infinity/ownserp`、`bun add @devops-infinity/ownserp`

## README

# 拥有服务器

Serper.dev搜索 API 的 MCP 服务器,可进行每个呼叫的信用核算.

## 状态

稳定在2.0。 当地所有船闸通通后 每一艘被标记的船就释放 语义版承诺涵盖命令行,剖面图计划,分类账格式,以及工具结果形状. (原始内容存档于2018-07-21) (英语). Rust API of the Rust API of the `ownserp-core` 箱子没有被覆盖,所以小的放出可能会重新命名那里的公用物品. 从1.0开始,指令表面,配置方案,分类账格式,工具结果形状都遵循语义化的版本:对其中任何一个的突破性修改需要一个主要版本,新工具,旗帜,或设置需要一个小版本,而固定则需要一个补丁. `CHANGELOG.md` 记录每个变化.

## 目录

-   [概览](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-overview)
-   [所需资源](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-requirements)
-   [安装](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-installation)
-   [升级](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-upgrading)
-   [快开始](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-quick-start)
-   [连接客户端](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-connect-a-client)
-   [API 密钥](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-api-key)
-   [工具](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-tools)
-   [反应形状和外地预设](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-response-shape-and-field-presets)
-   [示例](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-example)
-   [成本核算和分类账](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-cost-accounting-and-the-ledger)
-   [配置](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-configuration)
-   [HTTP 部署](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-http-deployment)
-   [警卫](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-security)
-   [解决问题](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-troubleshooting)
-   [发展](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-development)
-   [分发](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-distribution)
-   [支助](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-support)
-   [捐款](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-contributing)
-   [许可证](https://npmcn.com/package/%40devops-infinity/ownserp/#readme-license)

## 概览

OwnSERP将Serper.dev搜索端点曝光为MCP(模式上下文协议)工具. 一个模型可以搜索网络,图像,新闻,地点,地图,视频,购物,学者,专利,评论,和镜头,取出一页,解决一个位置名称,并读取自己的花销,全部通过一个本地服务器.

它是为使用计量吸入器的代理人建造的。 每个工具描述都说明其价格,每个结果都包含一个成本对象,一个本地分类账记录每个调用. 在呼叫花费任何东西之前,服务器可以检查每个呼叫的天花板和会话预算,并在两者都会被通过时拒绝呼叫. 两人都离开,直到你让他们,通过 `per_call_credit_ceiling` 财务报告和审定财务报表 `session_budget_credits` 在剖面图中,或 `OWN_SERPER_PER_CALL_CREDIT_CEILING` 财务报告和审定财务报表 `OWN_SERPER_SESSION_BUDGET_CREDITS` 在环境中。 结果为模型所塑造,而不是为浏览器所塑造:隐形字符被剥去,长文本被封上并被标记,缺失字段被省略,并固定了密钥顺序.

服务器是一个二进制,不需要语言运行时间. 它会说MCP修订2026-07-28,并在2025-11-25上回答客户端. 它默认运行于stdio上,或带有无记名标志门的超流式HTTP上.

## 所需资源

-   要运行一个已发布的二进制: 没有运行时间, 没有工具链 。 预建的二进制覆盖了macOS,Linux,和Windows.
-   从源头建造:1.89拉斯特或更新,被钉入1.99.1英寸 `rust-toolchain.toml`。 。 。 .
-   Serper.dev 账户和 API 密钥来自 [https://serper.dev/api-keys (英语)](https://serper.dev/api-keys)。 。 。 .
-   一个在 stdio 上说出 MCP 的客户端,或者任何用于 Streamable HTTP 传输的 HTTP 客户端.

## 安装

每个安装路径都使用预建的二进制:没有Rust工具链和编译步骤.

发布档案涵盖macOS ARM64和x86 64,Linux x86 64有glibc,Linux ARM64有glibc,Linux x86 64和ARM64有静态musl,和Windows x86 64.

### 无

```sh
npx @devops-infinity/ownserp serve
```

包在安装时下载当前平台的存档,对照放出检查和进行检查,并运行二进制. 节点22或更新.

### 土生土长

```sh
brew install devops-infinity/tap/ownserp
```

macOS和Linux都安装了发行二进制. 水龙头在每次放出后都会由手进行更新,这样就可以将放出的时间拖后几分钟.

### Shell 安装器

```sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/devops-infinity/ownserp/releases/latest/download/ownserp-installer.sh | sh
```

在 Windows 上, 在 PowerShell 中:

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/devops-infinity/ownserp/releases/latest/download/ownserp-installer.ps1 | iex"
```

### 释放归档

```sh
VERSION=2.4.0
BASE="https://github.com/devops-infinity/ownserp/releases/download/v$VERSION"
TARGET=x86_64-unknown-linux-gnu
curl -LO "$BASE/ownserp-$TARGET.tar.gz"
curl -LO "$BASE/ownserp-$TARGET.tar.gz.sha256"
sha256sum -c "ownserp-$TARGET.tar.gz.sha256"
tar -xzf "ownserp-$TARGET.tar.gz"
install -m 0755 "ownserp-$TARGET/ownserp" ~/.local/bin/ownserp
```

设定 `TARGET` 改为 `aarch64-apple-darwin` 或者说 `x86_64-apple-darwin` 在macOS上, `aarch64-unknown-linux-gnu` 或者说 `x86_64-unknown-linux-musl` 或者说 `aarch64-unknown-linux-musl` 在平台上使用 `.zip` 文件为 `x86_64-pc-windows-msvc` 在视窗上.

二进制打印其外壳补全和手动页面 `ownserp completions <shell>` 财务报告和审定财务报表 `ownserp man`安装到您的外壳和手动读取器所查看的地方 `~/.local/share/bash-completion/completions/`,打开目录 `fpath`, (中文(简体) ), `~/.config/fish/completions/`,以及 `~/.local/share/man/man1/`。 。 。 .

当 `MINISIGN_KEY` 配置了仓库密钥, 每个发布标志 `sha256.sum` 带着迷你标志 要检查下载, 对照此寄存器中的公钥验证签名, 然后对照文件检查归档 :

```sh
minisign -Vm sha256.sum -P RWSPyQWAsXwP5vjgAFI/PAAtbFAd5tA4BlhyFrT+MCPNmE2J+jgT26kC
grep "ownserp-x86_64-unknown-linux-gnu.tar.gz" sha256.sum | sha256sum --check
```

### 集装箱

```sh
docker run --rm -p 127.0.0.1:8777:8777 \
  -e SERPER_API_KEY -e OWN_SERPER_BEARER_TOKENS \
  -e OWN_SERPER_ALLOWED_HOSTS=127.0.0.1,localhost \
  ghcr.io/devops-infinity/ownserp:latest
```

该图像服务于可流的HTTP并拒绝没有无记名符号的公共绑定,因此需要两个变量. `OWN_SERPER_ALLOWED_HOSTS` 必须命名每个 主机客户端发送, 因为图像绑定 `0.0.0.0` 和来自该地址的许可列表不匹配真实的主机;将公共主机名,或代理机发送的名称添加到同一列表中. 包裹是公开的,所以 `docker pull` 不需要登录.

### 窗口

使用上面的 PowerShell 安装器, 或者下载 `ownserp-x86_64-pc-windows-msvc.zip` 从发布页面中提取 `ownserp.exe`,将文件夹放入您的路径。 无法解析名称的客户端配置使用绝对路径 `ownserp.exe`。 。 。 .

### MCPB 捆绑

捆绑只携带了Linux x86 64 二进制. 在另一个架构上,安装该平台的存档.

下载 `ownserp-<version>.mcpb` 从发布页面中打开,然后在一个支持MCP Bundles的客户端中打开. 捆绑要API密钥并存储在OS密钥链中.

## 升级

`ownserp update` 请求 GitHub 提供最新的发布并打印符合此安装的命令 : `brew upgrade ownserp`, (中文(简体) ), `cargo install --locked ownserp`,npm全局安装,或容器拉出. 它只检查和报告,所以升级 贯穿你安装的频道 和该频道自己的签名和审查 保持有效. `ownserp update --json` 给 `current`, (中文(简体) ), `latest`, (中文(简体) ), `updateAvailable`,以及 `command` 用于脚本。 支票打来 `api.github.com` 服务器本身仍然没有发出遥测信号.

## 快开始

```sh
export SERPER_API_KEY="your key"
npx @devops-infinity/ownserp doctor
npx @devops-infinity/ownserp serve
```

第一个命令为外壳设置了密钥. 第二个打印解析设置,密钥源与密钥被遮盖,以及两个Serper主机的答案. 第三种在stdio上启动服务器,这是命令一个MCP客户端启动,因此它一直运行到客户端停止.

要连接客户端,请添加下一节显示的服务器.

## 连接客户端

每个客户端运行 `ownserp serve` 以stdio过程和通过 `SERPER_API_KEY` 在环境中。 当桌面客户端无法解析时 `ownserp` 的绝对路径 `command -v ownserp`。 。 。 .

### 克劳德代码

```sh
claude mcp add --scope project ownserp -- ownserp serve
```

或犯下 `.mcp.json` 项目根 :

```json
{
  "mcpServers": {
    "ownserp": {
      "command": "ownserp",
      "args": ["serve"]
    }
  }
}
```

### 克劳德桌面

将此添加到 `claude_desktop_config.json`时 `~/Library/Application Support/Claude/` 在macOS上或 `%APPDATA%\Claude\` 在视窗上。 使用安装二进制的绝对路径, 因为桌面应用程序不会继承 shell PATH :

```json
{
  "mcpServers": {
    "ownserp": {
      "command": "/absolute/path/to/ownserp",
      "args": ["serve"],
      "env": { "SERPER_API_KEY": "your key" }
    }
  }
}
```

Npm 包为当前平台安装了预建的二进制. 点 `command` 时间 `ownserp` 当客户端继承您的 PATH, 或者在绝对路径 `command -v ownserp` 当它没有.

### OpenAI 代码 CLI

单位 `~/.codex/config.toml`,或项目 `.codex/config.toml`数字 :

```toml
[mcp_servers.ownserp]
command = "ownserp"
args = ["serve"]
env_vars = ["SERPER_API_KEY"]
```

`env_vars` 从环境中通过变量,所以密钥永远不会进入命令行.

### 命令代码

```sh
commandcode mcp add-json --scope project ownserp '{"type":"stdio","command":"ownserp","args":["serve"]}'
```

### 光标

单位 `~/.cursor/mcp.json`,或 `.cursor/mcp.json` 用于一个项目:

```json
{
  "mcpServers": {
    "ownserp": {
      "command": "ownserp",
      "args": ["serve"],
      "env": { "SERPER_API_KEY": "your key" }
    }
  }
}
```

### 风起浪起 (卡斯卡德)

单位 `~/.config/devin/mcp_config.json` 在 Linux 和 macOS 上,或 `%APPDATA%\devin\mcp_config.json` 在视窗上 :

```json
{
  "mcpServers": {
    "ownserp": {
      "command": "ownserp",
      "args": ["serve"],
      "env": { "SERPER_API_KEY": "your key" }
    }
  }
}
```

### VS 代码

运行 `MCP: Add Server` 从命令调色板,或添加 `.vscode/mcp.json` 到工作区 :

```json
{
  "servers": {
    "ownserp": {
      "type": "stdio",
      "command": "ownserp",
      "args": ["serve"],
      "env": { "SERPER_API_KEY": "your key" }
    }
  }
}
```

### 齐德

单位 `settings.json`数字 :

```json
{
  "context_servers": {
    "ownserp": {
      "command": "ownserp",
      "args": ["serve"],
      "env": { "SERPER_API_KEY": "your key" }
    }
  }
}
```

### 其他MCP客户

使用带有命令的 stdio `ownserp` 和论点 `serve`设置 `SERPER_API_KEY` 在客户环境块或外壳中,客户继承.

## API 密钥

三个源起作用,过程环境胜过键链.

-   环境变量,在 shell 或客户端的内嵌块中:

```sh
export SERPER_API_KEY="your key"
```

-   OS 键链, 从 stdin 读取, 这样密钥不会输入 shell 历史 :

```sh
printf '%s' "$SERPER_API_KEY" | ownserp config set-api-key
```

-   客户端 JSON 配置(Client JSON config),客户端在其中注入它所持有的封口.

密钥从未从命令行参数读取,从未被写入配置文件,也从未被打印出外壳. 在 Linux 上, 键链商店是特勤局, 所以桌面会话总线必须运行; 在无头服务器上, 设置 `SERPER_API_KEY` 换句话说 每个项目或代理人使用一个命名的密钥 [https://serper.dev/api-keys (英语)](https://serper.dev/api-keys),因为一个密钥不能被限定为较小的支出.

## 工具

工具列表中的每个工具描述都写出价格,因此一个模型可以在支出前编制预算.

-   `serper_search`,1功劳. 网络结果有知识图表,答题框,以及相关的搜索.
-   `serper_images`, 1 信用, 2 当 `num` 10岁以上。 图像结果带有维度和源.
-   `serper_news`一分功劳 日期新闻结果.
-   `serper_places`,1功劳. 当地企业通过Serper定位名称过滤.
-   `serper_maps`3个学分 定位到地图视图端口 `@lat,lng,zoomz` 形式.
-   `serper_videos`,1功劳. 视频结果包含频道和持续时间.
-   `serper_shopping`,2个入分. 产品上市并附有价格和交货.
-   `serper_scholar`,1功劳. 载有出版物资料和引文的论文.
-   `serper_patents`,1功劳. 与受让人的专利和日期.
-   `serper_autocomplete`,1功劳. 查询建议, 只取 `q`, (中文(简体) ), `gl`,以及 `hl`。 。 。 .
-   `serper_reviews`,1功劳. 对一个地方的审查,通过光标标记 `nextPageToken`。 。 。 .
-   `serper_lens`3个学分 反向图像搜索公共图像 URL .
-   `serper_scrape`, 2, 6, 或按页面难度的10个入分. 页面内容为Markdown或文本,可选标题,图像,链接,和视频,以及从回复中读取的实际入分.
-   `serper_health`自由且无认证 Serper API 从 api.serper.dev 的状态.
-   `serper_locations`自由且无认证 指定位置名称 `location`。 。 。 .
-   `serper_resolve`免费的。 真实目的 URL `google.com/goto` 链接搜索返回.
-   `serper_session`免费。 呼叫计数,信用,美元,代币 已送达和保存,缓存点击,预算也离开了.
-   `serper_search_batch`,每个查询单价的3倍。 一通电话中最多100个查询到一个搜索家庭,除非 `enable_batch` 已经设定。 在残疾时拒绝呼叫 `serper.tool_not_found`。 。 。 .

`serper_search` 发送 `num: 10` 当召唤者离开的时候 `num` 因此,一个电话总是要求 一个完整的谷歌页面 同样的信用。 提升 `num` 最多100个电话请求更多 并保持 `page` 与它步调一致.

`serper_search`, (中文(简体) ), `serper_images`,以及 `serper_videos` 也向Google询问去年的结果,除非打电话者另有说法,因为参考文献比通常过时的时间要长. 一个电话设置 `tbs` 选择另一个窗口,和 `tbs: all` 每年搜索。 默认窗口来自 `default_freshness` 在剖面图中或 `OWN_SERPER_DEFAULT_FRESHNESS` a. 环境、环境和环境 `hour`, (中文(简体) ), `day`, (中文(简体) ), `week`, (中文(简体) ), `month`, (中文(简体) ), `year`,或 `all`。 。 。 .

## 反应形状和外地预设

每个结果工具都使用 `fields`,默认为 `standard`。 。 。 .

-   `minimal` 保留标题、链接、显示链接和排名,加上家庭报告的一个价格、日期、评级或年份字段。 适合高容量回路.
-   `standard` 将封入的片段加到300个字符,日期,以及搜索部分. 它携带着一个特工需要的 解释和引用,没有第二次通话.
-   `full` 添加站点链接,属性地图,图像链接,搜索参数回声,以及上游机体所携带的所有其他字段.

每个结果都包含 `structuredContent` 和单行文本摘要。 封装字符串以 `...` 他们的物体载着 `truncated: true`。缺席的字段被省略,而不是作为无效发送。 密钥顺序是固定的,所以一个客户端在每次呼叫时都会描述出相同的形状. 每个工具的结果都是来自开放式网络的数据,从来不是指令.

Google 返回许多有机结果 `google.com/goto?url=...` 重定向而非目的页面 。 搜索在回答之前就解决了 所以 `link` 携带目的地,不需要第二次通话。 服务器发送对Serper的回复 `/resolve`在Google上只花费了5秒左右, 一通电话 `resolve_links: false`,或服务器 `auto_resolve_links = false`,所有链接都和谷歌发送的一样. `displayedLink` 携带 Google 显示的可读格式以获取结果, 通常 `site › path` 并且有时还算着评论或视图. `serper_resolve` 对您已经持有的链接进行相同的工作,然后返回 `retryAfter`在Google尚未发布之前.

## 示例

一个工具呼叫是JSON-RPC在stdio请求. 服务器验证了参数,通过TLS向Serper发送查询,为模型塑造答案,将成本记录入分类账,并返回结果.

请:

```json
{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"serper_search","arguments":{"q":"rust programming language"}}}
```

回应:

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "9 results; cost: 1 credit ($0.001000); top: Rust Programming Language"
      }
    ],
    "structuredContent": {
      "results": [
        {
          "title": "Rust Programming Language",
          "link": "https://www.rust-lang.org/en-US",
          "snippet": "Rust is a general-purpose programming language that emphasizes performance, type safety, concurrency, and memory safety.",
          "position": 1
        }
      ],
      "cost": {
        "credits": 1,
        "usd": 0.001,
        "sessionCredits": 22,
        "sessionUsd": 0.022
      },
      "truncated": false
    },
    "isError": false
  }
}
```

`content` 持有一行摘要. `structuredContent` 持有数据 `cost` 报告此呼叫和正在运行的会话。 当一个电话失败, `isError` 是真的,还有 `structuredContent` 携带一个 `code`页:1 `message`,则a `remedy`。 。 。 .

## 成本核算和分类账

该分类账住在 `$XDG_DATA_HOME/ownserp/ledger/calls.jsonl`,或 `~/.local/share/ownserp/ledger/calls.jsonl`在它居住的窗口上 `%LOCALAPPDATA%\ownserp\ledger\calls.jsonl`,何时 `HOME` 它被设置在Unix路径上。 一行持有工具,终点,一个按键的散列参数,估计得分,反应报告时的实际得分,持续时间,状态,字节,和符号计数. 查询文本从未被写入 .

塞尔珀以4xx或5xx状态拒绝的电话,有费率限制的答案,或者有转接方向的答案,被记录为零入分,因为没有计费. 暂停或取消记录在估计值中,因为请求可能已经到达Serper并被开出账单.

```sh
ownserp audit verify
```

在Unix上,分类账目录只有所有者(0700),文件只有所有者(0600). 在Windows上 它坐落在下面 `%LOCALAPPDATA%`,因此它继承了用户配置文件的访问规则. 一行被封为一米B. 任何数目 `ownserp serve` 一个机器上的流程共享这个文件,一个散列链和一个运行的总计。 一个进程只在读取自上次调用以来所写的行并附加自有行时才取取文件锁,因此,只要它运行,任何进程都无法持有锁. 仅丢失了新行的最后一行被保留下来,因为它的散列证明它是被写的;任何不完全的被放入锁下,链检查覆盖了每一个完整的行. 每行都带有格式版本,由更新型的二进制所撰写的文件被名字拒绝,而不是被读取为损坏. 在Windows上,运行中的服务器不注意旋转,所以重新启动它来取取新链. 参数散列是一个 HMAC,一个按键散列,由 `args.key`,在分类账目录旁边创建的,只有所有者权限,所以单是分类账无法确认一个被猜测的查询.

`session_budget_credits` 计算链中的每一笔信用, 不论过程如何。 另一程序保留但尚未写入的信用对这项检查来说是看不见的,因此,预算最多可以以运行程序的数目乘以每笔信贷上限。 只有在设定了上限时,这个约束才有效。 在没有上限的情况下,这个过程是最大单项保留次数的倒数,即100克地图或镜头批次的900分。 响应缓存保留每个进程:每个进程都保留自己的缓存. `OWN_SERPER_LEDGER_DIR` 仍给客户自己的独立分类账 这是你想要的.

要关闭一个分类账而不丢失它,运行 `ownserp audit rotate`它核查链条,并用时间戳将文件存档在原件旁边。 每个运行的服务器在其下个写入上打开了一条新链. 当链子已经损坏时, `ownserp audit rotate --archive-damaged` 将文件存档到已核实的最后一行,这样就可以开始新的链条,而支出历史仍然可以读取. `ownserp audit remove --yes` 删除活分类账、其档案和参数密钥,并打印其删除的每个路径;没有 `--yes` 它只说它会删除什么.

美元数字来自组合级: `starter` (违约), `standard`, (中文(简体) ), `scale`, (中文(简体) ), `ultimate`,或 `custom` 与 `SERPER_USD_PER_1K`。 。 。 .

## 配置

环境变量:

-   `SERPER_API_KEY`
-   `SERPER_USD_PER_1K`
-   `OWN_SERPER_PROFILE`
-   `OWN_SERPER_BIND`
-   `OWN_SERPER_CACHE_TTL_SECS`
-   `OWN_SERPER_LEDGER_DIR`
-   `OWN_SERPER_BEARER_TOKENS`
-   `OWN_SERPER_ALLOWED_HOSTS`
-   `OWN_SERPER_LOG_FORMAT`,设置为 `json` 每个日志行一个 JSON 对象

配置文件位于 `$XDG_CONFIG_HOME/ownserp/profile.toml`,或 `~/.config/ownserp/profile.toml`。在视窗上它是 `%APPDATA%\ownserp\profile.toml` 何时 `HOME` 未设定 :

```toml
version = 1
pack = "starter"
usd_per_1k = 1.0
cache_ttl_secs = 0
cache_max_bytes = 16777216
ledger_dir = "/absolute/path/to/ownserp-ledger"
per_call_credit_ceiling = 10
session_budget_credits = 500
enable_batch = false
http = false
bind = "127.0.0.1:8777"
request_timeout_secs = 30
default_freshness = "year"
auto_resolve_links = true
```

`version` 是剖面图版本。 今天是1,一个新版本的名字被拒绝.

`ledger_dir` 采取绝对的道路。 文件是 TOML 文档, 所以 `~` 或一个变量被字面地存储而不是扩展.

`session_budget_credits` 计算所有向当前分类账链记录的信用,通过重启 `ownserp audit rotate` 开始重新计数. `allowed_hosts` 列表主机名 HTTP 模式可接受; 保留它以从绑定地址中获取.

一个没有的自定义包 `usd_per_1k` 由于汇率不明,因此没有美元数额的贷项.

缓存默认关闭 . `cache_ttl_secs` 高于 0 打开; 命中答案 `cacheHit: true` 并且不收费。 一个电话设置 `tbs` 本身跳过缓存,而默认的新鲜度窗口没有.

`ownserp doctor` 打印解析的设置,包括默认的新鲜度窗口,遮盖密钥,密钥出处的名称,并探测两个主机. `ownserp config show` 打印密钥源、口罩密钥、信用包、分类账目录和配置路径.

## HTTP 部署

```sh
OWN_SERPER_BEARER_TOKENS="a random value of at least 32 characters" \
  ownserp serve --http --bind 127.0.0.1:8777
```

`/healthz` 打开. `/readyz` 财务报告和审定财务报表 `/metrics` 何时需要无记名标志 `OWN_SERPER_BEARER_TOKENS` 设置,其他路径都是 MCP 终点。 服务器拒绝一个没有符号的非回放绑定,拒绝一个短于32个字符的符号. 它根据每个受保护路线上的许可列表检查主机头,在1 MiB时封入一个请求机体,并给请求机体30秒到达,最多接受256个连接,一次性封存最多128个请求,从每个请求的截止日期算起 `request_timeout_secs` 和重试计数,并在最后期限过后取消调用,拒绝一个带有源头的请求,并标记每个响应 `x-content-type-options: nosniff` 与 `cache-control: no-store`。一个服务器上的每个无记名符号共享服务器的分类账、会话预算和缓存。 在代理服务器后面列出它发送的名字 `OWN_SERPER_ALLOWED_HOSTS` 并让代理执行自己的头和闲置的超时.

## 警卫

服务器持有一个API密钥,仅通过TLS向Serper发送查询,不发送遥测. TLS 根集被捆绑入二进制中, 因此一个容器没有 `ca-certificates` 仍可验证Serper;加载时会添加平台根. 结果被视为不可信的案文. [警卫](https://npmcn.com/package/%40devops-infinity/ownserp/SECURITY.md) 说明报告程序,以及 [威胁模型](https://npmcn.com/package/%40devops-infinity/ownserp/docs/threat-model.md) 说明资产、信托边界、控制和剩余风险.

## 解决问题

每个出错都包含一个稳定的代码,一个消息,一个补救方法,对于网络故障,最多可有3个命名为DNS,TLS,或连接问题的已消毒原因. HTTP 运输拒绝带同一对象,并带有代码 `serper.unauthorized`, (中文(简体) ), `serper.auth_rate_limited`, (中文(简体) ), `serper.host_refused`, (中文(简体) ), `serper.origin_refused`,以及 `serper.busy`。 。 。 . `ownserp` 成功时退出 0,运行时间失败时退出 1,使用错误时退出 2. `ownserp doctor` 当没有配置密钥或当Serper健康检测失败时, 退出 1; 账户端点不报出但不是失败的余额 。 守则及其修正:

-   `serper.auth_missing`。没有配置密钥,或者无法读取 OS 密钥链;原因名称是什么 。 设定 `SERPER_API_KEY` 运行 `ownserp config set-api-key`,然后重新启动服务器.
-   `serper.auth_failed`Serper拒绝了钥匙 检查一下 [https://serper.dev/api-keys (英语)](https://serper.dev/api-keys)。 。 。 .
-   `serper.credits_exhausted`. Serper账户没有入帐。 顶上 [https://serper.dev/dashboard (英语)](https://serper.dev/dashboard),然后再次打电话.
-   `serper.rate_limited`. 上游利率限制停止了呼叫. Serper不发布重试头,服务器不重试429.
-   `serper.budget_refused`. 将通过每名发言者的上限或会议预算。 在配置文件或环境中提升并重新启动服务器, 或者降低 `num`。 。 。 .
-   `serper.bad_request`。一个参数失败验证 。 消息取出字段名称 .
-   `serper.tool_not_found`。该工具不在此配置列表中。 打电话 `tools/list` 并只使用它返回的名称.
-   `serper.tool_disabled`。该工具存在,但设置使其不受影响。 设置信件名称的密钥, 如 `enable_batch`,然后重新启动服务器.
-   `serper.deadline_exceeded`。这个电话超过了服务器的最后期限,可能已经开具了账单。 用更窄的请求重试, 或加高 `request_timeout_secs`。 。 。 .
-   `serper.config_error`设置不正确. `ownserp doctor` 显示每个已解析的值及其源,即使失败的设置是它无法解析的.
-   `serper.keychain_error`。OS 键链不可用。 使用 `SERPER_API_KEY` 在一个无头的东道主.
-   `serper.ledger_fault`无法读取或写入本地调用分类账,或者无法使用其他程序。 检查分类账目录和空闲空间, 然后重新启动; 如果链被损坏, 运行 `ownserp audit rotate --archive-damaged`。 。 。 .
-   `serper.upstream_failed`。Serper 或网络在重试后失败 。 检查 [https://serper.betteruptime.com (中文(简体) )](https://serper.betteruptime.com/)。 。 。 .
-   `serper.cancelled`. 请求在出道时被取消.
-   `serper.internal_error`意外的局部失败。 重试一次,然后打开一个问题与消息.

## 发展

这条路需要1.89或更新 被钉入1.99.1英寸 `rust-toolchain.toml`。 。 。 .

```sh
cargo install --path crates/ownserp --locked
tools/verify.sh
```

`tools/verify.sh` 在本地运行整个大门:格式化、检查、带警告的剪接、拒绝、测试、医生测试、文件、咨询、依赖政策、抑制重新检查日期、未使用的依赖性、表单版本、80%的行覆盖层、对树和基特历史的秘密扫描。 检查其工具被报告为跳过,以及 `OWN_SERPER_STRICT_GATE=1` 将任何跳过都变成失败; 释放会这样运行 .

`tools/smoke.sh [base-url]` 探测运行中的服务器 : `/healthz`, (中文(简体) ), `/readyz`, (中文(简体) ), `/metrics`,MCP握手,和 `tools/list`它写着: `OWN_SERPER_BEARER_TOKENS` 当服务器需要符号时。 部署后运行.

发行版本身运行在 `.github/workflows/release.yml` 在本地跑者矩阵上,当 `v*` 标记被推出 .

当地生命周期:

-   `tools/reinstall.sh` 构建和安装二进制 `~/.local/bin`。 。 。 .
-   `tools/release.sh --prepare` 缓冲版本; `--package` 建立归档和校验和 .
-   `tools/publish-npm.sh` 发布 npm 软件包; `tools/npm-auth-setup.sh` 存储使它无污染的符号.
-   `tools/registry-auth.sh` 刷新 GitHub, npm, 箱子. io, MCP 注册, 以及已经存在于您外壳的环境变量中的 ghcr 会话, 因此在发布时没有注册请求 .
-   `tools/install-hooks.sh` 指向本地的钩子:在每次下手前进行秘密扫描,在每次出手前进行全门扫描.
-   [相关内容](https://npmcn.com/package/%40devops-infinity/ownserp/RELEASING.md) 是发行的运行簿.

## 分发

-   货箱.io: `ownserp` 财务报告和审定财务报表 `ownserp-core`。 。 。 .
-   无 : `@devops-infinity/ownserp`。 。 。 .
-   土人水龙头: `devops-infinity/tap`。 。 。 .
-   MCP 登记册: `io.github.devops-infinity/ownserp`。 。 。 .
-   GitHub发布:macOS ARM64和x86 64,Linux x86 64和ARM64的档案有glibc,Linux x86 64和ARM64有静态musl,而Windows x86 64则各有验收和,外加外壳安装器,PowerShell安装器和Linux MCPB捆.
-   容器图像 : `ghcr.io/devops-infinity/ownserp`,公众.
-   该寄存处的特征: `server.json`, (中文(简体) ), `mcpb/manifest.json`,以及 `Dockerfile`。 。 。 .

## 支助

打开一个问题在 [https://github.com/devops-infinity/ownserp/issues (中文(简体) )](https://github.com/devops-infinity/ownserp/issues) 用于提问、错误或特性请求。 通过私人频道报告安全问题 `SECURITY.md`从来没有在一个问题.

## 捐款

欢迎提出问题和拉动请求 [https://github.com/devops-infinity/ownserp 页面存档备份,存于互联网档案馆](https://github.com/devops-infinity/ownserp)运行 `tools/verify.sh` 在打开拉动请求之前; 更改只在出站口经过时着陆。 读取 `RELEASING.md` 在剪辑释放之前.

成果出自谷歌通过塞伯尔. 下游用户在他们身上保留着Serper的归属责任条款.

## 许可证

麻省理工学院或阿帕奇2.0. 见 [利马](https://npmcn.com/package/%40devops-infinity/ownserp/LICENSE-MIT) 财务报告和审定财务报表 [自由主义](https://npmcn.com/package/%40devops-infinity/ownserp/LICENSE-APACHE)。 。 。 .

## 常见问题

### @devops-infinity/ownserp 是什么？

OwnSERP,用于Serper\.dev搜索 API 的 MCP 服务器,超过 stdio和可流的 HTTP

### 如何安装 @devops-infinity/ownserp？

在项目目录运行 npm install @devops-infinity/ownserp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ownserp，可以用 npx ownserp 直接运行。

### @devops-infinity/ownserp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/devops-infinity\_\_ownserp 是否存在。

### @devops-infinity/ownserp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=14\.14。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @devops-infinity/ownserp 可以商用吗？

@devops-infinity/ownserp 使用 MIT OR Apache-2\.0 许可。可在 MIT、Apache-2\.0 中任选其一遵守。选择 MIT 时，宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @devops-infinity/ownserp 的下载量有多少？

根据 npm 官方下载统计，@devops-infinity/ownserp 在 2026/10/12 – 2026/11/10 这 30 天内被下载 4,095 次，日均约 137 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @devops-infinity/ownserp 还在维护吗？

最新版本 2\.4\.0 发布于 2026/10/30（12 天前）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/10/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。