mcp-server-template by purinton - MCP Server

@purinton/mcp-server-template

A Model Context Protocol (MCP) server providing a set of custom tools for AI and automation workflows. Easily extendable with your own tools.

Overview
Available Tools
Usage
Extending & Customizing
Support
License
Links

Overview

This project is an MCP server built on @purinton/mcp-server . It exposes a set of tools via the Model Context Protocol, making them accessible to AI agents and automation clients.

Key Features:

Dynamic tool loading from the tools/ directory
Simple to add or modify tools
HTTP API with authentication
Built for easy extension

Available Tools

Below is a list of tools provided by this MCP server. Each tool can be called via the MCP protocol or HTTP API.

Example: Echo Tool

Name: echo
Description: Returns the text you send it.

Input Schema:

{ "echoText": "string" }

Example Request:

{
  "tool": "echo",
  "args": { "echoText": "Hello, world!" }
}

Example Response:

{
  "message": "echo-reply",
  "data": { "text": "Hello, world!" }
}

Usage

Install dependencies:
```
npm install
```
Configure environment variables:
- MCP_PORT: (optional) Port to run the server (default: 1234)
- MCP_TOKEN: (optional) Bearer token for authentication
Start the server:
```
node mcp-server-template.mjs
```
Call tools via HTTP or MCP client.
See the @purinton/mcp-server documentation for protocol/API details.

Extending & Customizing

To add a new tool:

Create a new file in the tools/ directory (e.g., tools/mytool.mjs):

import { z, buildResponse } from '@purinton/mcp-server';
export default async function ({ mcpServer, toolName, log }) {
  mcpServer.tool(
    toolName,
    "Write a brief description of your tool here",
    { echoText: z.string() },
    async (_args,_extra) => {
      log.debug(`${toolName} Request`, { _args });
      const response = 'Hello World!';
      log.debug(`${toolName} Response`, { response });
      return buildResponse(response);
    }
  );
}

Document your tool in the Available Tools section above.
Restart the server to load new tools.

You can add as many tools as you like. Each tool is a self-contained module.

Running as a systemd Service

You can run this server as a background service on Linux using the provided mcp-server-template.service file.

1. Copy the service file

Copy mcp-server-template.service to your systemd directory (usually /etc/systemd/system/):

sudo cp mcp-server-template.service /usr/lib/systemd/system/

2. Adjust paths and environment

Make sure the WorkingDirectory and ExecStart paths in the service file match where your project is installed (default: /opt/mcp-server-template).
Ensure your environment file exists at /opt/mcp-server-template/.env if you use one.

3. Reload systemd and enable the service

sudo systemctl daemon-reload
sudo systemctl enable mcp-server-template
sudo systemctl start mcp-server-template

4. Check service status

sudo systemctl status mcp-server-template

The server will now run in the background and restart automatically on failure or reboot.

Running with Docker

You can run this MCP server in a Docker container using the provided Dockerfile.

1. Build the Docker image

docker build -t mcp-server-template .

2. Run the container

Set your environment variables (such as MCP_TOKEN) and map the port as needed:

docker run -d \
  -e MCP_TOKEN=your_secret_token \
  -e MCP_PORT=1234 \
  -p 1234:1234 \
  --name mcp-server-template \
  mcp-server-template

Replace your_secret_token with your desired token.
You can override the port by changing -e MCP_PORT and -p values.

3. Updating the image

If you make changes to the code, rebuild the image and restart the container:

docker build -t mcp-server-template .
docker stop mcp-server-template && docker rm mcp-server-template
# Then run the container again as above

Support

For help, questions, or to chat with the author and community, visit:

Purinton Dev on Discord