[Ugasutun]

Closes #409

Summary

MCP exposed prices (L213) but nothing for discovery. An agent couldn't list
which pairs exist, see the liquidity behind them, or find what's moving, so it
had to guess asset codes. This PR adds three MCP tools that wrap the existing
/pairs, /pools and /screener logic.

Changes

• Added lens_list_pairs, lens_get_pools and lens_screen_pairs MCP tools.
• Extracted the query logic behind /pairs, /pools and /screener into
  shared service functions. The REST routes and MCP tools both call them, so
  there is a single implementation and no duplicated queries.
• All three tools return bounded results (default limit of N, hard max of M)
  with a next_cursor / offset field for fetching the next page.
• Every asset in a result includes its full issuer address, never truncated.
• Tool descriptions state when to use each tool:
  • lens_list_pairs: enumerate which pairs exist, e.g. to discover valid
    asset codes before asking for a price.
  • lens_get_pools: inspect the liquidity behind a specific pair.
  • lens_screen_pairs: find pairs by movement or criteria, e.g. top movers.

Pagination

Pass the next_cursor from a previous response as cursor to get the next
page. When next_cursor is null, there are no more results. The parameters
are documented in each tool's input schema and in docs/mcp.md.

Testing

• Parity tests call each REST route and its MCP tool with the same inputs and
  assert the payloads match.
• Tests assert that results never exceed the page limit and that following the
  cursor yields the next page with no overlap.
• Tests assert that issuers are returned in full (no shortened form like
  GABC…XYZ).
• Tests assert that the three tool descriptions are distinct.

Checklist

• All three tools exist and share implementations with the REST routes
• Results are bounded, with a documented way to get the next page
• Issuers appear in full
• Descriptions distinguish the tools from one another
• Tests assert parity with the corresponding REST route
• Docs updated

[drips-wave]

@Ugasutun Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Miracle656]

Coordination note — ten PRs are editing one 179-line file

If your MCP PR has just gone red with a conflict, this is why, and it is my fault rather than yours.

