npm package: @hwangboss/mcp-typescript-demo
Description: A comprehensive MCP (Model Context Protocol) demo using TypeScript
Author: Your Name
Latest version: 1.1.2

# MCP TypeScript Demo

A comprehensive demonstration of the **Model Context Protocol (MCP)** using TypeScript and Node.js. This project showcases how to build a robust MCP server with multiple tools, resources, and best practices.

## 🚀 Features

- ✅ **Weather Information Tool** - Get weather data for cities worldwide
- ✅ **File Operations** - Read, write, and list files with security controls  
- ✅ **Calculator Tool** - Perform mathematical calculations with multiple operations
- ✅ **CSDN Article Publishing** - Publish Markdown articles to CSDN platform
- ✅ **Static Resource Provider** - Serve documentation and configuration resources
- ✅ **Type Safety** - Full TypeScript implementation with strict type checking
- ✅ **Input Validation** - Comprehensive validation using Zod schemas
- ✅ **Error Handling** - Robust error handling and logging
- ✅ **Security** - Path traversal protection and input sanitization
- ✅ **Structured Logging** - Detailed logging with configurable levels

## 📋 Prerequisites

- **Node.js** >= 18.0.0
- **npm** or **yarn**
- **TypeScript** knowledge

## 🛠️ Installation

1. **Clone or download** this demo project
2. **Install dependencies**:
   ```bash
   npm install
   ```

## 🏗️ Build & Run

### Development Mode
```bash
# Build TypeScript
npm run build

# Watch mode for development
npm run dev

# Start the server
npm start
```

### Production Mode
```bash
# Build for production
npm run build

# Start production server
NODE_ENV=production npm start
```

## 📦 Installation & Configuration

### Method 1: NPX Installation (Recommended)

After publishing to npm, you can use it like other MCP servers:

```json
{
  "mcpServers": {
    "typescript-demo": {
      "command": "npx",
      "args": [
        "-y",
        "@hwangboss/mcp-typescript-demo",
        "/Users/bhuang/Desktop",
        "/Users/bhuang/Downloads",
        "/Users/bhuang/code"
      ],
      "env": {
        "LOG_LEVEL": "INFO",
        "CSDN_COOKIE": "your_csdn_cookie_here",
        "CSDN_CATEGORIES": "TypeScript"
      }
    }
  }
}
```

### Method 2: Local Development

```json
{
  "mcpServers": {
    "typescript-demo": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/Users/bhuang/code/ai/mcp-typescript-demo",
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
```

### Command Line Arguments

The server supports command line arguments for specifying allowed directories:

```bash
# Allow file operations in specific directories
mcp-typescript-demo /Users/bhuang/Desktop /Users/bhuang/Downloads

# Show help
mcp-typescript-demo --help

# Show version
mcp-typescript-demo --version
```

## 🧪 Usage Examples

### Weather Tool
```javascript
// Get weather for London with metric units
const weather = await mcpClient.callTool('get_weather', {
  city: 'London',
  country: 'UK',
  units: 'metric'
});
```

### File Operations
```javascript
// Read a file
const fileData = await mcpClient.callTool('read_file', {
  path: 'example.txt',
  encoding: 'utf8'
});

// Write to a file
await mcpClient.callTool('write_file', {
  path: 'output.txt',
  content: 'Hello MCP!',
  createDirectories: true
});

// List files in directory
const files = await mcpClient.callTool('list_files', {
  directory: '.',
  recursive: false
});
```

### Calculator
```javascript
// Basic arithmetic
const sum = await mcpClient.callTool('calculate', {
  operation: 'add',
  operands: [1, 2, 3, 4]
});

// Power operation
const power = await mcpClient.callTool('calculate', {
  operation: 'power', 
  operands: [2, 8]
});
```

### CSDN Article Publishing
```javascript
// Publish a Markdown article to CSDN
const result = await mcpClient.callTool('publish_markdown_article', {
  title: "TypeScript 入门指南",
  markdownContent: "# TypeScript 入门指南\n\n这是一篇关于 TypeScript 的入门文章...",
  tags: "TypeScript,JavaScript,编程",
  description: "一篇详细介绍 TypeScript 基础知识的文章"
});
```

## 📚 Available Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `get_weather` | Get weather information | `city`, `country?`, `units?` |
| `read_file` | Read file contents | `path`, `encoding?` |
| `write_file` | Write to file | `path`, `content`, `encoding?`, `createDirectories?` |
| `list_files` | List directory contents | `directory`, `recursive?`, `includeHidden?` |
| `calculate` | Mathematical operations | `operation`, `operands` |
| `publish_markdown_article` | Publish to CSDN | `title`, `markdownContent`, `tags`, `description` |

## 📖 Available Resources

| Resource | Description | URI Pattern |
|----------|-------------|-------------|
| Documentation | API docs and README | `static://docs/{name}` |
| Configuration | Config templates | `static://config/{name}` |
| Examples | Usage examples | `static://examples/{name}` |

## 🔧 Configuration

### Environment Variables
- `LOG_LEVEL` - Set logging level (DEBUG, INFO, WARN, ERROR)
- `NODE_ENV` - Environment mode (development, production)
- `CSDN_COOKIE` - CSDN authentication cookie
- `CSDN_CATEGORIES` - CSDN article categories (default: TypeScript)

### File Operations Security
The file operations are restricted to the server's working directory for security. Path traversal attempts are automatically blocked.

## 🏗️ Architecture

```
src/
├── index.ts              # Main server entry point
├── types/               # TypeScript type definitions
│   └── index.ts
├── tools/               # Tool implementations
│   ├── weather.ts       # Weather information tool
│   ├── files.ts         # File operation tools
│   ├── calculator.ts    # Calculator tool
│   └── csdn.ts          # CSDN article publishing tool
├── resources/           # Resource providers
│   └── static.ts        # Static resource provider
└── utils/               # Utility functions
    ├── logger.ts        # Logging utility
    └── validators.ts    # Input validation schemas
```

## 🛡️ Security Features

- **Path Traversal Protection** - File operations are sandboxed
- **Input Validation** - All inputs validated with Zod schemas
- **Error Handling** - Secure error messages without information leakage
- **Type Safety** - Strict TypeScript prevents runtime errors

## 🧪 Development

### Code Quality
```bash
# Lint code
npm run lint

# Format code
npm run format

# Run tests
npm test
```

### VS Code Integration
The project includes TypeScript configurations optimized for VS Code development with IntelliSense support.

## 📝 API Documentation

The server provides comprehensive API documentation accessible via the `static://docs/api` resource. This includes:

- Complete tool specifications
- Parameter details and validation rules
- Error codes and handling
- Usage examples

## 🤝 Contributing

1. Follow TypeScript best practices
2. Maintain test coverage
3. Use conventional commit messages
4. Update documentation for new features

## 📄 License

MIT License - feel free to use this demo as a starting point for your own MCP servers.

## 🔗 Related Links

- [Model Context Protocol Specification](https://github.com/modelcontextprotocol/specification)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [TypeScript Documentation](https://www.typescriptlang.org/docs/)

---

**Built with TypeScript + Node.js + MCP SDK**