AI导哈

TTLock管理协议服务器

一个用于通过MCP兼容客户端（如VS Code、MCP Inspector等）访问和管理TTLock数据的服务器，支持OAuth认证、锁管理、IC卡操作及解锁记录读取。

  • by etxahun
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 etxahun/ttlock-mcp

使用说明

🔒 TTLock MCP

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

📁 目录

🏗️ 架构和存储库布局

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：

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" }
  2. auth.login （如果您没有配置自动登录）：
    { "username": "YOUR_EMAIL", "passwordMd5": "32_char_lowercase_md5" }
  3. 锁匠
    { "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<{cardNumber, cardName?, startDate?, endDate?}>, 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下获得许可。

相关 MCP