@purinton/supervisor

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 supervisor.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 ({ 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);
    }
  );
}

1. Document your tool in the Available Tools section above.
2. 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 supervisor.service file.

1. Copy the service file

Copy supervisor.service to your systemd directory (usually /etc/systemd/system/):

sudo cp supervisor.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/supervisor).
• Ensure your environment file exists at /opt/supervisor/.env if you use one.

3. Reload systemd and enable the service

sudo systemctl daemon-reload
sudo systemctl enable supervisor
sudo systemctl start supervisor

4. Check service status

sudo systemctl status supervisor

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

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 supervisor \
  supervisor

• 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 supervisor .
docker stop supervisor && docker rm supervisor
# 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 Repo
• GitHub Org
• GitHub Personal
• Discord