TRENCH MCP

Live: trenchmcp.lol
Created by: @fluixoo

Check liquidity before you trust the number.

TRENCH gives an AI agent observed Robinhood Chain pool data and a transparent, position-size-aware pressure model. The agent gets evidence to explain вЂ” not a made-up executable quote.

Open the terminal В· Connect your agent В· Read the assumptions

Public site

Open TRENCH в†’ trenchmcp.lol

Use the browser terminal without installing anything. Paste a Robinhood Chain token contract, enter a USD position size, and inspect public pool data alongside a transparent exit-pressure model.

Compare four independent position-size scenarios вЂ” 10%, 25%, 50% and 100% вЂ” then export the observation as JSON or Markdown. Source references, observation time and model assumptions stay beside the result.

Want to use TRENCH from an AI client? The agent connection guide explains how to connect to the hosted MCP endpoint or run the server locally.

No wallet connection, private keys, signatures or transactions. The synthetic demo is separately labeled; a failed live request is not silently replaced with demo data.

Results are model estimates, not executable sell quotes or token-safety verdicts. Pool data and the RPC block are separate observations, not an atomic block-pinned snapshot.

Understand it in 20 seconds

Question	Answer
What does it do?	Reads token pools and models how a USD position size changes estimated exit pressure.
Where is the AI?	Your MCP-compatible AI client calls the tools and interprets their structured results. The pressure calculation is deterministic.
Can I try it immediately?	Yes. Paste a Robinhood Chain token address and a USD position size, or load the separately labeled synthetic demo. No account or wallet connection.
Where does live data happen?	The hosted server reads DexScreener pools and Robinhood Chain RPC for both the browser terminal and MCP clients. Demo mode uses manual inputs.
Does it execute trades?	No signing, approvals, swaps or custody. It does not look up your wallet balance.
Is the result a quote?	No. It is a disclosed constant-product proxy, not a complete Uniswap v4 execution simulation.

TRENCH research desk displaying a clearly labeled synthetic example

The problem

AI agents can summarize token pages, read contracts and repeat social posts. That does not answer the operational question a trader actually has:

If this position had to exit now, what does the visible market structure suggest?

Raw liquidity alone is not enough. A $50K position and a $500 position do not face the same market. TRENCH collects the token, position size, observed primary pool, RPC block and an explicit pressure model in one structured MCP result. Pool data and RPC block reads are separate observations, not an atomic block-pinned snapshot.

What TRENCH is

TRENCH is a real, local-first MCP server for Claude, Codex and any compatible client. It exposes five read-only tools backed by current Robinhood Chain RPC and pool observations.

It does not trade. It does not accept private keys. It does not pretend a constant-product model is an executable quote.

user question
     в”‚
     в–ј
AI agent в”Ђв”ЂMCP/HTTP or stdioв”Ђв”Ђв–є TRENCH
                         в”њв”Ђв”Ђ Robinhood Chain RPC: chain + block
                         в”њв”Ђв”Ђ DexScreener: pools + liquidity + volume
                         в””в”Ђв”Ђ SLIP engine: size-aware pressure model
                                      в”‚
                                      в–ј
                           evidence + grade + limits

Run it now

Requirements: Node.js 22+.

npx --yes github:Floopi10/trench-mcp

Or install locally:

git clone https://github.com/Floopi10/trench-mcp.git
cd trench-mcp
npm ci
npm start

Connect your agent

Remote HTTPS вЂ” no local installation

Add this URL to a client supporting MCP Streamable HTTP:

https://trench-mcp.mytodofloopi.workers.dev/mcp

No authentication is required for these public read-only tools. Start with chain_health, then ask for inspect_token using a public token address. The separate Terminal calls the hosted analysis API. Its Demo mode stays synthetic. MCP clients use the endpoint above.

The hosted endpoint is rate limited (per-IP, best effort), limits request bodies to 16 KiB, validates browser origins, and only queries configured public data providers. It does not accept arbitrary RPC URLs or credentials from callers. Availability and provider coverage are not guaranteed. Do not send secrets.

Local stdio

After installing locally, add it to an MCP-compatible client:

{
  "mcpServers": {
    "trench": {
      "command": "node",
      "args": ["/absolute/path/to/trench-mcp/bin/trench-mcp.mjs"]
    }
  }
}

Windows example:

{
  "mcpServers": {
    "trench": {
      "command": "node",
      "args": ["C:\\tools\\trench-mcp\\bin\\trench-mcp.mjs"]
    }
  }
}

Tool surface

`inspect_token`

Reads the strongest visible Robinhood Chain pool for a token and returns price, liquidity, 24-hour volume, activity, pool count and a small-position pressure grade.

{ "token": "0x0000000000000000000000000000000000000000" }

`simulate_exit`

Models a specific USD exit size against estimated quote-side depth. The result includes the DEEP, THIN or CRITICAL grade, estimated receive, pressure percentage and suggested chunks.

{
  "token": "0x0000000000000000000000000000000000000000",
  "sizeUsd": 2500
}

`compare_exit_sizes`

Compares up to eight position sizes against the same market observation, preventing time drift between scenarios.

{
  "token": "0x0000000000000000000000000000000000000000",
  "sizesUsd": [100, 500, 2500, 10000]
}

`chain_health`

Returns chain ID, latest block, public RPC URL and observed round-trip latency.

