mcp-server-modular

No-code tool loading for MCP. Drop a .js file in the tools/ directory, restart the server, and your tool is live. No server code changes needed.

Quick Start

git clone https://github.com/itamos-technologia/mcp-server-modular.git
cd mcp-server-modular
npm install
node server.js

Server starts on http://localhost:3100/mcp. Connect any MCP client to this URL.

Related MCP server: MCP Shell Server

Creating a Tool

Create a .js file in tools/ that exports:

import { z } from 'zod';

export default {
  name: 'my_tool',
  description: 'What this tool does.',

  schema: {
    input: z.string().describe('The input parameter'),
    verbose: z.boolean().optional().describe('Show extra detail'),
  },

  async handler({ input, verbose = false }, ctx) {
    // Your logic here
    // ctx.run(cmd)          — execute shell command
    // ctx.runSafe(bin, args) — execute without shell (no injection risk)
    // ctx.esc(str)          — escape string for shell

    return {
      content: [{ type: 'text', text: `Result: ${input}` }]
    };
  },
};

That's it. Restart the server and your tool is available to any MCP client.

Tool API

Every tool file must export an object with:

Handler Context (ctx)

Handler Return

Return an MCP content array:

return {
  content: [
    { type: 'text', text: 'Your result here' }
  ]
};

Configuration

Features

• Hot-reload — fs.watch on tools/ directory, new sessions pick up changes automatically

• Lifecycle hooks — tools can export init(ctx) and cleanup(ctx) functions

• TypeScript detection — warns about .ts files with helpful compile instructions

• Error isolation — broken tools are skipped, server keeps running

Example Tools

• tools/hello.js — Simple greeting (template for new tools)

• tools/run_command.js — Shell command execution

Architecture

server.js          — MCP transport + tool discovery + hot-reload
tools/             — Drop tools here
  hello.js         — Example tool
  run_command.js   — Example tool
  your_tool.js     — Your custom tool

The server scans tools/ on startup, validates each file exports name, schema, and handler, and registers them with the MCP server. Schema validation is handled by Zod — invalid parameters are rejected before reaching your handler.

More from Itamos

mcp-server-modular is the free, open-source foundation.

MCP Basic — the full production toolkit built on top:

• 📄 Segment-based file editing — read and edit code at 5× token savings with built-in verification

• 🌐 Web page skeletonizer — browse any page at up to 89% token compression

• 📧 Universal mail client — IMAP/SMTP with auto-detect for Gmail, Outlook, Yahoo, and more

• 📋 Text offloader — large pastes compressed to skeleton references (34× savings)

• 🧠 Memory injection — semantic search across conversation history, injected automatically

• 📊 Token tracking dashboard — per-tool breakdown, lifetime savings, cost avoided

20M+ tokens saved and counting.

→ itamos-technologia.com

License

Apache 2.0 — see LICENSE

Author

Itamos Technologia