# MCP Server

A unified MCP (Model Context Protocol) server with pluggable tools. Each tool has an independent endpoint, allowing clients to selectively add specific tools.

[中文文档](./README_zh.md)

## Features

- **Unified Endpoint with Path Routing**: Each tool has its own MCP endpoint (`/mcp/{toolName}`)
- **Loosely Coupled Tools**: Tools are independently loaded from `src/tools/` directory
- **Fault Isolation**: Individual tool failures don't affect other tools (timeout protection + error handling)
- **StreamableHTTP Transport**: Modern MCP transport protocol
- **Bearer Token Authentication**: Secure API access
- **Docker Support**: Ready for containerized deployment

## Project Structure

```
mcp_server/
├── src/
│   ├── index.ts                    # Entry point
│   ├── core/
│   │   ├── tool-registry.ts        # Tool registry
│   │   ├── tool-loader.ts          # Dynamic tool loader
│   │   └── tool-executor.ts        # Isolated executor (timeout + error handling)
│   ├── server/
│   │   ├── app.ts                  # Express + StreamableHTTP
│   │   └── mcp-server.ts           # MCP Server instance
│   ├── middleware/
│   │   └── auth.ts                 # Bearer token authentication
│   ├── tools/                      # Loosely coupled tools directory
│   │   ├── calculator/index.ts     # Calculator tool (add/subtract/multiply/divide)
│   │   ├── echo/index.ts           # Echo tool (echo/reverse/info)
│   │   └── time/index.ts           # Time tool (get_current_time/convert_time/format_time)
│   ├── types/mcp.ts                # Type definitions
│   └── utils/logger.ts             # Terminal logger
├── Dockerfile                      # Multi-stage build
├── docker-compose.yml
├── package.json
└── tsconfig.json
```

## Quick Start

### Local Development

```bash
# Install dependencies
npm install

# Create .env file
echo "AUTHORIZATION_KEY=your-secret-key" > .env

# Start development server
npm run dev
```

### Docker Deployment

```bash
# Build and run with docker-compose
docker-compose up -d --build

# Or build manually
docker build -t mcp-server .
docker run -e AUTHORIZATION_KEY=your-secret-key -p 3000:3000 mcp-server
```

## API Endpoints

| Endpoint          | Method | Description                                  |
| ----------------- | ------ | -------------------------------------------- |
| `/mcp/{toolName}` | POST   | MCP JSON-RPC request for specific tool       |
| `/mcp/{toolName}` | GET    | SSE connection (requires session-id)         |
| `/mcp/{toolName}` | DELETE | Close session                                |
| `/health`         | GET    | Health check                                 |
| `/tools`          | GET    | List all available tools and their endpoints |

## Available Tools

### Calculator (`/mcp/calculator`)

Math expression evaluator supporting various operators and functions.

| Method     | Description                    | Parameters             |
| ---------- | ------------------------------ | ---------------------- |
| `evaluate` | Evaluate a math expression     | `expression`: string   |

**Supported Operators:**
- Arithmetic: `+`, `-`, `*`, `/`
- Floor Division: `//`
- Modulo: `%`
- Power: `**` or `^`

**Supported Constants:** `pi`, `e`

**Supported Functions:** `sin`, `cos`, `tan`, `sqrt`, `abs`, `log`, `log10`, `exp`, `floor`, `ceil`, `round`, `pow`, `min`, `max`

**Examples:**
```
2 + 3 * 4        → 14
(2 + 3) * 4      → 20
2^10             → 1024
sqrt(16)         → 4
2 * pi           → 6.283...
sin(0)           → 0
pow(2, 8)        → 256
17 // 5          → 3
17 % 5           → 2
```

### Echo (`/mcp/echo`)

Echo tool for testing and debugging.

| Method    | Description                 | Parameters        |
| --------- | --------------------------- | ----------------- |
| `echo`    | Echo back the input message | `message`: string |
| `reverse` | Reverse the input string    | `text`: string    |
| `info`    | Get server information      | -                 |

### Time (`/mcp/time`)

Time tool for timezone conversion and formatting.

| Method             | Description                             | Parameters                                                                   |
| ------------------ | --------------------------------------- | ---------------------------------------------------------------------------- |
| `get_current_time` | Get current time in a specific timezone | `timezone`: string (default: "Etc/UTC")                                      |
| `convert_time`     | Convert time between timezones          | `source_timezone`: string, `target_timezone`: string, `time`: string (HH:MM) |
| `format_time`      | Convert timestamp to formatted string   | `timestamp`: number (ms), `timezone`: string                                 |

## Client Configuration

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "calculator": {
      "url": "http://localhost:3000/mcp/calculator",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    },
    "time": {
      "url": "http://localhost:3000/mcp/time",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    }
  }
}
```

### Cursor / VS Code

Create `.cursor/mcp.json` in project root:

```json
{
  "mcpServers": {
    "calculator": {
      "url": "http://localhost:3000/mcp/calculator",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    }
  }
}
```

### Programmatic Usage (Node.js)

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({
  name: "my-client",
  version: "1.0.0",
});

const transport = new StreamableHTTPClientTransport(
  new URL("http://localhost:3000/mcp/calculator"),
  {
    requestInit: {
      headers: {
        Authorization: "Bearer your-secret-key",
      },
    },
  }
);

await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log(tools);

// Call a tool
const result = await client.callTool({
  name: "add",
  arguments: { a: 10, b: 5 },
});
console.log(result);
```

## Adding New Tools

1. Create a new directory under `src/tools/`:

```
src/tools/my-tool/
└── index.ts
```

2. Implement the `MCPTool` interface:

```typescript
import { z } from "zod";
import { MCPTool, MCPMethodDefinition } from "../../types/mcp.js";

const myTool: MCPTool = {
  name: "my-tool",
  description: "Description of my tool",
  version: "1.0.0",

  getMethods(): MCPMethodDefinition[] {
    return [
      {
        name: "my-method",
        description: "Description of my method",
        inputSchema: {
          param1: z.string().describe("Parameter description"),
        },
        handler: async (params) => {
          const { param1 } = params as { param1: string };
          return { result: param1 };
        },
      },
    ];
  },

  async initialize() {
    // Initialization logic
  },

  async healthCheck() {
    return true;
  },
};

export default myTool;
```

3. The tool will be automatically loaded on server startup.

## Scripts

```bash
npm run dev        # Start development server with hot reload
npm run build      # Build for production
npm start          # Start production server
npm test           # Run tests
npm run lint       # Check code style
npm run lint:fix   # Auto-fix code style issues
```

## License

MIT