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

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:

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

{ 
  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)

{
  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

{ url: string }  // hỗ trợ HTML & PDF

• Output (rút gọn)

{
  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

{ 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

{
  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

{ title: string; lang?: string /* default "vi" */ }

• Output (rút gọn)

{ 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

{
  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)

{
  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

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.