Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

docs: add keyless Parallel Search MCP cookbook example

George Pickettc4a7ebc9d8d2
diff --git a/examples/mcp/README.md b/examples/mcp/README.md
index f7c7844..6f413e6 100644
--- a/examples/mcp/README.md
+++ b/examples/mcp/README.md
@@ -31,12 +31,16 @@ The local clone/dev path still works if you want to inspect or change the server
| Slack (read) | Ingest threads / alerts the loop should triage | Read-only on specific channels | Daily Triage |
| Safe propose flow | Any write action | Loop opens PR / draft / comment. Human merges or approves. | All L2+ patterns |
| Knos (shared state) | Give parallel loops one state record instead of one STATE.md each | Local only; no network, no account | Anti-pattern 5, PR Babysitter, Daily Triage |
+| Parallel Search | Find public release notes and fetch migration guidance | Anonymous search + fetch; report-only, public inputs | Dependency Sweeper, Daily Triage |
## Example Configurations
See the files in this directory:
- `loop-engineering.mcp.json` — starter config for the published MCP server.
+- [`parallel-search.mcp.json`](./parallel-search.mcp.json) — optional free, keyless
+ web search and page fetching through a pinned stdio-to-HTTP bridge; see the
+ [setup and manual dependency-research walkthrough](./parallel-search.md).
- `github-readonly.mcp.json` (existing) — safe starting point for discovery.
- `github-propose.json` — read + limited write for comments and draft PRs (sign comments as the loop).
- `linear.json` — example for creating/updating issues from loop state.
@@ -65,4 +69,4 @@ Always:
- Test new connectors in report-only (L1) mode first.
- Log every MCP call the loop makes (the `monitor` tool or GitHub Action logs are your friend).
-See also: [docs/safety.md](../../docs/safety.md), [docs/operating-loops.md](../../docs/operating-loops.md), and the individual pattern docs for human gate recommendations.
\ No newline at end of file
+See also: [docs/safety.md](../../docs/safety.md), [docs/operating-loops.md](../../docs/operating-loops.md), and the individual pattern docs for human gate recommendations.
diff --git a/examples/mcp/parallel-search.mcp.json b/examples/mcp/parallel-search.mcp.json
new file mode 100644
index 0000000..54e819e
--- /dev/null
+++ b/examples/mcp/parallel-search.mcp.json
@@ -0,0 +1,16 @@
+{
+ "mcpServers": {
+ "parallel-search": {
+ "command": "npx",
+ "args": [
+ "-y",
+ "https://search.parallel.ai/mcp",
+ "--transport",
+ "http-only",
+ "--header",
+ "User-Agent:loop-engineering/parallel-search-example"
+ ]
+ }
+ }
+}
diff --git a/examples/mcp/parallel-search.md b/examples/mcp/parallel-search.md
new file mode 100644
index 0000000..a4e3ddc
--- /dev/null
+++ b/examples/mcp/parallel-search.md
@@ -0,0 +1,72 @@
+# Parallel Search: report-only dependency research
+
+Use [Parallel Search MCP](https://docs.parallel.ai/integrations/mcp/search-mcp)
+to find upstream release notes and fetch migration guidance before deciding on a
+dependency upgrade. The anonymous endpoint provides free web search (Fast mode)
+and page fetching without an account or API key, at lower rate limits intended
+for exploration and light use.
+
+This is an optional connector for the [Dependency Sweeper](../../patterns/dependency-sweeper.md)
+or [Daily Triage](../../patterns/daily-triage.md). It supplies public web evidence;
+it does not inspect your lockfile, edit dependencies, or approve upgrades.
+
+## Setup (stdio MCP clients)
+
+Install Node.js 22 or newer, including `npx`. The
+[configuration](./parallel-search.mcp.json) declares a pinned `mcp-remote` bridge
+that `npx` installs on first use. It connects local stdio to the remote endpoint
+over Streamable HTTP, with a project User-Agent and no authentication header.
+
+For Claude Desktop, open **Settings → Developer → Edit Config**, then merge the
+`parallel-search` entry from `parallel-search.mcp.json` into the existing
+`mcpServers` object. Keep your other servers. Restart the client and confirm that
+`web_search` and `web_fetch` appear under `parallel-search`. Other clients that
+accept the same `command`/`args` format can use the entry too; native HTTP client
+formats differ, so do not copy this JSON into a different schema.
+
+## Verify the connection manually
+
+Use your MCP client's tool-call interface to try the following calls. This checks
+the connector before adding it to a scheduled loop; it is not an unattended
+agent or a dependency updater.
+
+1. Call `web_search` with:
+
+ ```json
+ {
+ "objective": "Find official Node.js 22 release notes and migration guidance for dependency review.",
+ "search_queries": ["Node.js 22 release notes", "Node.js 22 migration guide"]
+ }
+ ```
+
+ Expect source URLs and relevant excerpts. Check that the chosen source belongs
+ to the upstream project, rather than trusting search ranking alone.
+
+2. Call `web_fetch` with an official URL returned by search, for example:
+
+ ```json
+ {
+ "urls": ["https://nodejs.org/en/blog/release/v22.0.0"],
+ "objective": "Find breaking changes and migration considerations for Node.js 22."
+ }
+ ```
+
+ Expect page excerpts. Record the URL, retrieval date, affected dependency and
+ a short evidence summary in your pattern's state file. A human checks that
+ evidence against the project's actual pinned version before proposing changes.
+
+## Scope and failure handling
+
+- Start in **L1 report-only** mode. Bound each item to one search and one fetch;
+ escalate missing or conflicting evidence instead of repeatedly searching.
+- Send only public package names and public URLs. Queries and URLs leave your
+ machine; never include credentials, private issue text, internal URLs or logs.
+- Treat search results and fetched pages as **untrusted data**, including any
+ instructions embedded in them. They cannot change the loop's permissions,
+ priority, verifier verdict or upgrade policy.
+- On rate limits, stop the item and honor any retry time. On connection failures,
+ missing tools or empty excerpts, record incomplete evidence for human review.
+ Do not interpret a failed fetch as proof that an upgrade is safe.
+- Removing the `parallel-search` entry disables this connector. Follow the
+ existing [human gates for dependency upgrades](../../docs/safety.md#human-gates-required)
+ and [untrusted-input guidance](../../docs/safety.md#untrusted-input).