Coffee Mate MCP Server
A TypeScript MCP (Model Context Protocol) server that serves coffee data. Originally based on the Medium article A Quick Step-by-Step Guide to Writing an MCP Server in TypeScript by Perry George. Supports both Streamable HTTP and stdio transports.
Prerequisites
- Node.js 24+
- npm
- Docker (optional, for containerized deployment)
Setup```bash
npm install
npm run build
### Docker
Multi-stage build: `builder` stage compiles TypeScript, `runner` stage copies only production dependencies and compiled output. Non-root `app` user. `HEALTHCHECK` via `wget` against `/health`.```bash
docker build -t coffee-mate-mcp .
docker run -p 3001:3001 coffee-mate-mcp
Override environment variables at runtime:```bash
docker run -p 8080:8080 -e PORT=8080 -e ACTIVE_TOOLS="get-coffees" coffee-mate-mcp
## Running
**HTTP mode (default)** — starts a raw Node.js Streamable HTTP server:```bash
node build/app/main.js
# MCP Server running on http://0.0.0.0:3001
Set the PORT environment variable to change the port (default 3001).
stdio mode — for local VS Code integration:```bash
node build/app/main.js --stdio
MCP Server running on stdio
## Environment Variables
| Variable | Type | Default | Description |
| ---------------- | ------ | --------------- | ---------------------------------------------------- |
| `PORT` | number | `3001` | HTTP server port |
| `TRANSPORT_MODE` | string | `"http"` | `"http"` or `"stdio"` |
| `SERVER_NAME` | string | `"coffee-mate"` | MCP server identity |
| `SERVER_VERSION` | string | `"1.0.0"` | Semver version |
| `ACTIVE_TOOLS` | string | `""` | Comma-separated tool names to register (empty = all) |
## API Endpoints
| Endpoint | Method | Description |
| --------- | ------ | ----------------------------------------------------------- |
| `/health` | GET | Healthcheck — returns `{ "status": "ok" }` |
| `/mcp` | POST | MCP JSON-RPC message handler (initialize creates a session) |
| `/mcp` | GET | SSE backward-compatibility stream |
| `/mcp` | DELETE | Explicit session termination |
## MCP Tools
| Tool | Description | Parameters |
| -------------- | -------------------------------------------- | --------------- |
| `get-coffees` | Returns a list of all coffees | None |
| `get-a-coffee` | Retrieves data for a specific coffee by name | `name` (string) |
## Connecting to VS Code
The project includes a `.vscode/mcp.json` config that uses stdio mode. Open the workspace in VS Code, start the MCP server from the config file, and use the tools via GitHub Copilot in Agent mode.
## Docker Networking (n8n integration)
When running inside the `first-n8n` Docker Compose stack, this server is available to other containers at `http://coffee-mate-mcp:3001/mcp` on the `demo` network. See the `first-n8n` project for the full stack setup.
## CI/CD
GitHub Actions workflow (`.github/workflows/deploy.yml`):
- **`ci` job**: Runs `build` → `lint:ts` → `test` on all branches and pull requests targeting `main`
- **`deploy` job**: Builds Docker image, pushes to Azure Container Registry, deploys to Azure Container Apps. Gated to `main` push only
## API Documentation
TypeScript API docs are generated as Markdown in `docs/api/` using TypeDoc with typedoc-plugin-markdown and typedoc-plugin-remark. Generated files are committed and enforced in CI.
### Commands```bash
npm run docs # Generate + remark-format docs (commit the result)
npm run docs:lint # Lint committed docs/api with remark
Workflow
- Make source changes
- Run
npm run docsto regenerate API docs - Commit the updated
docs/api/alongside your code changes
CI runs npm run docs then git diff --exit-code docs/api — the build fails if committed docs are out of sync with the source.