@glec/mcp-server/README.md

GLEC API MCP Server for Claude Desktop - Carbon emission calculation for logistics and transportation

# GLEC MCP Server

[![npm version](https://badge.fury.io/js/%40glec%2Fmcp-server.svg)](https://badge.fury.io/js/%40glec%2Fmcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/@glec/mcp-server)](https://nodejs.org/)

A Model Context Protocol (MCP) server that provides access to the GLEC API for calculating carbon emissions from logistics and transportation. This server enables Claude Desktop to interact with GLEC's emission calculation services through natural language.

## 🔑 Deployment Information

**Repository Owner**: gleccloud@gmail.com  
**GitHub Token**: `[REDACTED - See deployment guide]`  
**Repository URL**: https://github.com/gleccloud/glec-mcp-server  
**NPM Package**: @glec/mcp-server@1.0.0  
**Smithery API Key**: 79f45de2-1139-452c-aa2e-30e615314b4b  

### Manual GitHub Repository Creation
1. Go to https://github.com/new
2. Repository name: `glec-mcp-server`
3. Description: `GLEC API MCP Server - Claude Desktop integration for global logistics carbon emission calculations`
4. Set to Public
5. Do not initialize with README (already exists)
6. Create repository
7. Run: `git push -u origin main`

## 🌟 Features

- **🚛 Multi-Modal Transport**: Calculate emissions for road, rail, air, and sea transport
- **📊 ESG Reporting**: Generate comprehensive ESG and compliance reports
- **👥 Shipper Management**: Manage shipper information and data
- **🔒 Enterprise Security**: Encrypted API key storage and comprehensive logging
- **⚡ High Performance**: Rate limiting, caching, and optimized API calls
- **🛡️ Error Handling**: Robust error handling with detailed error messages
- **📈 Monitoring**: Built-in logging and performance monitoring

## 🚀 Quick Start

### Prerequisites

- Node.js 18.0.0 or higher
- Claude Desktop (Windows)
- GLEC API Key (get from [GLEC Console](https://open-api.glec.io/console))

### Installation

1. **Install the MCP server globally:**
   ```bash
   npm install -g @glec/mcp-server
   ```

2. **Get your GLEC API Key:**
   - Visit [GLEC Console](https://open-api.glec.io/console)
   - Sign up or log in to your account
   - Navigate to API Keys section
   - Create a new API key
   - Copy the API key for configuration

3. **Configure Claude Desktop:**
   - Open Claude Desktop settings
   - Go to "MCP Servers" section
   - Add new server configuration
   - Use the configuration provided below

## ⚙️ Configuration

### Claude Desktop Configuration

Add the following configuration to your Claude Desktop settings:

```json
{
  "mcpServers": {
    "glec-api": {
      "command": "glec-mcp",
      "env": {
        "GLEC_API_KEY": "your-glec-api-key-here",
        "GLEC_BEARER_TOKEN": "your-bearer-token-here",
        "GLEC_BASE_URL": "https://open-api.glec.io",
        "GLEC_TIMEOUT": "30000",
        "GLEC_RETRIES": "3",
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GLEC_API_KEY` | ✅ | - | Your GLEC API key from the console |
| `GLEC_BEARER_TOKEN` | ❌ | - | Bearer token for advanced features |
| `GLEC_BASE_URL` | ❌ | `https://open-api.glec.io` | GLEC API base URL |
| `GLEC_TIMEOUT` | ❌ | `30000` | Request timeout in milliseconds |
| `GLEC_RETRIES` | ❌ | `3` | Number of retry attempts |
| `LOG_LEVEL` | ❌ | `info` | Logging level (debug, info, warn, error) |

## 🛠️ Available Tools

### Emission Calculation

#### `glec_calculate_road_emission`
Calculate CO2 emissions for road transport.

**Parameters:**
- `transportMode` (required): Transport mode code (M001, M002, M003)
- `distance` (required): Distance in kilometers
- `weight` (required): Weight in tons
- `startLocation` (optional): Starting location
- `endLocation` (optional): Ending location
- `transportDate` (optional): Transport date (YYYY-MM-DD)
- `distanceUnit` (optional): Distance unit (km, miles)
- `weightUnit` (optional): Weight unit (t, kg, lbs)
- `vehicleType` (optional): Vehicle type
- `fuelType` (optional): Fuel type
- `loadFactor` (optional): Load factor (0-1)

**Example:**
```json
{
  "transportMode": "M001",
  "distance": 100,
  "weight": 5,
  "startLocation": "Seoul",
  "endLocation": "Busan",
  "transportDate": "2024-01-15"
}
```

#### `glec_calculate_rail_emission`
Calculate CO2 emissions for rail transport.

**Parameters:**
- `transportMode` (required): Rail transport mode code (R001, R002, R003)
- `distance` (required): Distance in kilometers
- `weight` (required): Weight in tons
- `trainType` (optional): Train type
- `electrification` (optional): Electrification type

#### `glec_calculate_air_emission`
Calculate CO2 emissions for air transport.

**Parameters:**
- `transportMode` (required): Air transport mode code (A001, A002, A003)
- `distance` (required): Distance in kilometers
- `weight` (required): Weight in tons
- `aircraftType` (optional): Aircraft type
- `flightType` (optional): Flight type (domestic, international)

#### `glec_calculate_sea_emission`
Calculate CO2 emissions for sea transport.

**Parameters:**
- `transportMode` (required): Sea transport mode code (S001, S002, S003)
- `distance` (required): Distance in kilometers
- `weight` (required): Weight in tons
- `shipType` (optional): Ship type
- `containerType` (optional): Container type

### Shipper Management

#### `glec_list_shippers`
List all registered shippers.

**Parameters:**
- `page` (optional): Page number (default: 1)
- `size` (optional): Page size (default: 10)
- `search` (optional): Search term

#### `glec_create_shipper`
Create a new shipper.

**Parameters:**
- `name` (required): Shipper name
- `email` (optional): Shipper email
- `phone` (optional): Phone number
- `address` (optional): Address
- `country` (optional): Country code
- `industry` (optional): Industry type
- `companySize` (optional): Company size

### Reports

#### `glec_generate_esg_report`
Generate ESG report.

**Parameters:**
- `startDate` (required): Start date (YYYY-MM-DD)
- `endDate` (required): End date (YYYY-MM-DD)
- `format` (optional): Report format (pdf, excel, json)
- `scope` (optional): Emission scope (1, 2, 3, 1,2, 1,3, 2,3, 1,2,3)
- `language` (optional): Report language (ko, en, ja, zh)
- `includeCharts` (optional): Include charts (default: true)
- `includeDetails` (optional): Include detailed data (default: true)
- `certificationStandard` (optional): Certification standard

### Utilities

#### `glec_get_emission_codes`
Get emission factor codes.

**Parameters:**
- `transportMode` (required): Transport mode (road, rail, air, sea)
- `category` (required): Vehicle size category (small, medium, large)

#### `glec_health_check`
Check GLEC API health status.

## 📚 Usage Examples

### Basic Emission Calculation

```
User: "Calculate the CO2 emissions for transporting 10 tons of goods 200km by road using a medium truck."

Claude: I'll calculate the road transport emissions for you.
```

### Multi-Modal Comparison

```
User: "Compare the emissions for transporting 5 tons 500km by road vs rail."

Claude: I'll calculate emissions for both transport modes and compare them.
```

### ESG Report Generation

```
User: "Generate an ESG report for Q1 2024 in PDF format."

Claude: I'll generate an ESG report for Q1 2024 in PDF format.
```

## 🔧 Development

### Local Development

1. **Clone the repository:**
   ```bash
   git clone https://github.com/glec-io/mcp-server.git
   cd mcp-server
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Set environment variables:**
   ```bash
   cp .env.example .env
   # Edit .env with your API key
   ```

4. **Build the project:**
   ```bash
   npm run build
   ```

5. **Run in development mode:**
   ```bash
   npm run dev
   ```

### Testing

```bash
# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch
```

### Linting and Formatting

```bash
# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format
```

## 🐛 Troubleshooting

### Common Issues

#### 1. Authentication Error
**Error:** `Authentication Error: Authentication failed`

**Solution:**
- Verify your API key is correct
- Check if the API key is active in GLEC Console
- Ensure the API key has the required permissions

#### 2. Rate Limit Exceeded
**Error:** `Rate Limit Error: Rate limit exceeded`

**Solution:**
- Wait for the rate limit window to reset
- Consider upgrading your GLEC API plan
- Implement request batching for bulk operations

#### 3. Network Connection Error
**Error:** `Network Error: Network connection failed`

**Solution:**
- Check your internet connection
- Verify the GLEC API is accessible
- Check firewall settings

#### 4. Validation Error
**Error:** `Validation Error: Invalid input parameters`

**Solution:**
- Check parameter types and values
- Ensure required parameters are provided
- Verify parameter ranges and formats

### Debug Mode

Enable debug logging to troubleshoot issues:

```json
{
  "env": {
    "LOG_LEVEL": "debug"
  }
}
```

### Logs

Logs are written to:
- Console output (for real-time debugging)
- `logs/error.log` (error logs)
- `logs/combined.log` (all logs)

## 📊 Performance

### Rate Limits

- **General API calls**: 100 requests/minute
- **Emission calculations**: 50 requests/minute
- **Report generation**: 10 requests/5 minutes
- **Shipper management**: 20 requests/minute

### Response Times

- **Emission calculations**: < 1 second
- **Shipper operations**: < 500ms
- **Report generation**: 5-30 seconds (depending on complexity)

### Caching

The server implements intelligent caching for:
- Emission factor codes
- Shipper information
- API responses (with appropriate TTL)

## 🔒 Security

### Data Protection

- API keys are encrypted at rest
- All API communications use HTTPS
- Sensitive data is redacted from logs
- Request/response data is sanitized

### Authentication

- Supports both GlecApiKey and Bearer token authentication
- Automatic token rotation support
- Secure credential storage

### Audit Logging

- All API calls are logged with correlation IDs
- Security events are tracked
- Audit trail for compliance

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Documentation**: [https://glec.io/docs](https://glec.io/docs)
- **Issues**: [GitHub Issues](https://github.com/glec-io/mcp-server/issues)
- **Email**: support@glec.io
- **Discord**: [GLEC Community](https://discord.gg/glec)

## 🙏 Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification
- [Anthropic](https://anthropic.com/) for Claude Desktop
- [GLEC](https://glec.io/) for the emission calculation API

---

Made with ❤️ by the GLEC team