@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.

---

Table of Contents

• 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

1. Install dependencies:

   npm install

2. Configure environment variables:

   • MCP_PORT: (optional) Port to run the server (default: 1234)
   • MCP_TOKEN: (optional) Bearer token for authentication

3. Start the server:

   node mcp-server-template.mjs

4. Call tools via HTTP or MCP client.
   See the @purinton/mcp-server documentation for protocol/API details.

Extending & Customizing

To add a new tool:

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

   import { z, buildResponse } from '@purinton/mcp-server';
   
   export default async function (server, toolName = 'mytool') {
     server.tool(
       toolName,
       "Describe what your tool does here.",
       { inputParam: z.string() }, // Define your input schema
       async (_args, _extra) => {
         // Your tool logic here
         return buildResponse({ message: "mytool-reply", data: { result: "..." } });
       }
     );
   }

2. Document your tool in the Available Tools section above.

3. 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

License

MIT © 2025 Russell Purinton

Links

• @purinton/mcp-server on npm
• GitHub
• Discord