Skip to content

moonlight-lupin/agent-skills / research/endpoint-probe

endpoint-probe

Flagged

Use when you need to discover an API's surface — poke a base URL to find its type (REST, GraphQL, SOAP, JSON-RPC), auth scheme, available endpoints, rate limits, and CORS policy. Also probes MCP servers (HTTP and stdio) to discover tools, resources, and prompts with full input schemas. Runs a Python probe script that checks well-known discovery paths (OpenAPI/Swagger, GraphQL introspection, health, .well-known), fingerprints the server, sends OPTIONS for CORS, detects auth from 401/403 responses, and guesses common REST resources. For MCP, performs JSON-RPC initialize handshake then tools/list, resources/list, prompts/list. Feed it a base URL or MCP server URL, optionally with auth credentials.

references/interpretation-guide.md

View on GitHub
# Interpretation Guide

Patterns observed from testing against real APIs: GitHub, Petstore Swagger, OpenRouter, OpenCode, Composio MCP, AlphaVantage MCP, library-rag MCP.

## Status Code Patterns

| Pattern | Meaning | Example |
|---|---|---|
| All 404 | API not at this URL, or auth-gated with 404-hiding | GitHub `/api/v1` base |
| All 403 + same body | Rate-limited, not auth-blocked | GitHub unauthenticated (60/60 used) |
| Mixed 200/401/403 | True auth-gated API — some paths open, some protected | Typical REST API |
| 406 Not Acceptable | MCP server needs `Accept: application/json, text/event-stream` | Composio MCP before fix |
| 401 + `WWW-Authenticate: Bearer` | OAuth2/JWT auth required | Standard OAuth2 API |
| 200 + `text/html` for every path | SPA catch-all (Next.js, Nuxt) — not real API responses | OpenRouter domain root |

## OpenAI-Compatible Inference Prefixes

If probing `https://provider.ai/v1` returns nothing, the OpenAPI spec is at the domain root (`https://provider.ai`). The `/v1` prefix is just the inference slice (`/v1/chat/completions`, `/v1/models`). Always probe the domain root.

**Tested:** OpenCode (`opencode.ai/zen/go/v1` → empty; `opencode.ai` → 188 endpoints)

## SPA Catch-All Detection

Next.js/Nuxt/SPA frameworks serve the same HTML shell for every path. Signs:
- Server fingerprint shows Next.js/Nuxt
- Most discovery paths return 200 + `text/html` with similar body lengths (±200 bytes)
- REST resource guessing returns 200 for every path

The script auto-detects this in REST resource guessing (uniform 200 + text/html + similar body lengths → discarded) and SOAP detection (WSDL returning text/html → not SOAP). Discovery paths may still show many `html-docs` entries — these are SPA routes, not real docs.

**Tested:** OpenRouter (Next.js + Cloudflare, 45 discovery paths all 200 text/html)

## MCP Transport Quirks

### StreamableHTTP (protocol 2025-06-18)
- Requires `Accept: application/json, text/event-stream` header
- May respond with SSE format (`data: {...}\n\n`) instead of plain JSON
- Composio returns SSE; AlphaVantage returns plain JSON — both work with the probe's SSE parser

### Stdio
- Server reads JSON-RPC from stdin, writes to stdout (newline-delimited)
- Read timeout via `select()` with `--timeout` deadline — no hang on silent servers
- Server→client notifications (no `id`) are discarded; response `id` is correlated
- Subprocess cleanup via `try/finally` with `_cleanup_subprocess` — always terminates even on exception
- Environment: scrubbed `os.environ` inherit — safe vars only (`PATH`, `HOME`, `USER`, `LANG`, `LC_*`, `TERM`, `SHELL`, `XDG_*`); secrets stripped by substring match (`TOKEN`, `API_KEY`, `PASSWORD`, etc.)
- Command allowlist: only `npx`, `uvx`, `python3`, `python`, `node`, `bunx` — no arbitrary paths, no `-c`/`-e`/`-p`/`--call`/`--eval`/`--exec`/`--print` inline code flags
- Body capped at 5 MiB to prevent memory DoS
- `pid` and `returncode` recorded in report for verification

### Protocol version negotiation
- Probe sends `2025-06-18` (latest). Server returns its supported version.
- AlphaVantage returned `2024-11-05` (older) — worked fine, probe reports the negotiated version.

## Performance Benchmarks

| Target | Mode | Time | Notes |
|---|---|---|---|
| Petstore Swagger | `--no-guess` | ~2s | OpenAPI found immediately |
| Petstore Swagger | Full probe | ~34s | Resource guessing adds time |
| GitHub API | Full probe | ~1.7s | Rate-limited, skipped guessing |
| OpenRouter | Full probe | ~3s | SPA detected, filtered |
| Composio MCP | `--mcp` | ~2s | SSE response parsed, 7 meta-tools (search/execute pattern) |
| AlphaVantage MCP | `--mcp` | ~5s | 129 tools, plain JSON, protocol 2024-11-05 |
| library-rag MCP | `--mcp-stdio` | ~3s | Subprocess launch + handshake, 3 tools with full schemas |

## Composio MCP Meta-Tool Pattern

Composio is a **meta-tool server** — instead of exposing 500+ individual app integrations, it exposes 7 orchestration tools that let you search for and execute any app integration dynamically. This is a different architecture from AlphaVantage (direct tools) or library-rag (direct tools).

Key tools: `COMPOSIO_SEARCH_TOOLS` (search by natural language → returns tool slugs + execution plans + pitfalls), `COMPOSIO_MULTI_EXECUTE_TOOL` (parallel execution), `COMPOSIO_GET_TOOL_SCHEMAS` (retrieve schemas by slug).

When probing a meta-tool server, the tool count will be low (7) but each tool is a gateway to hundreds of underlying integrations. The real surface is discovered at runtime via `COMPOSIO_SEARCH_TOOLS`, not at handshake time.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall