mcp-thai-proofread

MCP server สำหรับตรวจและแก้คำสะกดภาษาไทยในไฟล์ Markdown หรือข้อความ ด้วย LLM ที่เรียกผ่าน endpoint แบบ OpenAI-compatible (OpenRouter, vLLM, Ollama ฯลฯ) แก้เฉพาะการสะกด ไม่เรียบเรียงใหม่ และมีกฎตรวจคำตอบของ LLM อีกชั้น เพื่อกันไม่ให้ตัวเลข รหัส URL หรือโครงสร้างเอกสารเปลี่ยน

ให้ AI agent ที่รองรับ MCP (เช่น Hermes) เรียกใช้ผ่าน streamable HTTP ที่ http://<host>:8800/mcp

ผู้พัฒนา: Chacharin Lertyosbordin

เครื่องมือ

<โฟลเดอร์> ตั้งด้วย OUTPUT_PLACEMENT: file (ค่าเริ่มต้น) = โฟลเดอร์เดียวกับไฟล์ที่แก้ · top = โฟลเดอร์ชั้นแรกใต้ workspace (รวมไว้ที่เดียวต่อหนึ่งโปรเจกต์) ชื่อโฟลเดอร์ย่อยเปลี่ยนได้ด้วย BACKUP_SUBDIR และ NOTES_SUBDIR (ตั้ง NOTES_SUBDIR ว่าง = ไม่เขียนบันทึก ส่วนไฟล์สำรองปิดไม่ได้)

Related MCP server: SpellChecker MCP Server

หลักการทำงาน

1. หา path อย่างปลอดภัย — ตัด prefix ที่ agent อาจใส่มา (PATH_PREFIXES) บังคับให้ไฟล์อยู่ใน workspace และรับเฉพาะนามสกุลที่อนุญาต (FILE_EXTENSIONS)

2. หั่นเอกสาร — ขึ้นช่วงใหม่ทุกหัวข้อ หรือเมื่อเกิน CHUNK_CHARS ตัวอักษร ข้ามบล็อกโค้ดและบรรทัดที่ไม่มีภาษาไทย (ไม่ส่งไป LLM)

3. แนบบริบท — ชื่อเอกสาร ลำดับหัวข้อ และ CONTEXT_LINES บรรทัดก่อนและหลัง (LLM อ่านได้แต่ไม่แก้)

4. เรียก LLM — ส่งพร้อมกัน WORKERS ช่วง ลองใหม่เมื่อเจอ 429 หรือ 5xx ถ้า LLM คืนจำนวนบรรทัดไม่ตรง จะหั่นช่วงครึ่งแล้วส่งใหม่

5. ตรวจทีละบรรทัด — ไม่รับการแก้ (คงข้อความเดิมและบันทึกเหตุผล) ถ้า

   • ตัวเลข, URL, คำภาษาอังกฤษ, รหัสที่ตรงกับ PROTECTED_REGEX, จำนวน | หรือ ** หรือเครื่องหมายหัวข้อและรายการ เปลี่ยนไป

   • หรือบรรทัดเปลี่ยนไปมากกว่าเกณฑ์ MIN_SIMILARITY

6. เขียนผล — สำรองไฟล์เดิมก่อนเขียนทับ แล้วบันทึกว่าแก้บรรทัดไหน และไม่รับการแก้บรรทัดไหน เพราะอะไร

เริ่มใช้งาน

สิ่งที่ต้องมี

• Docker ที่เปิด BuildKit — Docker Desktop และ Docker Engine 23.0 ขึ้นไปเปิดเป็นค่าเริ่มต้นแล้ว ถ้า build แล้วเจอ the --mount option requires BuildKit ให้อัปเดต Docker หรือสั่ง build ด้วย DOCKER_BUILDKIT=1 docker compose build

• อินเทอร์เน็ตตอน build ครั้งแรก — ดึง python:3.12-slim, image ของ uv และไลบรารีจาก PyPI (ถ้าองค์กรปิดอินเทอร์เน็ต ต้องใช้ mirror ภายใน)

• LLM endpoint แบบ OpenAI-compatible พร้อม API key (ถ้า endpoint ต้องใช้)

ไม่ต้องติดตั้ง Python หรือ uv บนเครื่อง — Dockerfile ยืม uv รุ่นที่ระบุไว้มาติดตั้งไลบรารีตาม uv.lock ระหว่าง build แล้วไม่เก็บไว้ใน image ทุกคนจึงได้ไลบรารีเวอร์ชันเดียวกัน

ติดตั้ง

git clone https://github.com/chacharin/mcp-thai-proof-md.git
cd mcp-thai-proof-md
cp .env.example .env          # แล้วแก้ LLM_BASE_URL / LLM_API_KEY / LLM_MODEL
mkdir -p workspace            # วางไฟล์ที่ต้องการตรวจไว้ที่นี่ (หรือชี้ไปที่อื่นด้วย WORKSPACE_HOST_DIR)
docker network create agent_network   # ครั้งแรกครั้งเดียว — ชื่ออื่นตั้งได้ด้วย DOCKER_NETWORK
docker compose up -d --build
curl http://127.0.0.1:8805/health