I published 22 MCP issues (#404–#425) as if they were independent. They are not: almost all of them land in src/mcp/server.ts, which is 179 lines long. Every merge therefore conflicts everything else. The batch should have been sequenced, or scoped so the work genuinely separated — that was a mistake in how I wrote the issues, not in how you answered them.

Already merged:

• fix(security): block SSRF in bazaar_search via URL validation, post-DNS IP checks, and guarded redirects #488 — SSRF guard for bazaar_search, adding src/net/ssrf.ts. This is what just conflicted everything, because it touches server.ts and codes.ts.
• docs(mcp): add README for examples/mcp-server and link from repo README #486 — examples/mcp-server/README.md.

Order I intend to take the rest in, so you can rebase once rather than repeatedly:

1. feat: add configurable host allow-list to paid_call, refuse before any request #487 — paid_call host allow-list (paid_call will pay whatever URL the agent names #404). The gate that decides which hosts may be paid. This one goes next because everything else about spending is narrower than it.
2. feat(mcp): bound cumulative spend, audit payments, serve over HTTP #491 / fix(mcp): bound cumulative daily paid-call spend, not just per call #492 — cumulative spend ceiling and payment audit (The spend cap is per call, so it is not a cap #405, Nothing records what the agent spent #406). These bound and record what happens to hosts the allow-list permits.
3. fix: classify MCP paid-call errors by structured signals #480 — structural error classification (Errors are classified by searching the message text #410).
4. fix(mcp): bound tool result size, stream-cap upstream reads, and report truncation explicitly #489 — bounded tool results (Tool results are unbounded #416).
5. feat: add lens_get_price tool returning aggregated pair price with issuer-strict assets #493 / feat: add lens_list_pairs, lens_get_pools and lens_screen_pairs tools #482 / feat: declare the resources capability and expose pairs, venues, OpenAPI spec, and status #494 — the new Lens tools and the resources capability (An agent cannot ask Lens for a price #408, No tool exposes pairs, pools or the screener #409, The server advertises only tools, not resources #418).
6. test(mcp): add end-to-end 402 payment loop test against a stub facilitator #490 — the end-to-end 402 loop test (No test drives a real 402 payment loop #423).

Please do not all rebase at once. If you are below the one currently in flight, wait until the one above you lands — otherwise you rebase, I merge someone else, and you rebase again. I will comment on your PR when it is your turn.

One thing to settle between you: src/mcp/codes.ts is being extended by at least four of these, and #488 has already added a separate set of refusal reasons in src/net/ssrf.ts. We should end up with one vocabulary for "I refused to do that", not four. Whoever lands next, please look at what is already there and extend it rather than adding a parallel set — and say in your PR description what you added, so the next person can see it without reading the diff.

Nothing here reflects on the quality of the work. Several of these are among the best PRs this repo has had.

[Miracle656]

Screened against current main and this does not pass on its own branch, so a rebase alone will not fix it.

Merged alone it gives type errors against main. Run npx tsc --noEmit on a fresh rebase and you will see them.

Please rebase, get npx tsc --noEmit and npx vitest run both clean locally, and re-request. I would rather take this than not — it is held on correctness, not on wanting it.

[Miracle656]

The design is right and I want this in. It needs a rebase, because the screener was extracted on main in the week since you branched — differently from how you extracted it here, and in the same file.

The principle is the one I'd have asked for

 * `lens_screen_pairs` — over the exact implementations the REST routes use
 * (`listPairs`, `listPools`, `screenPairs`), so a page from a tool is a page

That is exactly right, and it is the thing MCP tool PRs usually get wrong: re-querying the database from the tool layer, so lens_screen_pairs and GET /screener slowly stop agreeing about what sortBy=liquidity or limit=500 means. Routing the tools through the same functions means there is one answer and one place to fix it.

Pulling /pools out of src/api/rest.ts into src/routes/pools.ts is also a genuine improvement independent of the tools — rest.ts has been a grab-bag for a while.

What changed under you

main now has src/services/screener.ts, exporting runScreener. It arrived with the GraphQL screener query (#609), which needed the same thing you need: one implementation behind more than one surface. src/routes/screener.ts is now a thin handler that validates with a Zod schema and calls it:

return await runScreener({ network, filters, sortBy, order, cursor, limit })

Your branch extracts the same logic as screenPairs inside src/routes/screener.ts. So we have two extractions of one query, and git cannot reconcile them — merging main gives 266 conflicted lines across three regions in that file alone.

I stopped there rather than picking a winner by hand. This is the query behind published volume and ranking numbers, and a merge I resolve by choosing between two restructurings is exactly where a subtle wrong answer hides. You know what you intended; I would be guessing.

What the rebase needs

1. Drop the screenPairs extraction. src/routes/screener.ts on main is already thin — leave it alone.
2. Point lensTools.ts at the service: import { runScreener } from '../services/screener'. Note it is src/services/, not src/routes/.
3. Check the argument shape. You currently go through stringifyScreenerArgs because the route parsed strings. runScreener takes typed values — { network, filters: { volume, change_24h_min, ... }, sortBy, order, cursor, limit } — so the MCP tool can pass numbers straight through and that helper can go. The route still stringifies only because query parameters arrive as strings; a tool's arguments do not.
4. Keep listPairs and listPools. Neither exists on main — /pools is still inline in rest.ts and pairs.ts exports no listPairs — so those extractions are yours and conflict with nothing conceptually.
5. src/mcp/server.ts and src/api/rest.ts have one conflict region each, both small.

Two things worth knowing that landed while you were out, because they affect the tool surface:

• Limit clamping lives in runScreener, not the route: Math.min(SCREENER_MAX_LIMIT, Math.max(1, limit ?? SCREENER_DEFAULT_LIMIT)). Pass limit through and the tool is clamped identically to REST and GraphQL for free. Do not re-clamp in the tool — one clamp or they drift.
• sortBy and order are allow-listed inside the service before being interpolated into the SQL, since a column name cannot be a bind parameter. That protection is in runScreener, so going through it is also what keeps the tool from becoming an injection surface. Worth a test asserting lens_screen_pairs with sortBy: "price; DROP TABLE" is refused rather than passed along.

After the rebase: npx tsc --noEmit, npm test, and if you touch openapi.yaml at all, npm run openapi:gen plus npx --yes openapi-typescript@7.13.0 openapi.yaml -o clients/typescript/src/schema.d.ts — both are byte-compared in CI now.

---

Separately: #423 is closed and credited to you. You were right that the work was already on main — it went in with #487 (94bd8ea), which is why #490's branch was empty after the rebase. I checked it rather than taking it on trust, and the sigValidOnMainnet: false assertion in that test is the best thing in it; details on the issue.

[Miracle656]

Scanned clean. The design is right and better than I expected from the last round — I want to lead with that because the blocker here is entirely the base.

What you got right

screenPairs is a shared function that the route and lens_screen_pairs both call, so the MCP tool cannot drift from the HTTP surface. And it validates inside itself:

const sortBy = q.sortBy ?? 'volume'
if (!allowedSortFields.includes(sortBy)) {
  return { ok: false, error: `sortBy must be one of: ${allowedSortFields.join(', ')}` }
}

That is the correct place for it. A column name cannot be a bind parameter, so the allow-list is the only thing standing between sortBy and the SQL — and putting it in the shared function rather than in the route's zod schema is what stops the MCP path from being an injection surface the HTTP path is not. That was my main worry last time and you closed it properly.

The blocker: the branch is 306 commits behind main

$ git diff --shortstat origin/main L482 -- src
184 files changed, 1918 insertions(+), 29327 deletions(-)

Twenty-nine thousand lines of deletions. Not conflicts — deletions, because the branch predates the files. Among them:

Deleted	Lines
src/__tests__/auth.test.ts	741
src/ingest/venues/blend.ts	661
src/__tests__/phoenixIngester.test.ts	657
src/ingest/venues/phoenix.ts	581
src/__tests__/vwap.test.ts	483

Two entire venue ingesters, the auth test suite, and much more. Merging this would undo months of work.

A rebase across 306 commits is genuinely unpleasant, and I would not blame you for starting a fresh branch from current main and moving your four files onto it — src/mcp/lensTools.ts, src/routes/pools.ts, and your changes to src/routes/pairs.ts and src/routes/screener.ts. The diff would be a tenth the size and far easier for both of us.

One thing to reconcile when you do

main has src/services/screener.ts with runScreener, which the REST route and the GraphQL screener query both use, and which carries its own ALLOWED_SORT_FIELDS and limit clamping. Your screenPairs is a second implementation of the same thing. Two screeners that both work is worse than one, because they drift silently — a filter fixed in one is wrong in the other for months before anyone notices.

Please fold the MCP tool onto runScreener rather than keeping screenPairs. You lose nothing: it already validates sortBy, it already clamps limit to [1, SCREENER_MAX_LIMIT], and going through it means your tool, the REST route and GraphQL answer identically by construction. If runScreener is missing something your tool needs, add it there and all three consumers get it.

A test asserting lens_screen_pairs with sortBy: "price; DROP TABLE users" is refused would be worth keeping either way — you have the guard, and that is the test that proves it stays.

main is green right now (tsc clean, 1,755 tests), so anything tsc or vitest reports after the rebase is yours.

https://claude.ai/code/session_01USgemLt4Rnz4SGB1Srf3GB

[Miracle656]

Correction to my earlier review.

I said this branch would delete 29,327 lines including both venue ingesters and the auth test suite. That was wrong, and the method was the problem: git diff origin/main L482 compares the two tips, so everything main gained since you branched looked like a deletion on your side. A merge does not do that — it keeps files main added that your branch never touched.

Measured properly:

conflicts: 3  (src/api/rest.ts, src/mcp/server.ts, src/routes/pairs.ts)
files a merge would delete: 0

blend.ts, phoenix.ts and auth.test.ts all survive. Three conflicts is an ordinary rebase, not the rewrite I described. Sorry for that.

What I said about the code stands and is the part worth your time: screenPairs validating sortBy inside the shared function is right, and folding the MCP tool onto main's runScreener would stop the REST, GraphQL and MCP screeners drifting apart.

https://claude.ai/code/session_01USgemLt4Rnz4SGB1Srf3GB

[Miracle656]

Merged as-is — no changes needed.

Verified locally on a real merge into main: 0 files deleted, tsc --noEmit clean, and the full suite green at 1891 passed / 1 skipped across 156 files.

What made this easy to accept is that the three tools are built from the same functions the REST routes call — listPairs, listPools, runScreener — so MCP is a different transport rather than a second implementation that can drift. No new SQL, nothing to keep in sync. /pools also kept its scope: read:prices through the move into src/routes/pools.ts.

Sorry again for the bogus "deletes thousands of lines" note earlier in this PR — that was my two-dot diff mistake, not anything in your branch.