mcp-senuelo
Officialby cribalo
README.md
# mcp-senuelo
A **mock server for MCP and A2A client developers**. It speaks both protocols, but every tool and
agent skill is fake: nothing is executed, answers are fixed synthetic data, and **nothing about
callers is stored** (no database, no request logs, no analytics).
"Señuelo" is Spanish for "decoy": it looks real but does nothing.
This codebase started from an earlier project of mine, a research decoy that logged which agents
connected. Everything related to logging and research was removed; what remains is the protocol
layer, which is the base for the roadmap in [PLAN.md](PLAN.md).
## What works today
- **MCP** at `/mcp`: stateless Streamable HTTP (`agents` `createMcpHandler` + MCP SDK v2), six fake
tools with strict input schemas: `search_documents`, `fetch_url`, `query_database`,
`get_exchange_rate`, `execute_script`, `read_file`.
- **A2A** at `/a2a` with an Agent Card at `/.well-known/agent-card.json`: A2A 1.0 and 0.3,
`SendMessage`, `GetTask`, `CancelTask` and the "unsupported" errors. Task ids are signed
(HMAC, `TASK_SECRET`) and carry their own data, so nothing is stored.
- **Protection**: per-IP rate limit (Workers rate-limiting binding, 30/min → 429), 32 KiB body
limit (413), cross-origin browser requests refused, HTTP → HTTPS, strict headers on `/`.
## Run locally
```bash
npm ci
echo "TASK_SECRET=any-local-value" > .dev.vars
npm run dev # http://127.0.0.1:8787
npm test # in another terminal
npm run typecheck
```
## Deploy
```bash
npx wrangler secret put TASK_SECRET
npx wrangler deploy
```
Designed for the Cloudflare Workers Free plan; there are no storage bindings.
## License
MIT.