# 🇲🇲 Myanmar MCP Server

<div align="center">

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![Node.js 18+](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)

**A Model Context Protocol (MCP) server with built-in animation system for Myanmar applications**

</div>

---

## ✨ Features

| Feature | Description |
|---------|-------------|
| **🤖 MCP Protocol** | Full MCP SDK implementation with stdio transport |
| **🎬 Animation System** | Timeline-based animation engine with keyframes & triggers |
| **🔧 Extensible Tools** | GitHub integration, filesystem operations, custom tools |
| **📦 TypeScript** | Full type safety with strict mode |
| **🧪 Testing** | Jest test suite with coverage reports |
| **🐳 Docker** | Containerized deployment ready |

---

## 🚀 Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/amkyawdev/myanmar-mcp-server.git
cd myanmar-mcp-server

# Install dependencies
npm install

# Build for production
npm run build
```

### Development

```bash
# Run with hot reload
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format
```

---

## ⚙️ Configuration

Create a `.env` file from the example:

```bash
cp .env.example .env
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | `3000` |
| `HOST` | Server host | `localhost` |
| `LOG_LEVEL` | Logging level (`debug`, `info`, `warn`, `error`) | `info` |
| `GITHUB_TOKEN` | GitHub API token | - |
| `ENABLE_ANIMATION` | Enable animation system | `true` |
| `ENABLE_FILESYSTEM` | Enable filesystem tools | `true` |
| `ENABLE_GITHUB` | Enable GitHub tools | `true` |

---

## 🎬 Animation System

The heart of Myanmar MCP Server - a powerful timeline-based animation system.

### Usage Example

```typescript
import { AnimationEngine, getPreset } from './animation';

// Load a preset
const engine = new AnimationEngine();
engine.load(getPreset('bounce'));
engine.play();

// Or load a custom script
engine.load({
  version: '1.0',
  name: 'My Animation',
  tracks: [{
    id: 'opacity',
    property: 'opacity',
    duration: 1000,
    keyframes: [
      { time: 0, value: 0 },
      { time: 1000, value: 1, easing: 'ease-out' }
    ]
  }]
});

engine.play();
```

### Available Presets

| Preset | Description |
|--------|-------------|
| `fadeIn` | Simple opacity fade in |
| `slideInLeft` | Slide from left with fade |
| `bounce` | Bouncy vertical movement |
| `pulse` | Scale pulsing effect |
| `spin` | 360° rotation |
| `typewriter` | Text reveal effect |
| `wave` | Wave-like oscillation |

### Easing Functions

| Function | Use Case |
|----------|----------|
| `linear` | Constant speed |
| `ease-in` | Start slow, end fast |
| `ease-out` | Start fast, end slow |
| `ease-in-out` | Slow start and end |
| `bounce` | Bouncy effect |
| `elastic` | Spring-like motion |

### Triggers

```json
{
  "triggers": [
    { "type": "time", "time": 1000, "action": "onComplete" },
    { "type": "condition", "condition": "progress >= 0.5", "action": "onMidpoint" },
    { "type": "event", "event": "userClick", "action": "pauseAnimation" }
  ]
}
```

### Animation JSON Format

```json
{
  "version": "1.0",
  "name": "My Animation",
  "description": "Animation description",
  "tracks": [
    {
      "id": "unique-track-id",
      "property": "opacity",
      "duration": 2000,
      "keyframes": [
        { "time": 0, "value": 0 },
        { "time": 1000, "value": 1, "easing": "ease-out" }
      ]
    }
  ],
  "triggers": [],
  "metadata": {}
}
```

---

## 🛠️ Available Tools

### GitHub Tool

```json
{
  "action": "get_user",
  "username": "amkyawdev"
}
```

**Actions:** `get_user`, `get_repo`, `list_repos`, `create_issue`

### Filesystem Tool

```json
{
  "action": "read_file",
  "path": "/path/to/file.txt"
}
```

**Actions:** `read_file`, `write_file`, `list_dir`, `create_dir`, `delete`

### Animation Tool

```json
{
  "action": "run_script",
  "script": "{ ... }",
  "output": "console"
}
```

**Actions:** `play`, `stop`, `pause`, `seek`, `get_state`, `list_presets`, `get_preset`, `run_script`

---

## 🐳 Docker

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

# View logs
docker-compose logs -f

# Stop
docker-compose down
```

### Manual Docker Build

```bash
docker build -t myanmar-mcp-server .
docker run -p 3000:3000 --env-file .env myanmar-mcp-server
```

---

## 📁 Project Structure

```
myanmar-mcp-server/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server class
│   ├── tools/                # Tool implementations
│   │   ├── github.tool.ts
│   │   ├── filesystem.tool.ts
│   │   └── index.ts
│   ├── animation/            # Animation system ✨
│   │   ├── engine.ts         # Animation engine
│   │   ├── timeline.ts       # Timeline management
│   │   ├── keyframes.ts      # Keyframe interpolation
│   │   ├── interpolators.ts  # Easing functions
│   │   ├── triggers.ts       # Event triggers
│   │   ├── renderer.ts       # Output renderers
│   │   ├── presets.ts        # Built-in presets
│   │   └── types.ts          # Type definitions
│   ├── types/                # Shared types
│   ├── utils/                # Utilities
│   │   ├── logger.ts
│   │   └── config.ts
│   ├── middleware/            # Request middleware
│   ├── errors/                # Error classes
│   ├── validators/            # Zod schemas
│   └── services/              # Business logic
├── tests/                     # Test files
├── examples/                  # Animation examples
├── dist/                      # Build output
└── package.json
```

---

## 📊 Scripts

| Command | Description |
|---------|-------------|
| `npm run dev` | Development with hot reload |
| `npm run build` | Build for production |
| `npm start` | Run production build |
| `npm test` | Run test suite |
| `npm run test:coverage` | Run with coverage report |
| `npm run lint` | Lint with ESLint |
| `npm run lint:fix` | Auto-fix linting issues |
| `npm run format` | Format with Prettier |
| `npm run typecheck` | TypeScript type checking |

---

## 🧪 Testing

```bash
# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage
```

---

## 👨‍💼 Admin / Maintainer

| Role | Name | GitHub |
|------|------|--------|
| **Owner & Maintainer** | Aung Myat Kyaw | [@amkyawdev](https://github.com/amkyawdev) |

### Responsibilities

- Code review and merge approvals
- Release management
- Security vulnerability handling
- Community support and issue triage

### Contact

- **GitHub Issues:** For bug reports and feature requests
- **Email:** (Coming soon)

---

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 🔒 Security

If you discover a security vulnerability, please report it via:

1. **GitHub Security Advisories** - Preferred method
2. **Email** - (Coming soon)

Please do not disclose security issues publicly until a fix is available.

---

## 📝 License

MIT © 2024 [amkyawdev](https://github.com/amkyawdev)

---

<div align="center">

**Made with ❤️ for Myanmar developers**

</div>