# 明道云 MCP Server

[![npm version](https://badge.fury.io/js/mingdao-mcp-server.svg)](https://www.npmjs.com/package/mingdao-mcp-server)
[![downloads](https://img.shields.io/npm/dm/mingdao-mcp-server)](https://www.npmjs.com/package/mingdao-mcp-server)
[![GitHub license](https://img.shields.io/github/license/iceleaf916/mingdao-mcp-server)](https://github.com/iceleaf916/mingdao-mcp-server/blob/main/LICENSE)
[![GitHub issues](https://img.shields.io/github/issues/iceleaf916/mingdao-mcp-server)](https://github.com/iceleaf916/mingdao-mcp-server/issues)
[![GitHub stars](https://img.shields.io/github/stars/iceleaf916/mingdao-mcp-server)](https://github.com/iceleaf916/mingdao-mcp-server)

MCP (Model Context Protocol) Server for Mingdao (明道云) Worksheet API

📦 [GitHub Repository](https://github.com/iceleaf916/mingdao-mcp-server) •
[🐛 Issues](https://github.com/iceleaf916/mingdao-mcp-server/issues) •
[👥 Contributors](https://github.com/iceleaf916/mingdao-mcp-server/graphs/contributors)



## 功能

- 列出工作表
- 获取工作表结构（字段、视图）
- 查询记录（支持筛选、排序、分页）
- 创建/更新/删除记录
- 批量操作
- 关联记录查询与管理

## 安装

### NPX 运行（推荐，无需安装）

**最简单的方式** - 项目已发布到 npm，可直接使用 npx 运行，无需全局安装：

```bash
npx mingdao-mcp-server
```

### 全局安装

如果需要频繁使用，可以全局安装：

```bash
npm install -g mingdao-mcp-server
```
### 从源码安装

```bash
git clone <repository-url>
cd mingdao-mcp-server
npm install
npm run build
```

## 配置

### 通过环境变量

创建 `.env` 文件：

```bash
# 必需
MINGDAO_APP_KEY=your_app_key
MINGDAO_SIGN=your_sign

# 可选（默认 cooperation.uniontech.com）
MINGDAO_BASE_URL=https://cooperation.uniontech.com
```

## 使用

### 快速启动（推荐）

使用 npx 直接运行：

```bash
MINGDAO_APP_KEY=your_app_key MINGDAO_SIGN=your_sign npx mingdao-mcp-server
```

### 全局安装后使用

```bash
MINGDAO_APP_KEY=your_app_key MINGDAO_SIGN=your_sign mingdao-mcp-server
```

### 开发模式

```bash
npm run dev
```

### 生产模式（从源码）

```bash
npm start
```

### MCP Inspector 调试

```bash
npm run inspector
```

## Claude Code 配置

### 方式一：使用 NPX（推荐，最简单）

在 `~/.claude.json` 中配置，无需全局安装：

```json
{
  "mcpServers": {
    "mingdao": {
      "command": "npx",
      "args": ["mingdao-mcp-server"],
      "env": {
        "MINGDAO_APP_KEY": "your_app_key",
        "MINGDAO_SIGN": "your_sign",
        "MINGDAO_BASE_URL": "https://cooperation.uniontech.com"
      },
      "type": "stdio"
    }
  }
}
```

### 方式二：全局安装

如果已全局安装，使用命令名：

```json
{
  "mcpServers": {
    "mingdao": {
      "command": "mingdao-mcp-server",
      "args": [],
      "env": {
        "MINGDAO_APP_KEY": "your_app_key",
        "MINGDAO_SIGN": "your_sign",
        "MINGDAO_BASE_URL": "https://cooperation.uniontech.com"
      },
      "type": "stdio"
    }
  }
}
```

### 方式三：从环境变量读取

将环境变量添加到 `~/.zshrc` 或 `~/.bashrc`：

```bash
export MINGDAO_APP_KEY="your_app_key"
export MINGDAO_SIGN="your_sign"
export MINGDAO_BASE_URL="https://cooperation.uniontech.com"
```

然后配置（无需在 JSON 中重复设置环境变量）：

```json
{
  "mcpServers": {
    "mingdao": {
      "command": "npx",
      "args": ["mingdao-mcp-server"],
      "type": "stdio"
    }
  }
}
```

### 方式四：本地开发

如需本地开发，使用本地路径：

```json
{
  "mcpServers": {
    "mingdao": {
      "command": "node",
      "args": ["/path/to/mingdao-mcp-server/dist/index.js"],
      "env": {
        "MINGDAO_APP_KEY": "your_app_key",
        "MINGDAO_SIGN": "your_sign",
        "MINGDAO_BASE_URL": "https://cooperation.uniontech.com"
      },
      "type": "stdio"
    }
  }
}
```

## 环境变量

| 变量名             | 必需 | 说明                                         |
| ------------------ | ---- | -------------------------------------------- |
| `MINGDAO_APP_KEY`  | 是   | 明道云应用 Key                               |
| `MINGDAO_SIGN`     | 是   | API 签名                                     |
| `MINGDAO_BASE_URL` | 否   | 明道云域名，默认 `cooperation.uniontech.com` |

## Tools

### 基础操作

- `list_worksheets` - 列出所有工作表
- `get_worksheet_schema` - 获取工作表结构

### 记录 CRUD

- `query_records` - 查询记录（支持筛选、排序、分页）
- `get_record` - 获取单条记录
- `create_record` - 创建记录
- `update_record` - 更新记录
- `delete_record` - 删除记录

### 工作表管理

- `create_worksheet` - 创建新的工作表

### 关联记录

- `get_related_records` - 获取关联记录
- `create_record_with_relations` - 创建记录并建立关联
- `update_record_relations` - 更新关联关系

### 批量操作

- `batch_create_records` - 批量创建
- `batch_update_records` - 批量更新

## 字段类型对照表

| 类型值 | 字段类型 | 值格式示例               |
| ------ | -------- | ------------------------ |
| 2      | 文本     | `"文本内容"`             |
| 6      | 数值     | `"123.45"`               |
| 10     | 多选     | `"选项1,选项2"`          |
| 11     | 单选     | `"选项值"`               |
| 14     | 附件     | `"https://.../file.jpg"` |
| 15     | 日期     | `"2024-01-15"`           |
| 16     | 日期时间 | `"2024-01-15 14:30"`     |
| 26     | 成员     | `"user-account-id"`      |
| 29     | 关联记录 | `"rowid1,rowid2"`        |

## 创建工作表示例

```json
{
  "name": "任务管理",
  "alias": "task",
  "controls": [
    {
      "controlName": "任务标题",
      "alias": "title",
      "type": 2,
      "required": true
    },
    {
      "controlName": "状态",
      "alias": "status",
      "type": 11,
      "required": true,
      "strDefault": "待处理"
    },
    {
      "controlName": "优先级",
      "alias": "priority",
      "type": 2,
      "required": false
    }
  ]
}
```

## 测试

使用测试脚本验证服务器:

```bash
# 设置环境变量后测试
MINGDAO_APP_KEY=xxx MINGDAO_SIGN=xxx node test-server.js
```

## 许可证

MIT