MCP Toolkit 🔧

A modern, extensible Node.js toolkit for building MCP (Model Context Protocol) servers with automatic tool discovery.

✨ Features

• 🚀 Zero Configuration: Works out of the box with npx
• 🔍 Auto-Discovery: Automatically finds and loads tools
• 📦 Extensible: Easy to add new tools following the open/closed principle
• 🛡️ Type Safe: Built with modern ES modules and validation
• 🎯 Claude Ready: Perfect integration with Claude Code
• 📖 Self-Documenting: Tools include rich descriptions and examples

🚀 Quick Start

Using with Claude Code

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "mcp-toolkit": {
      "command": "npx",
      "args": ["-y", "@maybexubin/mcp-toolkit"],
      "env": {}
    }
  }
}

Command Line Usage

# Start MCP server
npx @maybexubin/mcp-toolkit

# List available tools
npx @maybexubin/mcp-toolkit --list-tools

# Show version
npx @maybexubin/mcp-toolkit --version

# Show help
npx @maybexubin/mcp-toolkit --help

🔧 Available Tools

Calculator

Perform mathematical calculations and evaluate expressions.

Features:

• Basic arithmetic: +, -, *, /, %
• Advanced functions: sqrt, pow, abs, round, ceil, floor
• Trigonometric: sin, cos, tan, asin, acos, atan
• Logarithmic: log, log10, log2, exp
• Constants: PI, E
• Complex expressions with parentheses

Examples:

// Basic arithmetic
calculator({"expression": "2 + 3 * 4"})  // Result: 14

// Advanced functions
calculator({"expression": "sqrt(16) + pow(2, 3)"})  // Result: 12

// Trigonometry
calculator({"expression": "sin(PI/2)"})  // Result: 1

// Complex expressions
calculator({"expression": "(sqrt(16) + 2) * 3 - 1"})  // Result: 17

🛠️ Development

Adding New Tools

1. Create a new tool file in src/tools/:

import { BaseTool } from '../base-tool.js';

export class MyNewTool extends BaseTool {
  get name() {
    return 'my-new-tool';
  }

  get description() {
    return 'Description of what this tool does for Claude to understand';
  }

  getInputSchema() {
    return {
      type: 'object',
      properties: {
        input: {
          type: 'string',
          description: 'Input parameter description'
        }
      },
      required: ['input']
    };
  }

  async execute(args) {
    const { input } = args;
    // Tool logic here
    return this.success(`Processed: ${input}`);
  }
}

2. The tool will be automatically discovered and loaded! ✨

Tool Base Class

All tools extend BaseTool which provides:

• Validation: Automatic input validation against JSON schema
• Error Handling: Consistent error responses
• Success Helpers: Standardized success responses
• Metadata: Tool definitions for MCP registration

Architecture

mcp-toolkit/
├── index.js              # Main entry point with CLI
├── src/
│   ├── base-tool.js      # Base class for all tools
│   ├── tool-loader.js    # Automatic tool discovery
│   ├── server.js         # MCP server implementation
│   └── tools/            # Tool implementations
│       ├── calculator.js # Calculator tool
│       └── index.js      # Tool exports
├── package.json          # NPM configuration
└── README.md            # This file

📚 API Reference

MCPServer

The main server class that handles MCP protocol communication.

import { MCPServer } from '@maybexubin/mcp-toolkit';

const server = new MCPServer({
  name: 'my-server',
  version: '1.0.0'
});

await server.start();

ToolLoader

Automatically discovers and loads tools from the tools directory.

import { ToolLoader } from '@maybexubin/mcp-toolkit';

const loader = new ToolLoader();
await loader.loadAllTools();

BaseTool

Base class for creating new tools.

import { BaseTool } from '@maybexubin/mcp-toolkit';

class MyTool extends BaseTool {
  // Implementation
}

🔍 Troubleshooting

NPX Issues

If npx @maybexubin/mcp-toolkit doesn't work:

1. Clear npm cache: npm cache clean --force
2. Use with -y flag: npx -y @maybexubin/mcp-toolkit
3. Check Node.js version (requires >=18.0.0)

Claude Code Integration

1. Ensure the MCP server configuration is in the correct format
2. Restart Claude Code after adding the configuration
3. Check Claude Code logs for connection errors

Development Mode

Set environment variables for debugging:

DEBUG=1 node index.js
NODE_ENV=development node index.js

📄 License

MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🏷️ Version History

• 1.0.2 - Simplified architecture, improved npx support, comprehensive calculator tool
• 1.0.1 - Initial release with basic MCP server functionality

Built with ❤️ for the Claude Code and MCP community