# MCP Starter Server (TypeScript)

MCP server ตัวอย่างที่เขียนด้วย TypeScript ใช้ `@modelcontextprotocol/sdk`

## สถาปัตยกรรมคร่าวๆ

```mermaid
flowchart LR
    U[ผู้ใช้พิมพ์คำถาม] --> C[Claude]
    C -->|เลือกเรียก tool ที่เหมาะสม| E[MCP Starter Extension\n(Node process บนเครื่องนี้)]
    E -->|REST API + token| S[(SonarQube)]
    E -->|REST API + auth key| CV[(Coverity Connect)]
    S -->|Quality Gate / issues| E
    CV -->|projects / streams / defects| E
    E -->|ผลลัพธ์เป็นข้อความ| C
    C -->|สรุปคำตอบ| U
```

## Tools ที่มีให้

| Tool | ใช้ทำอะไร |
|---|---|
| `echo` | ทดสอบว่า server เชื่อมต่อได้ไหม |
| `get_weather` | ตัวอย่างเรียก API สาธารณะ (Open-Meteo) — ไว้ดูโครงสร้างโค้ดเฉยๆ |
| `get_sonar_overview` | ภาพรวมคุณภาพโค้ดจาก SonarQube: Quality Gate, coverage, duplications, security hotspots (New Code + Overall Code) |
| `get_sonar_issues` | รายการ issue ที่ SonarQube ตรวจเจอ กรองตามความรุนแรง/ประเภท/New Code ได้ |
| `list_sonar_projects` | ค้นหา/ดูรายชื่อโปรเจกต์ทั้งหมดใน SonarQube (ใช้ตอนไม่รู้ project key) |
| `list_coverity_projects` | ดูรายชื่อโปรเจกต์ทั้งหมดใน Coverity Connect |
| `list_coverity_streams` | ดูรายชื่อ stream ใน Coverity (ใช้หาชื่อ stream ก่อนค้นหา defect) |
| `get_coverity_issues` | ค้นหา defect ใน stream หนึ่งๆ กรองตาม impact/status ได้ |
| `coverity_debug_request` | [debug] เรียก path ใดๆ ใต้ Coverity API v2 ดิบๆ ใช้ตอน tool อื่น error |

## เตรียม SonarQube token

1. เข้า SonarQube → มุมขวาบน → **My Account** → **Security**
2. สร้าง token ใหม่ (ประเภท *User Token* หรือ *Project Analysis Token* ก็ได้ ขอแค่มีสิทธิ์ **Browse** โปรเจกต์ที่จะดู)
3. copy token เก็บไว้ (จะเห็นครั้งเดียว)


## เตรียม Coverity Connect Auth Key

1. เข้า Coverity Connect → คลิกชื่อผู้ใช้มุมขวาบน → หาเมนู Authentication Keys (หรือ Configuration > Users ถ้าเป็น admin)
2. สร้าง auth key ใหม่ จะได้ไฟล์ JSON ประมาณนี้:
   ```json
   {"key":"xxx","id":10077,"username":"user6","comments":{"host":"coverity2025.pttdigital.com",...}}
   ```
3. เอาค่าไปตั้งเป็น environment variable:
   - `COVERITY_USERNAME` = ค่าใน field `username`
   - `COVERITY_AUTH_KEY` = ค่าใน field `key`
   - `COVERITY_BASE_URL` = URL ของ Coverity Connect เช่น `https://coverity2025.pttdigital.com`

> **หมายเหตุความน่าเชื่อถือ**: Coverity ไม่มีเอกสาร REST API เปิดสาธารณะครบเหมือน SonarQube ทำให้ endpoint/field ใน `src/coverity.ts` เป็นการประกอบร่างจากตัวอย่างที่หาได้ ความมั่นใจปานกลาง — ถ้าเรียก `list_coverity_projects` / `list_coverity_streams` / `get_coverity_issues` แล้ว error ให้ใช้ tool `coverity_debug_request` เรียก path เดียวกันแบบ raw ดู response จริงแล้วเอา error message มาปรับโค้ดต่อ (เหมือนที่เจอกับ SonarQube ตอน `/projects/search` ต้องเปลี่ยนเป็น `/components/search`)

## วิธีรัน

```bash
npm install
cp .env.example .env    # แล้วใส่ SONAR_BASE_URL / SONAR_TOKEN ลงในไฟล์ .env
npm run build
npm start
```

