<div align="center">

<img src="https://raw.githubusercontent.com/falkenslab/mcp-server-template/main/docs/static/img/logo.svg" alt="mcp-server-template logo: a plug" width="112"/>

# mcp-server-template

**A Falken's Lab MCP server.**<br/>
The starting point for Falken's Lab's MCP servers: one bundled file, tests, docs in English and Spanish, ready for agent-kit.

[![npm](https://img.shields.io/npm/v/@falkenslab/mcp-server-template?color=cb3837&logo=npm)](https://www.npmjs.com/package/@falkenslab/mcp-server-template)
![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white)
![MCP server](https://img.shields.io/badge/MCP-server-0b0b0b)
[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](LICENSE)

**[📖 Documentation](https://falkenslab.github.io/mcp-server-template/)** · [📖 Documentación en español](https://falkenslab.github.io/mcp-server-template/es/)

</div>

This is a template repository: every Falken's Lab MCP server starts here, so they all look and work the same. It's an MCP server over stdio, written in TypeScript with the official MCP SDK and bundled into a single file that runs with `npx`, so an agent built on [agent-kit](https://github.com/falkenslab/agent-kit) can run it without installing anything. It comes with one example tool, tests, a strict check of its tools, CI, a documentation site in English and Spanish, and the design notes every server shares.

## ✨ Why this template

- 📦 **One file, nothing to install.** esbuild bundles every dependency into `dist/server.mjs`, which agent-kit runs with `npx`.
- 🧭 **Tools a model chooses well.** Each tool has a title, a description for the model, schemas and `readOnlyHint`, and `npm run check` fails if one doesn't.
- 🔧 **Programs installed apart, explained.** A server that needs Docker or ffmpeg declares it once and gets `check_requirements` and clear errors; it never installs anything.
- 🧪 **Tested from the start.** `node:test` with the SDK's in-memory transport, and CI on Node 20 and 24.
- 🌍 **Docs in two languages.** A Docusaurus site in English and Spanish, with the tools reference generated from the server itself.
- 🧠 **Design memory.** `.minispec/` with the decisions every Falken's Lab server shares, and a `CLAUDE.md` for coding agents.

## 🚀 Quick start

On GitHub, **Use this template** to create the new repository, then:

```bash
npm install
npm run init -- docker-lab-mcp "Hands-on practices in Docker, safe by default."
npm run build && npm run check
```

`init` renames the package, the command, the links and the docs. Then rewrite `.minispec/core/project.md` and this README for the new server, and add its tools in `src/tools/`.

## 🧰 What's inside

| Area | For example |
| --- | --- |
| 🔌 Server | `src/server.ts` (stdio), `src/createServer.ts`, `src/instructions.ts` |
| 🛠️ Tools | `server_info`, one file per tool in `src/tools/`, `reply()` for structured results |
| 🔧 Requirements | `src/requirements.ts`: `check_requirements` and `needs()`, only when a server needs programs |
| 🧪 Checks | `npm test`, `npm run check` (strict `tools/list`), typecheck and lint, CI |
| 📖 Docs | `docs/`, Docusaurus in English and Spanish, published to GitHub Pages |
| 🧠 Design | `.minispec/` (project, conventions, ADRs), `CLAUDE.md` |

## 📚 Documentation

- **[Getting started](https://falkenslab.github.io/mcp-server-template/getting-started)**: installing the server in an agent or in Claude Code.
- **[Tools](https://falkenslab.github.io/mcp-server-template/reference/tools)**: every tool, generated from the server.

## 🛠️ Developing

`npm run build`, `npm test` and `npm run check` before every commit; `CLAUDE.md` lists every command, and `.minispec/` the decisions behind them. Releases are published to npm by the owner.

<div align="center">

Made with 💖 by Falken's Lab Team

</div>