{}

`explain_exit_signal`

Packages the deterministic grade into evidence, limitations and concrete next checks so the host AI can explain a result without inventing a story.

How the pressure model works

TRENCH uses the highest-liquidity observed pool and approximates quote-side depth as half of total pool liquidity. After a configurable fee assumption, it applies constant-product movement to estimate how much pressure a position introduces.

quote_depth = pool_liquidity / 2
after_fee   = size Г— (1 - fee_rate)
receive     = quote_depth Г— after_fee / (quote_depth + after_fee)
impact      = 1 - receive / after_fee

Current grade rules:

Grade	Rule	Meaning
`CRITICAL`	liquidity below `$10K`, or size above `8%` of estimated quote depth	visible depth is highly constrained
`THIN`	size above `2%` of quote depth, or 24h turnover below `5%`	exit pressure deserves caution
`DEEP`	none of the walls above are crossed	position is small relative to the observed depth

These are transparent product rules, not predictions. Read MODEL.md for assumptions and failure modes.

Agent behavior contract

TRENCH returns facts and boundaries together. A good agent should:

State the observation time and available RPC block; do not imply the pool was read at that exact block.
Name the selected pool and visible liquidity.
Tie the grade to the requested position size.
Label modeled impact as a proxy.
Recommend checking an executable venue quote before action.

A bad agent hides timestamps, calls the proxy guaranteed output, or converts a grade into financial advice.

Security boundary

Every MCP capability is annotated read-only.
EVM addresses and USD sizes are strictly validated.
Position size is capped at $10,000,000.
Network requests time out after eight seconds.
No secrets are accepted, logged or persisted.
No wallet connection, signing, approval, swap or custody code exists.
Diagnostics use stderr so stdout remains valid MCP framing.

See SECURITY.md for the threat model.

Documentation

Development

npm ci
npm run check
npm run inspect

npm run check validates syntax and runs unit plus real stdio MCP integration tests. npm run inspect opens the official MCP Inspector.

Current scope

Version 0.1.0 intentionally does one job well: convert current market structure into evidence an AI agent can inspect and explain. Historical monitoring, deployer tracing and executable venue routing are not implemented. They will not be implied in copy until they exist and can be verified.

Mascot

Trench is a terminal-green chibi axolotl carrying a market scanner. The axolotl fits the product: it stays calm in hostile environments, sees what is happening below the surface and does not press the trade button for you.

Pixel field notes

The main mascot stays a terminal-green pixel axolotl. These companion illustrations add personality without turning the product interface into a toy.

Builder
Check the inputs. Read the source.

Diver
Look below the headline number.

What is tested

npm run check runs syntax checks and the test suite, including real stdio MCP integration tests, 108 synthetic browser/server model comparisons, HTTP MCP integration, origin checks, body limits and rate-limit checks.

Tests verify implementation behavior. They do not certify a token, guarantee provider availability, or make the modeled proceeds executable. Live results can change between requests.

License

MIT

Browser research desk

The terminal has live token input and a separate synthetic demo. It shows pool liquidity, volume, modeled depth, four independent position-size scenarios (10/25/50/100%), a receive curve, observation evidence and downloadable JSON/Markdown receipts. These are research estimates, not orders or contract-safety scores.

POST https://trench-mcp.mytodofloopi.workers.dev/api/analyze

Body: {"token":"<public EVM token address>","sizeUsd":5000}. Only these two fields are accepted. Uses the same analyzeExit engine as MCP. Browser queries leave your device for the hosted server and public providers; never submit secrets.

Origin validation, 16 KiB body limits and the shared 60 requests/minute per-IP best-effort limiter apply. Invalid input returns 400, no liquid pool 404, rate limiting 429, and provider failures 502. Errors never fall back silently to demo data. Results are snapshots, not an automatic live stream. Changing inputs invalidates the visible receipt; rerun to fetch new data.

The session console supports help, demo, analyze <token> <USD size> and clear. It is not a shell, wallet or trading bot. Activity is real session activity and is kept in memory only.

Market discovery feed

The homepage reads GET /api/markets from the hosted worker. It samples DexScreener search results for robinhood WETH, filters to Robinhood Chain EVM tokens with positive reported pool liquidity, deduplicates by CA using the largest observed pool, and returns up to 24 tokens. This is not a complete launch index, a safety ranking or a trade feed.

The compact scanner shows six rows immediately, then reveals remaining rows at one per second; snapshots refresh every 30 seconds without clearing existing rows. The server caches successful samples for 30 seconds, coalesces concurrent fetches, limits upstream requests to eight seconds and applies a 15-second failure cooldown. Per-IP service rate limits still apply. Errors are explicit; no synthetic tokens are substituted. On an upstream failure, a previously fetched server snapshot may be returned for up to five minutes with stale: true and its original timestamp. The browser marks retained rows as stale and removes them when they expire. Cold-start failures show a compact retry state and a manual CA input instead of an empty grid.

Analyze $1,000 opens the browser terminal and runs the existing read-only pressure model for the selected CA. Ask your agent opens MCP setup with an address-specific prompt to copy into your connected AI client. There is no embedded LLM, trading permission or automatic purchase.

AI-assisted development

Implemented with OpenAI Codex assistance. AI-authored changes are credited in commit metadata. This is an independent project, not an OpenAI product, partnership or endorsement.