# mcp-web-calc — MCP server cho LM Studio (không cần API key)

**Phiên bản:** 0.3.0

**6 công cụ tích hợp**
- `search_web` — Tìm web hai tầng (Nhanh: DuckDuckGo HTML → Sâu: Playwright/Bing)
- `fetch_url` — Tải & trích xuất nội dung từ URL/HTML/PDF (Readability + pdf-parse)
- `summarize_url` — Lấy nội dung từ URL rồi tóm tắt ngắn gọn
- `math_eval` — Máy tính chính xác (Number / BigNumber / Fraction)
- `wiki_get` — Lấy tóm tắt 1 trang Wikipedia theo ngôn ngữ
- `wiki_multi` — Lấy tóm tắt Wikipedia theo **nhiều ngôn ngữ** trong một lần gọi

> Không dùng API key. Hoạt động hoàn toàn qua MCP/stdio.

---

## Yêu cầu
- Node.js 18+
- Windows/macOS/Linux
- (Tìm kiếm sâu) **Playwright Chromium**

## Cài đặt
```bash
npm i
npx playwright install chromium   # cần cho 'deep' (Bing/Playwright)
# Dev:
npm run dev
# hoặc build & chạy prod:
npm run build && npm run start
```

## Biến môi trường (khuyến nghị)
Đặt trong LM Studio hoặc `.env`:
```env
USER_AGENT=mcp-web-calc/0.3 (https://local)
HTTP_TIMEOUT=15000       # ms cho mọi yêu cầu mạng
MAX_RESULTS=10           # mặc định cho search_web
LANG_DEFAULT=vi          # ngôn ngữ mặc định
MAX_BYTES=20971520       # giới hạn tải 20MB cho fetch_url
```

> **Bảo vệ SSRF**: `fetch_url` sẽ **chặn** `localhost/127.0.0.1/::1/.local/.localhost`.

---

## Thêm MCP server trong LM Studio
**Settings → Developer → Model Context Protocol (MCP) Servers → Add**

- **Name**: `mcp-web-calc`
- **Command**: `npm`
- **Args**: `run`, `dev`  *(hoặc `start` nếu đã build)*
- **Working directory**: đường dẫn tới thư mục dự án
- **Environment variables**: như ở phần trên

Khi chạy thành công, log sẽ hiện: `mcp-web-calc ready (stdio)…`

---

## Công cụ & cú pháp (tool schema)

### 1) `search_web`
- **Input**
```ts
{ 
  q: string;
  limit?: number;          // default: MAX_RESULTS (env), clamp 1..50
  lang?: string;           // "vi" | "en" | ...
  mode?: "fast"|"deep"|"auto"; // default: "auto"
}
```
- **Output (rút gọn)**
```ts
{
  items: { title: string; url: string; snippet?: string; source: "ddg_html"|"bing_pw" }[];
  modeUsed: "fast"|"deep"|"auto";
  enginesUsed: ("ddg_html"|"bing_pw")[];
  escalated: boolean;      // auto có leo sang deep hay không
  diagnostics?: Record<string, unknown>;
}
```
- **Ví dụ**
```
search_web: { "q": "Node.js LTS release schedule", "mode": "fast", "limit": 5, "lang": "vi" }
```

---

### 2) `fetch_url`
- **Input**
```ts
{ url: string }  // hỗ trợ HTML & PDF
```
- **Output (rút gọn)**
```ts
{
  text: string;
  url: string;
  title?: string;
  byline?: string;
  siteName?: string;
  lang?: string;
  length?: number; // nếu có
}
```
- **Ví dụ**
```
fetch_url: { "url": "https://example.com" }
```

---

### 3) `summarize_url`
- **Input**
```ts
{ url: string }
```
- **Hành vi**
  - Lấy nội dung bằng `fetch_url`, sau đó *thử* gọi model phía server (nếu được LM Studio cấp) để tóm tắt ngắn gọn tiếng Việt.
  - **Fallback**: nếu không gọi được model, trả về tối đa ~2000 ký tự đầu của bài.
- **Ví dụ**
```
summarize_url: { "url": "https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API" }
```

---

### 4) `math_eval`
- **Input**
```ts
{
  expression: string;                      // cú pháp mathjs
  mode?: "number"|"BigNumber"|"Fraction";  // default: "BigNumber"
  precision?: number;                      // default: 64 (khi BigNumber)
}
```
- **Lưu ý**
  - `mathjs` **không có** hàm `integrate`. Dùng `derivative`, `simplify`, ma trận, đơn vị, v.v.
  - Cần lượng giác? Dùng `mode="number"` để có sin/cos… chính xác kiểu số JS.
- **Ví dụ**
```
math_eval: { "expression": "derivative(sin(x)*exp(x), x)", "mode": "number" }
```

---

### 5) `wiki_get`
- **Input**
```ts
{ title: string; lang?: string /* default "vi" */ }
```
- **Output (rút gọn)**
```ts
{ lang: string; title: string; url: string; description?: string; extract?: string; thumbnailUrl?: string }
```
- **Ví dụ**
```
wiki_get: { "title": "Việt Nam", "lang": "vi" }
```

---

### 6) `wiki_multi`
- **Input**
```ts
{
  term: string,                 // thuật ngữ gốc, ví dụ "Cá"
  baseLang?: string,            // mặc định "vi"
  langs?: string[]              // mặc định ["vi","en"]
}
```
- **Output (rút gọn)**
```ts
{
  baseLang: string;
  base: { /* WikiSummary của baseLang */ };
  items: Record<string, WikiSummary | null>; // null nếu không tìm thấy
  resolved: Record<string, { title?: string; source: "base"|"langlinks"|"direct"|"none" }>
}
```
- **Ví dụ**
```
wiki_multi: { "term": "Cá", "baseLang": "vi", "langs": ["vi","en","ja","fr"] }
```

---

## Mẹo kiểm thử nhanh
```text
search_web: { "q": "site:developer.apple.com App Intents", "mode": "deep", "limit": 5, "lang": "vi" }
fetch_url: { "url": "https://example.com" }
summarize_url: { "url": "https://www.python.org/dev/peps/pep-0008/" }
math_eval: { "expression": "inv([[1,2],[3,4]])", "mode": "number" }
wiki_get: { "title": "Lambda calculus", "lang": "en" }
wiki_multi: { "term": "Cá", "baseLang": "vi", "langs": ["vi","en","ja","fr"] }
```

---

## Khắc phục sự cố
- **CAPTCHA / chặn tạm thời**: giảm tần suất, ưu tiên `mode="fast"`, thử lại sau vài phút.
- **Playwright chưa cài**: `npx playwright install chromium`.
- **Timeout / treo khi tải**: tăng `HTTP_TIMEOUT`, hoặc nội dung vượt `MAX_BYTES`.
- **URL nội bộ bị chặn**: đây là chủ đích (SSRF guard).

## Giấy phép
MIT — xem tệp `LICENSE`.