MCP Server Template

This project is a template for building, packaging, and releasing "Hello World" MCP servers. It demonstrates a modern, automated workflow for creating distributable server bundles for two different transport modes:

1. STDIO: The server communicates over standard input/output pipes, ideal for direct CLI integrations.
2. SSE (HTTP): The server runs as a standalone HTTP service, allowing multiple clients to connect via Server-Sent Events.

The repository is configured with an industrialized build system that automatically packages both server types for release.

---

📂 Repository Layout

.
├── .github/workflows/release.yml # Automated GitHub Actions release workflow
├── dist/                           # Output directory for release bundles (created by `make build`)
├── scripts/
│   └── build_bundle.sh           # Script to package server bundles
├── src/                            # Source code for server variants
│   ├── sse/
│   │   ├── server_sse.py
│   │   └── runner.json             # Runner configuration for SSE
│   └── stdio/
│       ├── server_stdio.py
│       └── runner.json             # Runner configuration for STDIO
├── Makefile                        # Main project command interface
├── pyproject.toml                  # Project definition and dependencies
└── requirements.txt                # Frozen dependencies for bundles

---

✅ Prerequisites

• Python 3.11+
• Poetry (for dependency management)
• make (GNU Make)
• gh CLI (optional, for the make release command)

---

🚀 Quickstart

Install dependencies and set up your local virtual environment using Poetry. This single command prepares your entire development workspace.

make install

---

🧑‍💻 Development Workflow

This project uses the matrix SDK to simulate the full lifecycle of an MCP server: installing a bundle, running it as a managed process, and interacting with it.

Version 1: STDIO Communication

The STDIO server is managed as a background process by the matrix runtime.

• Build, Install, and Run the Server

  make run-stdio

  This command chains the entire process: builds the .zip bundle, installs it using the SDK, and starts the server.

• Test the Running Server

  make test-stdio

  Runs the client script, which communicates with the background server over its STDIO pipes.

• Stop the Server

  make stop-stdio

  Uses the SDK to gracefully stop the managed process.

• View Logs

  make logs-stdio

Version 2: SSE (HTTP) Communication

The SSE server is managed as a persistent HTTP service by the matrix runtime, which automatically handles port allocation.

• Build, Install, and Run the Server

  make run-sse

  Builds the .zip bundle, installs it, and starts the HTTP server on an available port.

• Test the Running Server

  make test-sse

  Runs the client script, which connects to the server's SSE endpoint.

• Stop the Server

  make stop-sse

• View Logs

  make logs-sse

---

📦 Automated Packaging & Release

This template is designed for automated releases.

• Build All Bundles Locally

  make build

  This command uses scripts/build_bundle.sh to create versioned .zip archives and .sha256 checksums for both SSE and STDIO servers in the dist/ directory.

• Create a GitHub Release The .github/workflows/release.yml workflow automates this entire process. Simply push a new tag to your repository:

  git tag v0.2.0
  git push origin v0.2.0

  GitHub Actions will automatically build all bundles and attach them to a new release, ready for ingestion into Matrix Hub.

---

📖 Makefile Targets

Target	Description
make help	✨ Display the list of available commands.
make install	📦 Set up virtualenv & install dependencies.
make build	🛠️ Builds versioned ZIP bundles for all server types.
make release	🚀 Creates a GitHub release with all bundles (requires gh CLI).
STDIO
make run-stdio	🏃 Install and run the STDIO server via the SDK.
make test-stdio	🔬 Run the STDIO client against the SDK-managed server.
make stop-stdio	🛑 Stop the background STDIO agent server.
make logs-stdio	📜 View the logs for the STDIO server.
SSE (HTTP)
make run-sse	🏃 Install and run the SSE server via the SDK.
make test-sse	🔬 Run the client to connect to the SSE server.
make stop-sse	🛑 Stop the background SSE agent server.
make logs-sse	📜 View the logs for the SSE server.
General
make clean	🧹 Stop servers and remove virtual env and build artifacts.

---

Happy building your MCP servers!