README.md•2.24 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 (Mitigated footprint: vitest only).
- `npm test` – run offline unit + e2e suites (no network requests).
- `node src/jokes-mcp.js` – launch the server; type `health` or `getJoke {"category":"programming"}` on stdin.
## 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' | node src/jokes-mcp.js
# Category + language request
printf 'getJoke {"category":"programming","lang":"en"}\n' | node src/jokes-mcp.js
# 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; local fallback is validated in `tests/e2e/offline.test.js`.
## Codex MCP Configuration
```toml
[mcp_servers.jokes]
command = "node"
args = ["./src/jokes-mcp.js"]
env = { JOKE_API = "jokeapi", JOKE_DEFAULT_CATEGORY = "programming", JOKE_LANG = "en", TIMEOUT_MS = "2000", RETRIES = "2" }
startup_timeout_ms = 20000
```
## Project Layout
- `src/jokes-mcp.js` – MCP stdin loop, provider orchestration, structured logging.
- `src/providers/` – Joke providers (`jokeapi`, `official`, `local`) plus shared fetch helper.
- `local-jokes.json` – curated bilingual fallback pool (20 jokes, categorized).
- `tests/` – unit, offline e2e, and opt-in integration coverage.
- `docs/integration-guide.md` – playbook for wiring jokes into wait-period workflows.