ถ้า /health ตอบ "ok": false ให้ดูรายการ problems ในคำตอบ เช่น ยังไม่ได้เปลี่ยน LLM_API_KEY จากค่าตัวอย่าง หรือ workspace ยังไม่ถูก mount

.env ใส่เฉพาะค่าในหมวด "ต้องตั้ง" และค่าที่ต้องการให้ต่างจากค่าเริ่มต้น ส่วน .env.example เป็นคู่มือของทุกค่า ค่าเริ่มต้นในโค้ดเป็นกลาง ไม่ผูกกับ agent หรือองค์กรใด

ทดสอบด้วยการเรียก LLM จริงหนึ่งครั้ง:

docker exec mcp-thai-proofread /app/.venv/bin/python -m app.selftest
docker exec mcp-thai-proofread /app/.venv/bin/python -m app.selftest --file report.md   # ตรวจไฟล์จริงแบบไม่เขียน

ค่าตั้งทั้งหมดและคำอธิบายอยู่ใน .env.example แก้ .env แล้วสั่ง docker compose up -d (ไม่ต้อง build ใหม่)

เชื่อมกับ MCP client

ตัวอย่างสำหรับ Hermes (config.yaml):

mcp_servers:
  thai_proofread:
    url: http://mcp-thai-proofread:8800/mcp
    timeout: 900          # ไฟล์ยาวใช้เวลาหลายนาที อย่าตั้งต่ำกว่า LLM_TIMEOUT_SECONDS
    connect_timeout: 60

ถ้า timeout ของ client สั้นกว่าเวลาที่ใช้ตรวจจริง client จะรายงานว่าล้มเหลว ทั้งที่ server ยังแก้ไฟล์ต่ออยู่เบื้องหลัง

ถ้า agent อ้างถึงไฟล์ด้วย path ของเครื่องตัวเอง (เช่น Hermes ส่ง /opt/data/workspace/report.md) ให้ตั้ง PATH_PREFIXES=/opt/data/workspace/ เพื่อให้ระบบตัด prefix นั้นออก ส่วน uid/gid (RUN_UID, RUN_GID) ควรตรงกับเจ้าของ workspace ของ agent

ตัวเลือกเฉพาะของผู้ให้บริการ LLM (เช่น top_p หรือการเลือก provider ของ OpenRouter) ส่งผ่าน LLM_EXTRA_PARAMS เป็น JSON ได้โดยไม่ต้องแก้โค้ด

ปรับ prompt ให้เข้ากับงาน

prompt ในตัวเป็นแบบทั่วไป (เนื้อหาเดียวกับ prompts/system_prompt.example.md) ถ้าต้องการปรับ:

cp prompts/system_prompt.example.md prompts/system_prompt.md   # แล้วแก้ไฟล์นี้
echo "SYSTEM_PROMPT_FILE=/app/prompts/system_prompt.md" >> .env
docker compose up -d

prompt ต้องยังสั่งให้ LLM คืนเฉพาะบรรทัดที่ต้องตรวจ จำนวนเท่าเดิม เรียงตามเดิม และไม่มีคำอธิบาย ไม่อย่างนั้นการแก้จะถูกปฏิเสธทั้งช่วง ไฟล์ใน prompts/ ที่ไม่ใช่ *.example.md จะไม่ถูก commit (อาจมีชื่อองค์กร)

ความปลอดภัย

• workspace ถูก mount แบบเขียนได้ เพราะเครื่องมือแก้ไฟล์ให้ ทุกการแก้มีไฟล์สำรองเสมอ

• ค่าเริ่มต้นเปิดพอร์ต 8805 ให้เครื่องอื่นในเครือข่ายเรียกได้ (PUBLISH_ADDR=0.0.0.0) ถ้าไม่ได้ตั้ง MCP_AUTH_TOKEN ใครในเครือข่ายก็สั่งแก้ไฟล์ได้ ควรตั้ง token หรือเปลี่ยนเป็น PUBLISH_ADDR=127.0.0.1

• API key ของ LLM อยู่ใน .env เท่านั้น และไม่ถูกส่งกลับไปให้ client

พัฒนาต่อ

ชุดทดสอบไม่เรียก LLM จริง (ใช้ LLM จำลอง) จึงไม่เสียค่า API รันได้ 2 วิธี

ถ้ามี uv บนเครื่อง:

uv run pytest

ถ้าไม่มี uv ให้รันผ่าน Docker (ไม่สร้างไฟล์ใด ๆ ในโฟลเดอร์โปรเจกต์):

docker run --rm -v "$PWD:/w" -w /w -e UV_PROJECT_ENVIRONMENT=/tmp/venv python:3.12-slim \
  sh -c "pip install -q uv==0.13.1 && uv run --frozen pytest -q -p no:cacheprovider"

บน PowerShell ใช้ ${PWD} แทน $PWD และขึ้นบรรทัดใหม่ด้วย ` แทน \

เพิ่มหรืออัปเดตไลบรารี: แก้ pyproject.toml แล้วสั่ง uv lock และ commit uv.lock ที่ได้ไปด้วย

สัญญาอนุญาต

MIT © 2026 Chacharin Lertyosbordin