Ttlock MCP

🔒 TTLock MCP

一 MCP（模型上下文协议） 用于访问和管理的服务器 TTLock 来自MCP兼容客户端（VS Code、MCP Inspector等）的数据。\ 它支持OAuth、锁管理、IC卡操作（添加/删除/列表、批量）和读取解锁记录。

______________________________________________________________________

📁 目录

• 架构和存储库布局
• 需求
• 安装
• 配置

- .env - VS代码(.vscode/mcp.json)

• 运行和测试

- MCP检查员 - VS代码

• 工具目录（MCP）
• TTLock集成说明
• 故障排除
• 安全与最佳实践
• 路线图
• 许可证

______________________________________________________________________

🏗️ 架构和存储库布局

ttlock-mcp/
├─ src/
│  ├─ env.ts          # Loads/validates environment variables (.env) with zod
│  ├─ server.ts       # MCP server (STDIO) + tool definitions (with auth guard)
│  └─ ttlock.ts       # TTLock HTTP client (OAuth + v3 endpoints)
├─ dist/              # Compiled output (tsc)
├─ .vscode/
│  └─ mcp.json        # VS Code config to launch the MCP server
├─ .env               # Local environment variables (DO NOT commit)
├─ package.json
├─ tsconfig.json
└─ README.md          # This document

技术亮点

• Node.js 20+ 随着 ESM (moduleResolution: "NodeNext")
• TypeScript
• @模型上下文协议/sdk （STDIO服务器）
• 轴, 质量保证, 动物圈, dotenv
• *（可选）* dotenv cli 加载 .env 对于Inspector命令

NodeNext/ESM注释： 使用 .js 扩展 在……里面 相对进口 即使在 .ts 文件\ （例如。 import { Env } from './env.js').

______________________________________________________________________

📋 需求

• Node.js >= 20
• TTLock云凭据： clientId, clientSecret
• TTLock 网关在线 用于远程操作（解锁/锁定和IC卡添加/删除）

______________________________________________________________________

🛠️ 安装

# 1) Install deps
npm install

# 2) (optional) Convenient for Inspector to auto-load .env
npm i -D dotenv-cli

# 3) Build once
npm run build

______________________________________________________________________

⚙️ 配置

🔐 .env

创建一个 .env repo根目录下的文件：

TTLOCK_CLIENT_ID=xxxxxxxx
TTLOCK_CLIENT_SECRET=xxxxxxxx
TTLOCK_API_BASE=https://api.sciener.com
MCP_SERVER_NAME=ttlock-mcp

# Optional: auto-login on first use
TTLOCK_USERNAME=your_ttat_account_or_email
TTLOCK_PASSWORD_MD5=32_char_lowercase_md5_of_your_password

在Linux上获取MD5： ``bash echo -n 'your_password' | md5sum | awk '{print $1}' ``

💻 VS代码(.vscode/mcp.json)

建议的工作区配置：

{
  "servers": {
    "ttlock-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/server.js"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

这让VS Code启动服务器并加载您的 .env 自动。

______________________________________________________________________

📜 NPM脚本

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js",
    "watch": "tsc -w",
    "inspect": "dotenv -e .env -- npx @modelcontextprotocol/inspector node dist/server.js"
  }
}

如果你不使用 dotenv-cli，通过Inspector UI或shell环境传递变量。

______________________________________________________________________

🧪 运行和测试

🔍 MCP检查员

npm run build
npm run inspect

检查器UI设置：

• 运输类型： STDIO
• 命令： node
• 论据： dist/server.js

快速测试：

1. 拼

   { "text": "hello" }

1. auth.login （如果您没有配置自动登录）：

   { "username": "YOUR_EMAIL", "passwordMd5": "32_char_lowercase_md5" }

1. 锁匠

   { "pageNo": 1, "pageSize": 50 }

💻 VS代码

• 使用打开项目（WSL或本地） code ..
• 随着 mcp.json 上面，打开 聊天 视图（副驾驶）。\