> หมายเหตุ: ตอนรันผ่าน `npm start` ตรงๆ จะไม่มีอะไรเกิดขึ้นถ้าไม่มี MCP client ต่อเข้ามา — server แค่รอรับคำสั่งผ่าน stdio เท่านั้น

### token อ่านมาจากไหน

โค้ดอ่านจาก environment variable `SONAR_BASE_URL` / `SONAR_TOKEN` ล้วนๆ ซึ่งมาได้ 2 ทาง:

- **`npm start`** — ใช้ `node --env-file-if-exists=.env` โหลดไฟล์ `.env` ให้อัตโนมัติ (ต้องใช้ Node 20.12+)
- **ผ่าน MCP client** (Claude Desktop / Claude Code) — client รัน `node dist/index.js` เอง ไม่ผ่าน npm ดังนั้นไฟล์ `.env` จะไม่ถูกโหลด ต้องใส่ค่าในบล็อก `env` ของ config ตามตัวอย่างด้านล่าง

## วิธีทดสอบด้วย MCP Inspector

```bash
npx @modelcontextprotocol/inspector \
  -e SONAR_BASE_URL=https://sonarqube.example.com \
  -e SONAR_TOKEN=your_token_here \
  node dist/index.js
```

จะเปิดหน้าเว็บให้เลือก tool แล้วกรอก `projectKey` (เช่น `manageposition-api`) และ `branch` (เช่น `develop/bau`) ทดสอบเรียกดูผลลัพธ์ได้ทันที

## วิธีเชื่อมกับแอป Claude (แบบ Extension — สำหรับแอปรุ่นใหม่ที่มีหน้า Settings > Extensions)

แอป Claude รุ่นใหม่ (ที่มี Cowork mode) ใช้ระบบ Extension แทนการแก้ไฟล์ config ตรงๆ โปรเจกต์นี้มีไฟล์ `manifest.json` เตรียมไว้ให้แล้ว:

1. `npm install && npm run build` ให้เรียบร้อย (ต้องมี `dist/` และ `node_modules/` ในโปรเจกต์ เพราะตอนโหลดเป็น extension จะไม่รัน `npm install` ให้)
2. เปิดแอป Claude → **Settings → Extensions**
3. กด **"Install unpacked extension"** แล้วเลือกโฟลเดอร์นี้ทั้งโฟลเดอร์ (ที่มี `manifest.json` อยู่ข้างใน)
4. จะมีฟอร์มให้กรอก **SonarQube Base URL** และ **SonarQube Token** — กรอกให้ครบ
5. Enable extension แล้วลองถามในแชทได้เลย

> `manifest.json` เขียนตามสเปก Desktop Extension (DXT) เท่าที่ทราบ ถ้า error ให้ copy ข้อความมาดู จะปรับให้ตรงสเปกจริง

## วิธีเชื่อมกับ Claude Desktop

เปิดไฟล์ config ของ Claude Desktop (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows: `%APPDATA%\Claude\claude_desktop_config.json`) แล้วเพิ่ม:

```json
{
  "mcpServers": {
    "mcp-starter": {
      "command": "node",
      "args": ["D:\\noom\\MCP\\mcp-starter_2\\dist\\index.js"],
      "env": {
        "SONAR_BASE_URL": "https://sonarqube.example.com",
        "SONAR_TOKEN": "your_token_here"
      }
    }
  }
}
```

แล้ว restart Claude Desktop จากนั้นถามได้เลย เช่น "Quality Gate ของ manageposition-api branch develop/bau ผ่านไหม"

## วิธีเชื่อมกับ Claude Code

```bash
claude mcp add mcp-starter \
  --env SONAR_BASE_URL=https://sonarqube.example.com \
  --env SONAR_TOKEN=your_token_here \
  -- node /absolute/path/to/mcp-starter/dist/index.js
```

## โครงสร้างโปรเจกต์

```
src/
  index.ts         - นิยาม tools ทั้งหมด และจุดเริ่มรัน server
  sonarqube.ts     - ฟังก์ชันเรียก SonarQube Web API (แยกออกมาให้ทดสอบ/แก้ง่าย)
  sonar.check.ts   - self-check ของตัวแปลงข้อมูล รันด้วย `npm run check`
```