dingtalk-wiki 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ianen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,339 @@
+# dingtalk-wiki-mcp
+
+[![Release](https://img.shields.io/github/v/release/ianen/dingtalk-wiki-mcp?display_name=tag)](https://github.com/ianen/dingtalk-wiki-mcp/releases)
+[![License](https://img.shields.io/github/license/ianen/dingtalk-wiki-mcp)](./LICENSE)
+[![Stars](https://img.shields.io/github/stars/ianen/dingtalk-wiki-mcp?style=social)](https://github.com/ianen/dingtalk-wiki-mcp)
+[![JavaScript](https://img.shields.io/badge/language-JavaScript-f7df1e)](./package.json)
+
+**DingTalk Wiki / Docs read-write MCP server that fills the gap left by DingTalk official MCP.**
+
+[中文文档 / Chinese docs](./README.zh-CN.md)
+
+> DingTalk's official MCP does **not** provide Wiki / Docs read-write capability.  
+> This project is an open-source complement that makes AI agents and MCP clients actually able to **read, browse, and create DingTalk Wiki / Docs content**.
+
+## Repository Highlights
+
+- **Official MCP gap**: Wiki / Docs read-write is not covered
+- **This project adds it**: workspace browsing, node browsing, and document creation
+- **MCP-compatible**: works with stdio-based MCP clients
+- **Agent-ready**: includes `SKILL.md` for OpenClaw-style skill workflows
+
+---
+
+## MCP 使用方法 / MCP Usage
+
+This server runs over **stdio** and works with any MCP-compatible client (OpenClaw, mcporter, Claude Desktop, VS Code extensions, etc.).
+
+### Option A: Configure in MCP client (recommended)
+
+All config goes into one JSON block — no local files needed:
+
+```json
+{
+  "mcpServers": {
+    "dingtalk-wiki": {
+      "command": "node",
+      "args": ["/path/to/dingtalk-wiki-mcp/index.js"],
+      "env": {
+        "DINGTALK_APP_KEY": "your-app-key",
+        "DINGTALK_APP_SECRET": "your-app-secret",
+        "DINGTALK_WIKI_CONFIG": {
+          "defaultUser": "me",
+          "users": {
+            "me": { "name": "Your Name", "userId": "your-user-id" }
+          },
+          "workspaces": {
+            "My Workspace": {
+              "id": "your_workspace_id",
+              "url": "https://alidocs.dingtalk.com/i/spaces/.../overview",
+              "type": "TEAM"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+> `DINGTALK_WIKI_CONFIG` 支持两种写法：
+> - **JSON 对象**（如上）— MCP 客户端自动处理，**推荐**
+> - **JSON 字符串** — shell export 时必须用，如 `"{\"defaultUser\":\"me\",...}"`
+
+| env var | 说明 |
+|---------|------|
+| `DINGTALK_APP_KEY` | 钉钉应用 AppKey |
+| `DINGTALK_APP_SECRET` | 钉钉应用 AppSecret |
+| `DINGTALK_WIKI_CONFIG` | 用户/知识库配置（JSON），必填 |
+
+首次调用时程序自动通过 `userId` 获取 `unionId` 并缓存到 `~/.cache/dingtalk-wiki-mcp/`，后续启动不再重复请求。
+
+Then call tools as `dingtalk-wiki.list_wiki_workspaces` (namespaced).
+
+### Option B: Direct stdio mode (mcporter)
+
+```bash
+mcporter call --stdio "node /path/to/index.js" list_wiki_workspaces
+```
+
+### Option C: Run standalone
+
+```bash
+node index.js
+```
+
+Then your MCP client connects via stdio.
+
+---
+
+## Quick Start
+
+### 1) Install
+
+```bash
+npm install
+```
+
+### 2) Configure environment
+
+```bash
+cp .env.example .env
+```
+
+Required:
+
+```env
+DINGTALK_APP_KEY=your-app-key
+DINGTALK_APP_SECRET=your-app-secret
+```
+
+`index.js` now auto-loads `.env` from the current working directory (or the repo directory) if those variables are not already present in the environment.
+
+### 3) Run
+
+```bash
+pnpm start
+```
+
+Or:
+
+```bash
+node index.js
+```
+
+> `npx dingtalk-wiki-mcp` is a future-friendly path after npm publishing.  
+> This repository already includes the correct CLI entry (`bin`), but npm distribution is not part of the current release yet.
+
+---
+
+## DingTalk official MCP vs this project
+
+| Capability                     |         DingTalk official MCP |       dingtalk-wiki-mcp |
+| ------------------------------ | ----------------------------: | ----------------------: |
+| Wiki read                      |                   Not covered |                      ✅ |
+| Wiki write                     |                   Not covered |                      ✅ |
+| Create docs                    |                   Not covered |                      ✅ |
+| Create folders                 |                   Not covered |                      ✅ |
+| Create mind maps               |                   Not covered |                      ✅ |
+| Browse workspaces              |                   Not covered |                      ✅ |
+| Browse nodes / folders         |                   Not covered |                      ✅ |
+| Read Notable / `.able` records |                   Not covered |                      ✅ |
+| MCP client compatibility       | Partial / official scope only | ✅ stdio MCP-compatible |
+| OpenClaw skill packaging       |                            No |  ✅ includes `SKILL.md` |
+
+**Positioning principle:** this project does **not** replace the official DingTalk MCP. It **complements** it by filling the Wiki / Docs gap.
+
+---
+
+## Core capabilities
+
+### Wiki / Docs
+
+- List Wiki workspaces
+- Get workspace details
+- List Wiki nodes (folders / docs)
+- Create:
+  - `DOC`
+  - `WORKBOOK`
+  - `MIND`
+  - `FOLDER`
+- Search Wiki by linking to DingTalk search
+- Read Notable / `.able` sheets and records via official API
+
+### Organization
+
+- List departments
+- List department users
+- Get user info
+
+### Operator / Config
+
+- Set current operator (`unionId`)
+- Use a default operator from local config
+- Inspect current local config
+
+### Skill included
+
+This repo is not only an MCP server. It also includes:
+
+- `SKILL.md`
+
+So it can be reused as a **skill package** in OpenClaw-style agent workflows.
+
+---
+
+## Demo
+
+### 1. List Wiki workspaces
+
+![List workspaces demo](./assets/demo-list-workspaces.svg)
+
+### 2. Browse workspace nodes
+
+![Browse nodes demo](./assets/demo-list-nodes.svg)
+
+### 3. Create a document
+
+![Create document demo](./assets/demo-create-doc.svg)
+
+> These demo images are illustrative documentation assets built from representative command/output flows, with all tenant-specific data removed.
+
+---
+
+## Real use cases
+
+### 1) AI automatically creates weekly report docs
+
+Your AI agent can create a fresh DingTalk Wiki document every week for sales, product, or ops reporting.
+
+### 2) Agent explores Wiki structure before writing
+
+Before generating content, an agent can inspect workspaces and folders first, then choose the right target node.
+
+### 3) Auto-initialize project knowledge-base structure
+
+When a new project starts, automation can create a standard folder tree such as:
+
+- Project Overview
+- Weekly Reports
+- Specs
+- Release Notes
+- Retrospectives
+
+---
+
+## Client integration examples
+
+- [OpenClaw example](./docs/clients/openclaw.md)
+- [mcporter example](./docs/clients/mcporter.md)
+- [Generic MCP client example](./docs/clients/generic-mcp-client.md)
+
+---
+
+## Example usage
+
+### Registered server mode
+
+If you have registered this server in your MCP client config under the name `dingtalk-wiki`:
+
+```bash
+mcporter call dingtalk-wiki.show_config
+mcporter call dingtalk-wiki.list_wiki_workspaces
+mcporter call dingtalk-wiki.list_wiki_nodes workspace_id="your_workspace_id"
+mcporter call dingtalk-wiki.create_wiki_doc workspace_id="your_workspace_id" name="Weekly Summary" doc_type="DOC"
+mcporter call dingtalk-wiki.get_user_info userid="your_user_id"
+```
+
+### Direct stdio mode
+
+If you want to run the server directly without pre-registering it, call the tool names directly:
+
+```bash
+mcporter call --stdio "node ./index.js" show_config
+mcporter call --stdio "node ./index.js" list_wiki_workspaces
+mcporter call --stdio "node ./index.js" list_wiki_nodes workspace_id="your_workspace_id"
+mcporter call --stdio "node ./index.js" create_wiki_doc workspace_id="your_workspace_id" name="Weekly Summary" doc_type="DOC"
+```
+
+---
+
+## Available MCP tools
+
+- `set_operator`
+- `show_config`
+- `list_wiki_workspaces`
+- `get_wiki_workspace`
+- `list_wiki_nodes`
+- `get_wiki_node`
+- `create_wiki_doc`
+- `search_wiki`
+- `list_departments`
+- `get_department_users`
+- `get_user_info`
+- `list_notable_sheets`
+- `list_notable_records`
+
+---
+
+## Requirements
+
+- Node.js 18+
+- A DingTalk app with the required API permissions
+- A stdio-compatible MCP client, such as:
+  - OpenClaw
+  - mcporter
+  - other MCP hosts / clients
+
+---
+
+## Permissions
+
+Depending on what you use, your DingTalk app may need permissions such as:
+
+- `Document.WorkspaceDocument.Write`
+- Wiki read permissions
+- Department read permissions
+- User read permissions
+
+Please refer to DingTalk Open Platform documentation for the latest permission names and approval requirements.
+
+---
+
+## Trust materials
+
+- [FAQ](./FAQ.md)
+- [Changelog](./CHANGELOG.md)
+- [API test notes](./API_TEST_REPORT.md)
+- [Skill definition](./skill/SKILL.md)
+- [Skill reference (Chinese)](./docs/skill-reference.md)
+
+---
+
+## Security notes
+
+- This repository ignores `.env`
+- inject AppKey / AppSecret via environment variables instead of hardcoding them
+
+---
+
+## Limitations
+
+- This is a community-maintained complement, not an official DingTalk project
+- Some APIs require enterprise approval on the DingTalk side
+- `search_wiki` is currently more of a search-entry helper than a full-text search implementation
+- Reading normal DingTalk document body content via official public API is still not implemented in this project
+- Notable / `.able` support currently covers sheets and records, not arbitrary document-body export
+
+---
+
+## Related links
+
+- [DingTalk Open Platform - Knowledge Base Overview](https://open.dingtalk.com/document/development/knowledge-base-overview)
+- [Create Team Space Document](https://open.dingtalk.com/document/development/create-team-space-document)
+
+---
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,331 @@
+# dingtalk-wiki-mcp
+
+[![Release](https://img.shields.io/github/v/release/ianen/dingtalk-wiki-mcp?display_name=tag)](https://github.com/ianen/dingtalk-wiki-mcp/releases)
+[![License](https://img.shields.io/github/license/ianen/dingtalk-wiki-mcp)](./LICENSE)
+[![Stars](https://img.shields.io/github/stars/ianen/dingtalk-wiki-mcp?style=social)](https://github.com/ianen/dingtalk-wiki-mcp)
+[![JavaScript](https://img.shields.io/badge/language-JavaScript-f7df1e)](./package.json)
+
+**一个补足钉钉官方 MCP 空白的开源项目：让 AI / MCP 客户端真正读写钉钉 Wiki / Docs。**
+
+[English docs](./README.md)
+
+> 钉钉官方 MCP 目前**没有提供 Wiki / Docs 读写能力**。  
+> 这个项目专门补上这一块，让 AI Agent 和 MCP 客户端可以真正做到：**浏览工作空间、浏览目录节点、创建文档 / 文件夹 / 脑图**。
+
+## 仓库要点
+
+- **官方 MCP 有空白**：没有覆盖 Wiki / Docs 读写
+- **这个项目补上了**：支持 workspace、node 浏览和文档创建
+- **MCP 兼容**：兼容 stdio 模式的 MCP client
+- **Agent 友好**：自带 `SKILL.md`，可直接作为 skill 复用
+
+---
+
+## MCP 使用方法
+
+本服务通过 **stdio** 运行，兼容任何 MCP 客户端（OpenClaw、mcporter、Claude Desktop、VS Code 扩展等）。
+
+### 方式 A：配置到 MCP 客户端（推荐）
+
+所有配置集中在一个 JSON 块中，无需额外本地文件：
+
+```json
+{
+  "mcpServers": {
+    "dingtalk-wiki": {
+      "command": "node",
+      "args": ["/path/to/dingtalk-wiki-mcp/index.js"],
+      "env": {
+        "DINGTALK_APP_KEY": "your-app-key",
+        "DINGTALK_APP_SECRET": "your-app-secret",
+        "DINGTALK_WIKI_CONFIG": {
+          "defaultUser": "me",
+          "users": {
+            "me": { "name": "Your Name", "userId": "your-user-id" }
+          },
+          "workspaces": {
+            "My Workspace": {
+              "id": "your_workspace_id",
+              "url": "https://alidocs.dingtalk.com/i/spaces/.../overview",
+              "type": "TEAM"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+> `DINGTALK_WIKI_CONFIG` 支持两种写法：
+> - **JSON 对象**（如上）— MCP 客户端自动处理，**推荐**
+> - **JSON 字符串** — shell export 时必须用，如 `"{\"defaultUser\":\"me\",...}"`
+
+| 环境变量 | 说明 |
+|---------|------|
+| `DINGTALK_APP_KEY` | 钉钉应用 AppKey |
+| `DINGTALK_APP_SECRET` | 钉钉应用 AppSecret |
+| `DINGTALK_WIKI_CONFIG` | 用户/知识库配置（JSON），必填 |
+
+首次调用时程序自动通过 `userId` 获取 `unionId` 并缓存到 `~/.cache/dingtalk-wiki-mcp/`，后续启动不再重复请求。
+
+之后以 `dingtalk-wiki.工具名` 的方式调用（如 `dingtalk-wiki.list_wiki_workspaces`）。
+
+### 方式 B：直接 stdio 模式（mcporter）
+
+```bash
+mcporter call --stdio "node /path/to/index.js" list_wiki_workspaces
+```
+
+### 方式 C：独立启动
+
+```bash
+node index.js
+```
+MCP 客户端通过 stdio 连接即可。
+
+---
+
+## 快速开始
+
+### 1）安装依赖
+
+```bash
+npm install
+```
+
+### 2）配置环境变量
+
+```bash
+cp .env.example .env
+```
+
+必填：
+
+```env
+DINGTALK_APP_KEY=your-app-key
+DINGTALK_APP_SECRET=your-app-secret
+```
+
+现在 `index.js` 会在环境变量未显式设置时，自动加载当前工作目录（或仓库目录）下的 `.env`。
+
+### 3）运行
+
+```bash
+npm start
+```
+
+或者：
+
+```bash
+node index.js
+```
+
+> `npx dingtalk-wiki-mcp` 是后续可扩展的分发路径。  
+> 当前仓库已经具备正确的 CLI 入口（`bin`），但 npm 发布不在这次版本范围内。
+
+---
+
+## 官方 DingTalk MCP vs 本项目
+
+| 能力 | 钉钉官方 MCP | dingtalk-wiki-mcp |
+|---|---:|---:|
+| Wiki 读取 | 未覆盖 | ✅ |
+| Wiki 写入 | 未覆盖 | ✅ |
+| 创建 docs | 未覆盖 | ✅ |
+| 创建 folder | 未覆盖 | ✅ |
+| 创建 mind map | 未覆盖 | ✅ |
+| 浏览 workspace | 未覆盖 | ✅ |
+| 浏览 nodes / 目录 | 未覆盖 | ✅ |
+| 读取 Notable / `.able` 记录 | 未覆盖 | ✅ |
+| MCP 客户端兼容性 | 官方范围内 | ✅ stdio 兼容 |
+| OpenClaw skill 化复用 | 无 | ✅ 自带 `SKILL.md` |
+
+**定位原则：**本项目不是替代官方 MCP，而是**补足官方没覆盖的 Wiki / Docs 能力**。
+
+---
+
+## 核心能力
+
+### Wiki / Docs
+- 列出 Wiki 工作空间
+- 获取工作空间详情
+- 列出 Wiki 节点（目录 / 文档）
+- 创建：
+  - `DOC`
+  - `WORKBOOK`
+  - `MIND`
+  - `FOLDER`
+- 提供跳转式 Wiki 搜索能力
+- 通过官方 API 读取 Notable / `.able` 的数据表和记录
+
+### 组织架构
+- 列出部门
+- 列出部门成员
+- 获取用户信息
+
+### 操作者 / 配置
+- 设置当前操作者（`unionId`）
+- 使用本地默认操作者
+- 查看当前本地配置
+
+### 自带 skill
+这个仓库不仅是 MCP Server，还自带：
+
+- `SKILL.md`
+
+所以它也可以作为 **OpenClaw 风格 agent 工作流中的 skill 包** 来复用。
+
+---
+
+## Demo
+
+### 1）列出知识库工作空间
+
+![列出工作空间 Demo](./assets/demo-list-workspaces.svg)
+
+### 2）浏览知识库目录节点
+
+![浏览节点 Demo](./assets/demo-list-nodes.svg)
+
+### 3）创建文档
+
+![创建文档 Demo](./assets/demo-create-doc.svg)
+
+> 这些 Demo 图是基于典型命令与输出流程制作的说明型素材，所有租户相关数据都已移除。
+
+---
+
+## 真实使用场景
+
+### 1）AI 自动创建周报文档
+让 Agent 按周在钉钉知识库中自动创建销售、产品或运营周报文档。
+
+### 2）Agent 写入前先浏览知识库结构
+在生成内容之前，先读取 workspace / folder 结构，找到正确目录后再写入。
+
+### 3）自动初始化项目知识库目录
+新项目开始时，自动生成标准目录结构，例如：
+
+- Project Overview
+- Weekly Reports
+- Specs
+- Release Notes
+- Retrospectives
+
+---
+
+## 客户端接入示例
+
+- [OpenClaw 示例](./docs/clients/openclaw.md)
+- [mcporter 示例](./docs/clients/mcporter.md)
+- [通用 MCP client 示例](./docs/clients/generic-mcp-client.md)
+
+---
+
+## 示例用法
+
+### 已注册 server 模式
+
+如果你已经在 MCP client 里把这个 server 注册为 `dingtalk-wiki`：
+
+```bash
+mcporter call dingtalk-wiki.show_config
+mcporter call dingtalk-wiki.list_wiki_workspaces
+mcporter call dingtalk-wiki.list_wiki_nodes workspace_id="your_workspace_id"
+mcporter call dingtalk-wiki.create_wiki_doc workspace_id="your_workspace_id" name="Weekly Summary" doc_type="DOC"
+mcporter call dingtalk-wiki.get_user_info userid="your_user_id"
+```
+
+### 直接 stdio 模式
+
+如果你不想预先注册 server，而是直接拉起它，那么工具名直接写裸工具名：
+
+```bash
+mcporter call --stdio "node ./index.js" show_config
+mcporter call --stdio "node ./index.js" list_wiki_workspaces
+mcporter call --stdio "node ./index.js" list_wiki_nodes workspace_id="your_workspace_id"
+mcporter call --stdio "node ./index.js" create_wiki_doc workspace_id="your_workspace_id" name="Weekly Summary" doc_type="DOC"
+```
+
+---
+
+## 可用 MCP 工具
+
+- `set_operator`
+- `show_config`
+- `list_wiki_workspaces`
+- `get_wiki_workspace`
+- `list_wiki_nodes`
+- `get_wiki_node`
+- `create_wiki_doc`
+- `search_wiki`
+- `list_departments`
+- `get_department_users`
+- `get_user_info`
+- `list_notable_sheets`
+- `list_notable_records`
+
+---
+
+## 环境要求
+
+- Node.js 18+
+- 一个具备相关 API 权限的钉钉应用
+- 一个支持 stdio 的 MCP client，例如：
+  - OpenClaw
+  - mcporter
+  - 其他 MCP Host / Client
+
+---
+
+## 权限说明
+
+根据你的使用范围，钉钉应用可能需要这些权限：
+
+- `Document.WorkspaceDocument.Write`
+- Wiki 读取权限
+- 部门读取权限
+- 用户读取权限
+
+请以钉钉开放平台最新文档和审批要求为准。
+
+---
+
+## 信任材料
+
+- [FAQ](./FAQ.md)
+- [Changelog](./CHANGELOG.md)
+- [API 测试说明](./API_TEST_REPORT.md)
+- [Skill 定义](./SKILL.md)
+- [Skill 参考文档](./docs/skill-reference.md)
+
+---
+
+## 安全说明
+
+- 仓库已默认忽略 `.env`
+- 建议通过环境变量注入 AppKey / AppSecret，而不是写死在代码里
+
+---
+
+## 限制说明
+
+- 本项目是社区补充实现，不是钉钉官方项目
+- 部分 API 需要企业侧权限审批
+- `search_wiki` 当前更偏向“跳转辅助”，不是完整全文检索实现
+- 目前项目仍未实现通过官方公开 API 读取普通 DingTalk 文档正文
+- 当前 Notable / `.able` 支持的是数据表和 records 读取，不是任意正文导出
+
+---
+
+## 相关链接
+
+- [钉钉开放平台 - 知识库概述](https://open.dingtalk.com/document/development/knowledge-base-overview)
+- [创建团队空间文档](https://open.dingtalk.com/document/development/create-team-space-document)
+
+---
+
+## License
+
+MIT

package/docs/clients/generic-mcp-client.md

@@ -0,0 +1,20 @@
+# Generic MCP Client Example
+
+Many MCP clients support stdio-based servers with a configuration block similar to this:
+
+```json
+{
+  "mcpServers": {
+    "dingtalk-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/dingtalk-wiki-mcp/index.js"],
+      "env": {
+        "DINGTALK_APP_KEY": "your-app-key",
+        "DINGTALK_APP_SECRET": "your-app-secret"
+      }
+    }
+  }
+}
+```
+
+If your client supports environment-file injection, you can also keep secrets in `.env` instead of embedding them directly.