README.md•3.16 kB
# Joke MCP Server
A lightweight Model Context Protocol (MCP) companion that serves short jokes to developers while tasks are processed. Designed for Node.js 18+ with airtight offline defaults and fast fallbacks.
## Quick Start
- `npm install` – install dependencies (TypeScript, linting, Vitest).
- `npm test` – run offline unit + e2e suites (no network requests).
- `npm run dev` – launch the server with tsx; type `health` or `getJoke {"category":"programming"}` on stdin.
- `npm run build && npm start` – compile to `dist/` and run the production bundle.
- `npm run dev:worker` – start the Cloudflare Worker MCP locally via Wrangler dev (HTTP interface).
## Environment Variables
| Variable | Description | Default |
| --- | --- | --- |
| `JOKE_API` | Primary provider (`jokeapi` or `official`). | `jokeapi` |
| `JOKE_DEFAULT_CATEGORY` | Fallback category when input omits one. | `programming` |
| `JOKE_LANG` | Default language (currently `en` or `zh`). | `en` |
| `TIMEOUT_MS` | Per-request HTTP timeout in ms. | `2000` |
| `RETRIES` | Retry attempts with exponential backoff. | `2` |
| `ALLOW_NET` | Opt-in for live HTTP calls (`true` to enable). | `false` |
| `LOG_VERBOSE` | Emit provider diagnostics to `stderr`. | `false` |
## Usage Examples
```bash
# Health check
printf 'health\n' | npm run dev --silent
# Category + language request
printf 'getJoke {"category":"programming","lang":"en"}\n' | npm run dev --silent
# Development helper
./scripts/dev.sh 'getJoke {"lang":"zh"}'
```
## Testing
- Offline suite: `npm test`
- Live integration (opt-in): `npm run test:online` with `ALLOW_NET=true`
- Tests mock network providers by default; CLI I/O is covered in `tests/integration/cli.test.ts`, HTTP Worker coverage in `tests/integration/worker.test.ts`, and fallback behaviour in `tests/e2e/offline.test.ts`.
## Cloudflare Worker (HTTP MCP)
- Configure `wrangler.toml` (included) and set secrets/env vars with `wrangler secret put` if needed.
- Dev server: `npm run dev:worker` (serves on `http://127.0.0.1:4242` by default).
- Deploy: `wrangler deploy` (requires Cloudflare account credentials).
- Endpoints:
- `GET /health` → `{ ok: true }`
- `POST /getJoke` with JSON body matching CLI payloads.
## Codex MCP Configuration
```toml
[mcp_servers.jokes]
command = "node"
args = ["./dist/interfaces/cli.js"]
env = { JOKE_API = "jokeapi", JOKE_DEFAULT_CATEGORY = "programming", JOKE_LANG = "en", TIMEOUT_MS = "2000", RETRIES = "2" }
startup_timeout_ms = 20000
```
## Project Layout
- `src/interfaces/cli.ts` – MCP stdin/stdout adapter wrapping the agent.
- `src/agents/jokes-mcp.agent.ts` – provider orchestration, fallback policy, structured logging hooks.
- `src/providers/` – Joke providers (`jokeapi`, `official`, `local`) plus shared fetch helper.
- `data/jokes/local-jokes.json` – curated bilingual fallback pool (20 jokes, categorized).
- `src/interfaces/cloudflare/worker.ts` – Cloudflare Worker entry that exposes the HTTP MCP endpoints.
- `tests/` – unit, CLI/HTTP integration, offline e2e, and opt-in live coverage.
- `docs/integration-guide.md` – playbook for wiring jokes into wait-period workflows.