feat(mcp): harden keys, env drift guard, rate limiting, and resources (#412, #413, #417, #418)

[sparkysolutions10-pixel]

Summary

This PR addresses four related MCP server hardening issues (#412, #413, #417, #418) to ensure safe network configuration, complete documentation & drift protection, rate limiting defense, and direct MCP resource exploration:

1. Independent Testnet Startup & Opt-In Mainnet Key Signing (Running on testnet requires a mainnet key #412 - 100 pts):

   • In examples/mcp-server/run.ts, decouple testnet from mainnet requirements. The server starts with only MCP_AGENT_SECRET_KEY_TESTNET configured.
   • Mainnet key usage requires explicit opt-in via MCP_ENABLE_MAINNET=true and announces loudly at startup: [mcp-server] WARNING: stellar:pubnet is enabled with live funds!.
   • If no keys are provided, the server starts safely in read-only mode, and paid_call returns a structured ERR_MISSING_KEY error naming the required network without failing process startup.
   • Key values are strictly never logged.

2. Environment Drift Guard Extension & Full MCP Documentation (The MCP environment variables escape the drift guard #413 - 100 pts):

   • Extended src/__tests__/envDrift.test.ts to scan both examples/ and scripts/ directories in addition to src/.
   • Documented all MCP variables (MCP_AGENT_SECRET_KEY_TESTNET, MCP_AGENT_SECRET_KEY_MAINNET, MCP_ENABLE_MAINNET, MCP_MAX_PAYMENT_PRICE, MCP_MAX_CONCURRENCY, MCP_RATE_LIMIT_PAID_CALL, MCP_RATE_LIMIT_BAZAAR_SEARCH) and missing oracle relay variables (ORACLE_RELAY_RPC_URL, ORACLE_RELAY_NETWORK_PASSPHRASE) in .env.example.
   • Added an explicit test in envDrift.test.ts proving that undocumented environment variable reads in examples/ fail CI.

3. In-Flight Concurrency Capping & Per-Tool Rate Limiting (Nothing limits how fast an agent can call #417 - 150 pts):

   • Added in-flight concurrency limiter to BazaarMcpServer (maxConcurrency: 5 by default) that rejects concurrent bursts with structured ERR_CONCURRENCY_LIMIT_EXCEEDED and retry hint.
   • Added configurable sliding-window rate limits per tool (defaulting to 10 req/min for paid_call, 30 req/min for bazaar_search) returning structured ERR_RATE_LIMITED with honest retryAfterSeconds.
   • Exported Prometheus counter mcp_rate_limit_rejections_total labeled by tool and reason (rate_limit vs concurrency).

4. MCP Resource Capability & Static Data Exposure (The server advertises only tools, not resources #418 - 150 pts):

   • Declared resources: {} in server capabilities.
   • Implemented ListResourcesRequestSchema exposing lens://pairs, lens://venues, lens://openapi, and lens://status.
   • Implemented ReadResourceRequestSchema returning accurate JSON content, application/json MIME type, and honest freshness metadata (_meta.version, _meta.lastModified).

Closes

• Closes Running on testnet requires a mainnet key #412
• Closes The MCP environment variables escape the drift guard #413
• Closes Nothing limits how fast an agent can call #417
• Closes The server advertises only tools, not resources #418

Verification

• npx vitest run tests/mcp.test.ts src/__tests__/envDrift.test.ts (17/17 tests passing)
• npx tsc --noEmit (0 errors)
• npm run build (build succeeds)

[Miracle656]

Changes requested: one issue per PR, and only issues assigned to you

This is a process requirement, applied to all 23 of your open PRs in this repo. It is not a judgement about the code, which I have not been able to review — and that is the first half of the problem.

The bundling

Across your open PRs, 150 distinct issues are claimed. This one claims several. #483 claims 22, #481 claims 20, #477 claims 20, #474 claims 20.

A PR that closes twenty issues cannot be reviewed. Each of those issues has its own acceptance criteria — typically five — so twenty issues is a hundred separate things to verify in one diff, and if any one of them is wrong the whole PR is blocked while it is fixed. Every batch I published says the issues are deliberately independent so they can be worked in parallel, by different people, without colliding. Bundling them removes exactly that property.

The assignments

135 of the 150 issues claimed are assigned to other contributors — 67 different people.

This PR is an example: it names issues currently assigned to other contributors who are working on them now. Several have open PRs of their own. If this merged as it stands, those people would have done the work and received nothing for it, and I would have no way to tell the two efforts apart.

I am not assuming anything about why. Assignments change, Drips and GitHub can disagree, and a wide-ranging branch picks up issue numbers easily. But the effect on the people holding those assignments is the same regardless of intent, which is why I have to act on it.

What I need

• One issue per PR. The issue number in the title, its acceptance criteria met, and nothing else in the diff.
• Only issues assigned to you, or unassigned ones you have claimed through Drips. If an issue is assigned to someone else, it is theirs.
• Re-open the work that meets both conditions as individual PRs. I will review them in the order they arrive and at the same pace as everyone else's.

Nothing is being closed. These stay open and are yours to re-cut, withdraw or split as you choose.

Two things worth knowing before you re-cut

Some of this has already landed. #488 (SSRF guard for bazaar_search) and #487 (the paid_call host allow-list) cover the same ground as your #449; #486 covers the MCP README. Check current main before rebuilding something that is already there.

main has moved a long way today — #306, #309, #252, #256, #355, #381, #390, #402, #476, #488 and more. Cut from current main, not from where these branches started.

If you believe an issue named here is genuinely yours, say which and I will check the assignment myself — I would rather be corrected than have someone lose work.