npm package: @maybexubin/mcp-toolkit
Description: A modern, extensible Node.js toolkit for building MCP (Model Context Protocol) servers with automatic tool discovery
Author: MCP Toolkit Contributors
Latest version: 1.0.4

# MCP Toolkit 🔧

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

[![npm version](https://badge.fury.io/js/@maybexubin%2Fmcp-toolkit.svg)](https://www.npmjs.com/package/@maybexubin/mcp-toolkit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ 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:

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

### Command Line Usage

```bash
# 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:**
```javascript
// 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/`:

```javascript
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.

```javascript
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.

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

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

### BaseTool

Base class for creating new tools.

```javascript
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:

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

## 📄 License

MIT License - see the [LICENSE](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