这 ttlock mcp 服务器出现，工具可用。

• 直接调用工具（例如，选择 locks.list 或类型 #locks.list).

______________________________________________________________________

🧪 工具目录（MCP）

所有处理程序返回 CallToolResult ({ content: [{ type: "text", text }] }).\ 标记有的工具🔒 需要身份验证（如果 TTLOCK_USERNAME 和 TTLOCK_PASSWORD_MD5 存在于 .env).

🔑 认证

• auth.login { username: string, passwordMd5: string }
• auth.refresh {}

🔒 锁定

• 🔒 locks.list { pageNo?: number=1, pageSize?: number=50 }
• 🔒 locks.detail { lockId: number }
• 🔒 locks.unlock { lockId: number } *（需要网关联机）*
• 🔒 locks.lock { lockId: number } *（需要网关联机）*

🪪 IC卡

• 🔒 cards.list { lockId: number, pageNo?: number=1, pageSize?: number=50 }
• 🔒 cards.add { lockId: number, cardNumber: string, cardName?: string, startDate?: ms, endDate?: ms }\

如果 startDate/endDate 省略（或 0)，这张卡是永久性的。

• 🔒 cards.bulkAdd\

{ lockId: number, cards: Array, delayMs?: 0–5000, continueOnError?: boolean }

• 🔒 cards.delete { lockId: number, cardId: number, deleteType?: 1|2|3=2 }
• 🔒 cards.bulkDelete { lockId: number, cardIds: number[], deleteType?: 1|2|3=2, delayMs?: 0–5000, continueOnError?: boolean }
• 🔒 cards.clear { lockId: number, confirm?: boolean=false }\

⚠️ 删除 全部 锁上的卡片。

cardId与卡号： 删除需要 cardId （通过以下方式获取 cards.list).\ deleteType: 2 = 网关 （远程）最有用； 1 =BLE； 3 =NB-IoT（如适用）。

📋 解锁记录（访问日志）

• 🔒 records.list\

{ lockId: number, pageNo?: number=1, pageSize?: number=50, startDate?: ms, endDate?: ms }

时间格式： startDate/endDate 是 历元毫秒（UTC）.\ 示例（马德里CEST，今天06:00–10:00）： startDate=1756699200000, endDate=1756713600000.

______________________________________________________________________

🔗 TTLock集成说明

• OAuth： 登录使用 username + passwordMd5 （32个字符，小写）。
• date 参数（v3 API）： 每次呼叫都会发送 date = Date.now().TTLock服务器接受大约±5分钟。\

如果你看到 date must be current time, in 5 minutes，同步您的系统时钟（NTP）。\ 客户端还支持使用服务器时间偏移（来自HTTP）重试 Date 头部）以减轻小漂移。

• 网关： 远程操作（解锁/锁定、添加/删除卡）需要兼容 网关在线.
• ESM： 保持相对进口以 .js.

______________________________________________________________________

🧯 故障排除

• date must be current time, in 5 minutes\

您的机器时钟已关闭。启用NTP：

  timedatectl set-ntp true
  sudo systemctl restart systemd-timesyncd

• 未认证\

跑 auth.login 或设置 TTLOCK_USERNAME 和 TTLOCK_PASSWORD_MD5 在……里面 .env.

• 网关脱机/不支持\

确保您的锁/网关支持该操作并且处于联机状态。

• 检查器“找不到命令”\

检查 命令 = node, 参数 = dist/server.js，并且你构建了这个项目。

• ESM导入错误\

确保相对进口以 .js 和 tsconfig.json 用途 moduleResolution: "NodeNext".

______________________________________________________________________

🗺️ Roadmap

• 在磁盘（缓存）上持久/旋转令牌。
• 网络钩子 锁定记录通知 实时事件。
• 更多的管理端点（重命名卡、更改有效性窗口等）。
• 测试和剥皮（Vitest/ESLint）。

______________________________________________________________________

📄 许可证

此项目在Apache-2.0下获得许可。