{ "state_left": [ {"ts": 1786343456770, "value": "ON"} ] } ``` ต้องแปลงเป็น `{ state_left: "ON" }` โดย: - เลือก entry ที่ `ts` **มากที่สุด** ไม่ใช่ index 0 (`entries.reduce((a,b) => b.ts >= a.ts ? b : a)`) - key ที่ array ว่าง → ข้ามไปเลย ไม่ใส่เป็น `undefined` - **ส่งค่าดิบออกไปตรง ๆ** return type เป็น `Record` โดยเจตนา การตีความเป็นหน้าที่ของ `parseTbBoolean` เท่านั้น ถ้าชั้นนี้แปลงเป็น boolean เอง จะทำลายความสามารถในการปฏิเสธค่าที่ไม่รู้จัก Picks the entry with the greatest `ts`, skips keys with empty arrays, and passes the raw value through untouched. The `unknown` return type is deliberate: interpretation belongs to `parseTbBoolean` alone. **4. login แบบ lazy + 401 = login ใหม่ 1 ครั้ง ลองซ้ำ 1 ครั้ง ไม่วนลูป** ``` เรียกครั้งแรก / first call → ยังไม่มี token → login → ยิง request 401 กลางทาง / mid-session 401 → ทิ้ง token → login ใหม่ → ยิงซ้ำ 1 ครั้ง 401 อีกครั้ง / 401 again → ยอมแพ้ + บอกว่า credential ใช้ไม่ได้กับงานนี้ ``` รวมสูงสุด 2 login + 2 request ต่อการเรียก 1 ครั้ง constructor **ไม่ยิง network เลย** (มีเทสต์ assert ว่า 0 request หลังสร้าง object) At most 2 logins and 2 requests per call. The constructor performs zero network I/O. #### ข้อความ error เป็นส่วนหนึ่งของ product / Error messages are a product surface Claude อ่านข้อความพวกนี้แล้วเล่าให้คนที่ต้องไปแก้ปัญหาฟัง จึงต้องบอกว่า**ให้ไปดูที่ไหน**: Claude relays these to a human who has to fix the problem, so each must say what to check: | สถานการณ์ | ข้อความ | |---|---| | 401 ตอน login | `ThingsBoard rejected the credential in TB_USERNAME / TB_PASSWORD. Check your .env file.` | | 401 สองครั้ง | `ThingsBoard returned 401 twice. The credential ... is not valid for this operation.` | | 404 | `ThingsBoard has no device with id "". Check TB_LIGHTING_DEVICE_ID.` | | ต่อไม่ได้ | `Cannot reach ThingsBoard at . It may be unreachable from this machine.` + `cause` | **ห้ามใส่ password หรือ token ลงใน error message เด็ดขาด** Never place the password or token in any error message. ### 5.4 `src/mock.ts` — อุปกรณ์ปลอม implement `LightingClient` เหมือนกันเป๊ะ ใช้ตอนเทสต์ และตอน `TB_MOCK=1` ```ts new MockLightingClient({ initial?: { left: true }, // เริ่มด้วยไฟที่เปิดอยู่ overrides?: { any_on: true }, // บังคับค่า key ให้ชนะค่าที่คำนวณได้ omitKeys?: ["state_right"], // ตัด key ออกจาก response }) mock.state // { left, center, right } mock.calls // [{ method, params }, ...] ทุก RPC เรียงตามลำดับ ไม่ dedup ``` **ความซื่อสัตย์ของ mock สำคัญมาก** เพราะเทสต์ของ `readLighting`/`setLighting` พิสูจน์ความถูกต้องบนมันทั้งหมด ถ้า mock โกหก เทสต์จะผ่านโดยพิสูจน์เรื่องที่ผิด ดังนั้น: Mock fidelity is critical: the correctness proofs for `readLighting`/`setLighting` all rest on it. If the mock lies, those tests pass while proving the wrong thing. Therefore: - `state_all` / `any_on` **คำนวณสดทุกครั้งที่อ่าน** ไม่เก็บไว้ (ไม่มีโอกาส drift) derived fresh on every read, never stored - `overrides` มีไว้เพื่อ**สร้างสถานการณ์ที่อุปกรณ์ขัดแย้งกับตัวเอง** สำหรับทดสอบ cross-check exists to manufacture self-contradicting device data for cross-check tests - `calls` บันทึก RPC **ทุกตัวรวมทั้งตัวที่ผิด** ไม่ dedup ไม่เรียงใหม่ — เพราะเทสต์ต้องพิสูจน์ว่า "ครบ 3 ดวงยิงครั้งเดียว" ด้วย `calls.length` records every RPC including invalid ones, so `calls.length` can prove the one-call-not-three behaviour - method ที่ไม่รู้จัก → `throw` (firmware จริงก็ไม่รับ) unknown method throws, as the real firmware would ### 5.5 `src/index.ts` — MCP wiring ชั้นบางที่สุด ไม่มีตรรกะธุรกิจเลย / The thinnest layer, zero business logic. ```ts const config = loadConfig(process.env); // ตายก่อน client ต่อ / fail fast const client = config.mock ? new MockLightingClient() : new ThingsBoardClient(config); const server = new McpServer({ name: "thingsboard-lighting", version: "1.0.0" }); server.registerTool("get_lighting", {...}, handler); server.registerTool("set_lighting", {...}, handler); await server.connect(new StdioServerTransport()); ``` #### ★ stdout เป็นช่อง JSON-RPC — ห้ามเขียนอะไรลงไป **`console.log` ตัวเดียวทำโปรโตคอลเสีย** และอาการที่เห็นจะเหมือน client เป็นฝ่ายผิด ทุกข้อความ diagnostic ต้องไป `console.error` (stderr) รวมทั้งบรรทัดแจ้งว่า server ขึ้นแล้วและบรรทัดแจ้ง `TB_MOCK` A single `console.log` corrupts the protocol and presents as a client bug. Every diagnostic goes to `console.error`. มีเทสต์คุมเรื่องนี้ (`test/index.handshake.test.ts`) ที่ตรวจ **ทุกบรรทัด** ของ stdout ว่า parse เป็น JSON-RPC ได้ บรรทัดที่ parse ไม่ได้ = เทสต์ fail (เคยเขียนผิดเป็น filter ทิ้งบรรทัดที่ไม่ขึ้นต้นด้วย `{` ซึ่งทำให้เทสต์ไม่มีทาง fail เลย — แก้แล้วและพิสูจน์ด้วยการแอบใส่ `console.log` ให้เทสต์ fail จริงก่อน) A test guards this by checking **every** stdout line parses as JSON-RPC; a non-parsing line fails the test. (It was originally written to filter out lines not starting with `{`, which made it unable to fail at all. Fixed, and proven by deliberately injecting a `console.log` and watching it fail.) #### ด่าน zod คือรั้วจริง / The zod enum is the real fence ```ts inputSchema: z.object({ lights: z.array(z.enum(["left", "center", "right"])).min(1), on: z.boolean(), }) ``` `setLighting` เชื่อ type `readonly LightId[]` แค่ตอน compile — string แปลก ๆ ที่หลุดมาจาก JSON จะถูก**ทิ้งเงียบ ๆ** ไม่ได้ถูกปฏิเสธ ด่าน zod ที่นี่คือสิ่งที่ทำให้เป็นไปไม่ได้ **ห้ามลดเป็น `z.string()`** ทดลองแล้ว: ส่ง `lights: ["ceiling"]` → ได้ ``` Input validation error: Invalid arguments for tool set_lighting: lights.0: Invalid option: expected one of "left"|"center"|"right" ``` `setLighting` trusts its type at compile time only; a stray string from JSON would be silently dropped rather than rejected. This enum is what makes that impossible. Do not weaken it to `z.string()`. #### annotations เป็นป้ายบอก ไม่ใช่รั้ว / Annotations are labels, not fences MCP spec เขียนว่า clients **MUST** consider tool annotations to be untrusted ดังนั้นค่าเหล่านี้บอกเจตนาให้ UI ของ client รู้ ไม่ได้บังคับอะไรเลย: | tool | annotations | ทำไม / why | |---|---|---| | `get_lighting` | `readOnlyHint: true`, `openWorldHint: true` | อ่านเท่านั้น, แตะระบบภายนอก | | `set_lighting` | `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: true` | `destructiveHint: false` เพราะเปิด/ปิดไฟย้อนกลับได้ · `idempotentHint: true` เพราะสั่งเปิดซ้ำผลเท่าเดิม | รั้วจริงคือ: server นี้มี tool แค่ 2 ตัว ผูก device id เดียวจาก config และ **ไม่มี generic RPC passthrough** (ตอนออกแบบมีคนเสนอ `thingsboard_rpc(deviceId, method, params)` และถูกปฏิเสธเพราะไม่มีขอบเขต) The real fence: exactly 2 narrow tools against one fixed device id, and no generic RPC passthrough (proposed during design and rejected as unbounded). #### `ok()` / `fail()` ```ts function ok(status) { return { content: [{type:"text", text: describeLighting(status)}], structuredContent: status }; } function fail(error) { return { content: [{type:"text", text: message}], isError: true }; } ``` `isError: true` คือ *tool execution error* ตาม MCP spec — spec แนะให้ client ส่งต่อให้ model เพื่อให้แก้ตัวเองได้ **ไม่ปล่อย stack trace ออกไป และไม่ทำให้ server ตาย** `isError: true` is a *tool execution error*; the spec says clients SHOULD feed these to the model so it can self-correct. No stack trace escapes and the server never crashes. --- ## 6. สัญญาของ MCP tools / MCP tool contracts ### `get_lighting` ```jsonc // input — ไม่รับ argument / takes no arguments {} // output { "content": [{ "type": "text", "text": "3 of 3 lights are on: left, center, right." }], "structuredContent": { "onCount": 3, // นับจาก 3 key เดี่ยว / from the 3 individual keys "total": 3, "lights": { "left": true, "center": true, "right": true }, "reported": { "state_all": true, "any_on": true }, // ค่าสรุปที่อุปกรณ์รายงาน "consistent": true, // false = ขัดแย้งกัน / contradictory "warnings": [] } } ``` ### `set_lighting` ```jsonc // input { "lights": ["left"], // 1-3 ตัว จาก "left" | "center" | "right" ห้ามซ้ำ ห้ามว่าง "on": false // true = เปิด / false = ปิด } // output — structuredContent เหมือน get_lighting แต่เป็นค่าที่อ่านได้ *หลัง* สั่ง // same shape as get_lighting, but read AFTER the command { "content": [{ "type": "text", "text": "2 of 3 lights are on: center, right." }], "structuredContent": { "onCount": 2, ... } } ``` --- ## 7. ข้อมูลอ้างอิงของ ThingsBoard / ThingsBoard reference ทุกค่าในหัวข้อนี้ยืนยันจาก `/v3/api-docs` ของ instance จริง หรือจากการอ่าน/เขียนของจริง — ไม่ใช่จากความจำ Every value here was verified against the live instance's own OpenAPI document or by real reads/writes. | รายการ | ค่า | |---|---| | Instance | `https://thingsboard.syntechnology.com` (self-hosted, **ไม่ใช่** `thingsboard.cloud`) | | REST API version | `3.9.0` | | Auth header | `X-Authorization: Bearer ` | | Login | `POST /api/auth/login` → `{ token, refreshToken }` | | Telemetry (ล่าสุด) | `GET /api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries?keys=...` | | Telemetry (ประวัติ) | เพิ่ม `&startTs=&endTs=&limit=` | | RPC | `POST /api/plugins/rpc/oneway/{deviceId}` | | RPC body | `{ "method": "setStateLightLeft", "params": true }` | **หมายเหตุเรื่อง `startTs`/`endTs`:** OpenAPI ของ instance นี้ mark ทั้งสองเป็น `required` บน path ของ latest-value ด้วย **แต่ใช้งานได้จริงโดยไม่ต้องส่ง** สาเหตุคือ Spring ผูก handler สองตัวไว้ path เดียวกัน แล้ว generator รวมเป็น operation เดียว ยืนยันด้วยการยิงจริงแล้ว The instance's OpenAPI marks both as `required` on the latest-values path, but it works without them. That is an artifact of two Spring handlers sharing one path being merged into a single operation. Verified empirically. ### telemetry keys ของอุปกรณ์นี้ / this device's telemetry keys | key | ความหมาย | ใช้ทำอะไร | |---|---|---| | `state_left` | ไฟดวงซ้าย | **นับ** / counted | | `state_center` | ไฟดวงกลาง | **นับ** / counted | | `state_right` | ไฟดวงขวา | **นับ** / counted | | `state_all` | ไฟครบ 3 ดวงหรือไม่ | cross-check เท่านั้น / cross-check only | | `any_on` | มีไฟเปิดอย่างน้อย 1 ดวงหรือไม่ | cross-check เท่านั้น / cross-check only | ค่าที่อุปกรณ์ส่ง: **`"ON"` / `"OFF"` (string) เท่านั้น** สังเกตจากสายจริงทั้งสองค่าเมื่อ 2026-08-10 Values sent by the device: the strings `"ON"` and `"OFF"` only. Both observed on the wire. > `enum BaseLighting` ใน frontend เดิมมี key ชื่อ `state` ด้วย — **ไม่ใช้ในงานนี้** และอุปกรณ์จริงก็ไม่ได้ส่ง key นั้นมาเลย (ตรวจด้วย `GET .../keys/timeseries` แล้ว) > The frontend's `enum BaseLighting` also lists a `state` key. It is out of scope here, and the real device does not report it at all. --- ## 8. การตั้งค่า / Configuration ```bash TB_BASE_URL=https://thingsboard.syntechnology.com TB_USERNAME= TB_PASSWORD= TB_LIGHTING_DEVICE_ID= TB_MOCK=0 # 1 = ใช้อุปกรณ์ปลอม ไฟจริงไม่ขยับ / use the mock, no real lights move ``` **กฎเรื่องความปลอดภัย / Security rules:** - `.env` อยู่ใน `.gitignore` แล้ว — **ห้าม commit** - `.env.example` เก็บ**ชื่อ key เท่านั้น ไม่มีค่า** อย่าเผลอกรอกค่าจริงลงไปเพราะไฟล์นี้ git ติดตามอยู่ (`.gitignore` มี `!.env.example` ยกเว้นไว้) - ตรวจก่อน commit ทุกครั้ง: `git check-ignore -v .env` ต้องมี output - `.env` is gitignored — never commit it. - `.env.example` holds **key names only**. Do not fill in real values there: that file IS tracked by git (`.gitignore` has `!.env.example`). ### หา `TB_LIGHTING_DEVICE_ID` / Finding the device id ```bash TOKEN=$(curl -s -X POST https://thingsboard.syntechnology.com/api/auth/login \ -H 'Content-Type: application/json' \ -d '{"username":"YOUR_USER","password":"YOUR_PASS"}' \ | python -c "import json,sys; print(json.load(sys.stdin)['token'])") curl -s "https://thingsboard.syntechnology.com/api/tenant/devices?pageSize=100&page=0" \ -H "X-Authorization: Bearer $TOKEN" \ | python -c "import json,sys; [print(d['id']['id'], d['name']) for d in json.load(sys.stdin)['data']]" ``` --- ## 9. ต่อกับ Claude Desktop / Connecting Claude Desktop ### ⚠️ หา config ไฟล์ให้ถูกก่อน / Find the right config file first **ไทย** — ถ้า Claude Desktop ลงมาจาก **Microsoft Store (MSIX)** AppData ของมันถูก virtualize ทำให้ **ไม่ได้อ่าน** `%APPDATA%\Claude\` ตามที่เอกสารทั่วไปบอก ไฟล์จริงอยู่ที่: ``` %LOCALAPPDATA%\Packages\Claude_\LocalCache\Roaming\Claude\claude_desktop_config.json ``` เครื่องนี้คือ `Claude_pzs8sxrjxfjjc` การแก้ไฟล์ path ที่เอกสารบอกจะดู "สำเร็จ" แต่ไม่มีผลอะไรเลย **วิธีจับว่าแก้ผิดไฟล์:** ดู prefix ใน log ของ Claude Desktop มันจะเป็นชื่อ server จาก config ที่มันอ่าน**จริง** ถ้าไม่ตรงกับชื่อที่เพิ่งเขียนไป = ผิดไฟล์ **English** — if Claude Desktop came from the **Microsoft Store (MSIX)** build, its AppData is virtualized and it does **not** read `%APPDATA%\Claude\`. The real file is under `%LOCALAPPDATA%\Packages\Claude_\LocalCache\Roaming\Claude\`. Editing the documented path appears to succeed and changes nothing. **The tell:** Claude Desktop's log prefixes each line with the server name from the file *it* actually read — a mismatch means you edited the wrong file. ### รูปแบบ config / Config shape ```jsonc { "mcpServers": { "lighting": { "command": "node", "args": ["C:\\Users\\\\mcp-server-test\\build\\src\\index.js"], "env": { "TB_BASE_URL": "https://thingsboard.syntechnology.com", "TB_USERNAME": "...", "TB_PASSWORD": "...", "TB_LIGHTING_DEVICE_ID": "...", "TB_MOCK": "0" } } } }

ThingsBoard Lighting MCP Server

Installation