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.

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:

Field	Type	Required	Description
name	string	Yes	Unique tool name
description	string	No	Shown to the LLM
schema	object	Yes	Zod schema for parameters
handler	async function	Yes	Receives (args, ctx)

Handler Context (ctx)

Method	Description
ctx.run(cmd, timeout?)	Execute shell command (returns stdout)
ctx.runSafe(bin, args, timeout?)	Execute without shell — no injection possible
ctx.esc(str)	Escape string for safe shell interpolation

Handler Return

Return an MCP content array:

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

Configuration

Env Variable	Default	Description
MCP_PORT	3100	Server port

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