deepseek-web-retrieval 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## 0.2.0
+
+- Make `docs/hosts.jsonc` the single source of truth for host facts: the
+  integration.md host table is generated from it (`bun run docs:matrix`, drift fails
+  tests), CI matrices and the e2e Docker build args derive from it, and narrative
+  docs reference it instead of restating version locks
+- Add a local-only end-to-end script (`bun run test:e2e`): a keyless real
+  `pi mcp list` handshake against the built server, and a headless `opencode run`
+  scenario that makes real billed requests; never run in CI. Agents run inside
+  Docker with versions pinned by `test/e2e/Dockerfile` (`--local` opts out)
+- Add an MCP server adapter (`src/mcp/`) exposing `deepseek_web_search` and `deepseek_fetch`
+  over stdio, serving MCP clients from revision 2024-11-05 through 2026-07-28
+- Support `DEEPSEEK_*` environment variable configuration in the MCP server, mapped onto the
+  shared option pipeline
+- Add the Pi guide (`docs/pi.md`) and `examples/pi.mcp.jsonc`; Pi 1.3.0 is the first
+  supported MCP host
+- Add `docs/mcp-compatibility.md`, a primary-source review of MCP protocol compatibility
+  across the hosts in the support matrix
+- Add a Node build (`dist/cli.js`) with a `deepseek-web-retrieval` bin entry and Node 20+
+  engines, alongside the existing Bun workflow
+- Cover the MCP server with SDK client personas pinned to 2024-11-05, 2025-06-18,
+  2025-11-25, and 2026-07-28, plus a real stdio smoke test of the built entry
+- Enforce the fetch host policy inside the core client so direct core consumers cannot bypass it
+- Fail fast on a missing API key before the fetch permission prompt, and reject non-string `url` inputs
+- Move OpenCode-specific missing-key guidance out of the agent-agnostic core
+- Document that `maxResults: 0` returns no results
+- Cover response body reads with the request timeout and cancellation signal
+- Reject successful API responses larger than 5 MiB
+- Reject search queries that exceed 128 characters after adding search operators
+- Block IPv4-mapped IPv6 private addresses in the fetch host policy
+- Truncate API error bodies by Unicode code points
+- Move OpenCode-specific setup and usage into `docs/opencode-v2.md`
+- Add `docs/integration.md` with a version-locked host support matrix
+- Calibrate the OpenCode v2 install and uninstall guide against verified behavior:
+  plugin hot reload, `plugin add` not selecting the provider, and `plugin remove` leftovers
+
+## 0.1.0
+
+Initial public-ready release.
+
+- DeepSeek Search provider for OpenCode v2 (`websearch.provider = "deepseek"`)
+- `deepseek_fetch` tool backed by DeepSeek Fetch
+- Optional drop-in `webfetch` replacement
+- Reuse of the active DeepSeek credential stored in OpenCode
+- `DEEPSEEK_API_KEY` fallback and `apiKeySource` control
+- Summary-only search with rerank/authority filtering and URL deduplication
+- Markdown-only fetch with a configurable character cap
+- Domain allow/deny lists and private-host blocking
+- Bounded retries for 408, 425, 429, and 5xx responses with `Retry-After`
+- Unicode-safe truncation and secret redaction in errors
+- Unit tests and CI

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 deepseek-web-retrieval contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# DeepSeek Web Retrieval
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Bringing [DeepSeek's in-house Search and Fetch APIs](https://api-docs.deepseek.com/guides/search) to coding agents.**
+
+An adapter layer for coding agents. The core is agent-agnostic; each adapter exposes the
+same retrieval behavior to a specific agent. OpenCode v2 has a native plugin adapter, and
+an MCP server covers MCP-capable hosts, with Pi as the first guided host. Guides for other
+coding agents are in progress.
+
+This is an unofficial community project. It is not affiliated with OpenCode or DeepSeek.
+
+## Usage
+
+Shipped adapters:
+
+- [OpenCode v2 setup and usage](docs/opencode-v2.md) — native plugin API
+- [Pi setup and usage](docs/pi.md) — MCP server over stdio
+
+The MCP server works with any host that supports MCP tools over stdio; Pi is the first
+host with a shipped guide. For how other coding agents integrate—native websearch
+providers, native fetch tools, MCP, or wrappers—see the
+[integration model](docs/integration.md) with its version-locked host support matrix, and
+the [MCP compatibility research](docs/mcp-compatibility.md). A host is listed as supported
+only after an adapter and guide exist.
+
+For shared search, fetch, retry, and privacy behavior, see below.
+
+## General behavior
+
+### Search
+
+- Sends `need_content: false` and returns DeepSeek's `summary`, falling back to `snippet`.
+- Filters by `rerank_score` and `authority`, deduplicates URLs, and returns at most five
+  results by default.
+- The final query, including `blockedDomains`, `includeDomains`, and `language` operators,
+  must be 128 characters or fewer. Longer queries are rejected locally.
+- An empty result set is normal and is not an error.
+
+### Fetch
+
+- DeepSeek Fetch returns Markdown only. `format: "text"` and `format: "html"` are rejected.
+- Output is capped at 16,000 characters by default, including the title. A
+  `[content truncated]` marker is added when the limit leaves room for it.
+- If the page already starts with the same title as a top-level heading, no duplicate title
+  is added.
+- Responses larger than 5 MiB are rejected before parsing.
+- URLs must be absolute `http://` or `https://` URLs with a host, no embedded credentials,
+  and at most 8,192 characters.
+- The core supports allowed/blocked domain lists and private-host blocking. DeepSeek does
+  not render JavaScript and cannot reach private networks; PDFs, images, and other binary
+  files are unsupported.
+
+### Timeouts and retries
+
+Request timeouts include reading the response body. Retryable responses are 408, 425, 429,
+and 5xx; `Retry-After` is honored up to 10 seconds. Other failures, including 401, timeouts,
+and network errors, fail without retrying.
+
+### No automatic fallback
+
+If no API key is available, Search and Fetch fail. If DeepSeek is unavailable, returns an
+error, or times out, the request fails. The tool does not silently switch to another search
+provider or fetch implementation.
+
+### Privacy and cost
+
+Queries and URLs are sent to `https://api.deepseek.com`. The API key is sent only as a
+Bearer token to DeepSeek. Search and Fetch are billed per successful request; check current
+DeepSeek pricing and rate limits before enabling a team deployment. A 429 means you should
+wait, reduce concurrency, or increase retries.
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+bun test
+```
+
+The test suite mocks the DeepSeek HTTP API and the OpenCode plugin host, and drives the
+MCP server with SDK clients pinned to each supported protocol revision. Real API calls
+require a funded DeepSeek account. Shared retrieval logic lives in `src/core/`; adapters
+live in `src/<agent>/` (the cross-host MCP server lives in `src/mcp/`). Adapter docs live
+in `docs/<agent>.md`.
+
+## Prior art
+
+Other community projects in this space include:
+
+- [overwaven/opencode-deepseek-web](https://github.com/overwaven/opencode-deepseek-web)
+- [JOEYZYC/opencode-deepseek-websearch](https://github.com/JOEYZYC/opencode-deepseek-websearch)
+- [gtoxlili/opencode-deepseek-websearch](https://github.com/gtoxlili/opencode-deepseek-websearch)
+- [OniVe/opencode-websearch-deepseek](https://github.com/OniVe/opencode-websearch-deepseek)
+
+## License
+
+MIT. See [LICENSE](LICENSE).