Metadata-Version: 2.4
Name: mxchip-gateway-mcp
Version: 0.1.0
Summary: MCP server for MXCHIP local gateway (WebSocket)
Author: MXCHIP
License-Expression: MIT
License-File: LICENSE
Keywords: gateway,iot,mcp,mxchip,smart-home
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Requires-Python: >=3.10
Requires-Dist: cryptography>=42.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# mxchip-gateway-mcp

庆科本地网关 MCP Server。通过局域网 WebSocket（`ws://{ip}:53248/ws`）连接网关，提供 MCP Tool 查询与控制子设备、场景。

## 安装

需要 Python 3.10+ 与 [uv](https://docs.astral.sh/uv/)（推荐）或 pip。

```bash
pip install mxchip-gateway-mcp
# 或
uvx mxchip-gateway-mcp
```

## MCP 配置

在 Cursor（`.cursor/mcp.json`）或 Claude Code（`.mcp.json`）中添加：

```json
{
  "mcpServers": {
    "mxchip-gateway-mcp": {
      "command": "uvx",
      "args": ["mxchip-gateway-mcp"]
    }
  }
}
```

可选通过 `env` 预置网关连接：

```json
{
  "mcpServers": {
    "mxchip-gateway-mcp": {
      "command": "uvx",
      "args": ["mxchip-gateway-mcp"],
      "env": {
        "GATEWAY_IP": "192.168.1.100",
        "GATEWAY_PASSWORD": "mxchip-gateway-admin"
      }
    }
  }
}
```

锁定版本：

```json
{
  "args": ["--from", "mxchip-gateway-mcp==0.1.0", "mxchip-gateway-mcp"]
}
```

## 网关连接

以下方式任选其一：

1. MCP 配置中的 `GATEWAY_IP` / `GATEWAY_PASSWORD` 环境变量
2. 用户配置目录下的 `gateways.json`（`add_gateway` 工具会自动写入）
   - macOS: `~/Library/Application Support/mxchip-gateway-mcp/gateways.json`
   - Linux: `~/.config/mxchip-gateway-mcp/gateways.json`
   - Windows: `%APPDATA%/mxchip-gateway-mcp/gateways.json`
3. 对话中调用 `add_gateway` 工具

可参考 [`gateways.json.example`](gateways.json.example)。

## MCP Tools

| Tool | 说明 |
|------|------|
| `add_gateway` | 手动配置网关 IP 并建立连接 |
| `get_gateway_status` | 查看连接状态与重连信息 |
| `get_home` | 获取设备、场景、区域、群组等家庭模型 |
| `get_attributes` | 读取设备属性 |
| `set_attributes` | 设置设备属性（下行控制） |
| `set_scenes` | 触发场景（下行控制） |

Resource `gateway://home` 提供当前家庭状态快照（含上行 event 更新）。网关断线后后台自动重连。

## 开发

```bash
python3.10 -m venv .venv
.venv/bin/pip install -e ".[dev]"
mxchip-gateway-mcp
# 或
uvx --from . mxchip-gateway-mcp
```

构建与发布：

```bash
pip install build twine
python -m build
twine upload dist/*
```

## 调试

```bash
npx @modelcontextprotocol/inspector mxchip-gateway-mcp
```
