@j6e/pi-md-web-surfer

Pi extension: fetch web pages as markdown and search the web, powered by Jina AI

Packages

Package details

extension

Install @j6e/pi-md-web-surfer from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@j6e/pi-md-web-surfer
Package
@j6e/pi-md-web-surfer
Version
0.9.3
Published
May 17, 2026
Downloads
199/mo · 199/wk
Author
j6e
License
MIT
Types
extension
Size
37.1 KB
Dependencies
1 dependency · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-md-web-surfer

A pi extension that adds fetch_markdown and web_search tools — fetch web pages as clean markdown and search the web.

Inspired by the skill of the same name.

Tools

fetch_markdown

Fetch any web page as clean, token-efficient markdown.

Three strategies, tried in order:

  1. Content Negotiation — Sends Accept: text/markdown header. Sites using Cloudflare's Markdown for Agents return markdown directly (~80% fewer tokens than HTML).
  2. Direct text/plain — For raw .md files, text/plain responses, etc. The body is already clean text, so we use it directly.
  3. Jina Reader (fallback) — For sites that return HTML, routes through r.jina.ai which renders the page and extracts clean markdown.

Usage:

fetch_markdown(url, info?)

web_search

Search the web and return results as clean markdown via Jina Search.

Requires a Jina API key. Get one free at jina.ai/?newKey, then configure it with /md-web-surfer-config or the JINA_API_KEY environment variable.

Usage:

web_search(query, num?, info?, retainImages?, withLinksSummary?)
  • query — Search query
  • num — Number of results (1–20, default 5)
  • info — Include metadata (method, tokens)
  • retainImages — Image retention mode: "none" (default), "all", or "alt_text" (keep alt text with auto-generation)
  • withLinksSummary — Include a summary section for hyperlinks (default: false)

Configuration

/md-web-surfer-config

Interactive command to set your Jina API key. Writes to ~/.config/pi-md-web-surfer/config.json (chmod 0600).

/md-web-surfer-config        # prompt for key
/md-web-surfer-config --show # show current key status (masked)

API key resolution

First match wins:

  1. JINA_API_KEY environment variable
  2. jinaApiKey field in ~/.config/pi-md-web-surfer/config.json

Installation

Quick test (one session)

pi -e ./src/index.ts

Persistent (auto-discovered)

ln -s $(pwd) ~/.pi/agent/extensions/pi-md-web-surfer

Then run pi normally. The tools appear alongside read, write, edit, etc.

As a pi package

pi install npm:@j6e/pi-md-web-surfer

Development

npm install
npm test           # run tests once
npm run test:watch # TDD mode
npm run check      # typecheck

Smoke test against real URLs:

node --experimental-strip-types scripts/smoke-test.ts

Requirements

  • Node.js 22+ (for --experimental-strip-types)
  • pi-coding-agent 0.74+

License

MIT