Skip to main content
Glama
mcp-senuelo

mcp-senuelo

Official
by 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.