{"id":49574800,"url":"https://github.com/andyleimc-source/md-cloud","last_synced_at":"2026-05-03T16:08:29.046Z","repository":{"id":352624148,"uuid":"1215638780","full_name":"andyleimc-source/md-cloud","owner":"andyleimc-source","description":"MCP Server for Mingdao Collaboration v1 API (cloud-token mode, no OAuth)","archived":false,"fork":false,"pushed_at":"2026-04-20T13:11:16.000Z","size":35,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T13:45:12.789Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andyleimc-source.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-20T05:39:30.000Z","updated_at":"2026-04-20T13:11:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/andyleimc-source/md-cloud","commit_stats":null,"previous_names":["andyleimc-source/md-cloud"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/andyleimc-source/md-cloud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fmd-cloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fmd-cloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fmd-cloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fmd-cloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andyleimc-source","download_url":"https://codeload.github.com/andyleimc-source/md-cloud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fmd-cloud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32575265,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-03T16:08:27.737Z","updated_at":"2026-05-03T16:08:29.038Z","avatar_url":"https://github.com/andyleimc-source.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# md-cloud\n\nMCP Server for Mingdao Collaboration-era v1 API — **cloud-token mode**, no OAuth, no local secrets.\n\n\u003e 这是 [`mdold`](https://github.com/andyleimc-source/mdold) 的简化版，把 token 获取从本地 OAuth 流程改成远端 hook 三参数换 token，由服务端代为保管 access_token 并自动每日刷新。客户端只需要两个字段就能跑起来。\n\n## 功能\n\n提供约 **44 个**明道协作 v1 API 工具，覆盖 8 个模块：\n\n| 模块 | 数量 | 主要能力 |\n|------|-----|---------|\n| 动态 (post) | 9 | 全公司/我的/用户/群组动态、详情、评论、发布、删除 |\n| 日程 (calendar) | 8 | 列表、详情、邀请、搜索、创建、编辑、删除 |\n| 私信 (webchat) | 6 | 会话、消息、未读、发送 |\n| 收件箱 (message) | 2 | 系统通知、动态相关通知 |\n| 群组 (group) | 10 | 详情、成员、加入/创建、管理员管理 |\n| 用户 (user) | 6 | 联系人、组织成员、@搜索、按手机/邮箱查找 |\n| 组织 (company) | 3 | 组织、部门、按 ID 查询 |\n| 个人账户 (passport) | 4 | 当前用户详情、设置、未读、名片 |\n\n工具签名与 [mdold](https://github.com/andyleimc-source/mdold) 完全一致，可作 drop-in 替换。\n\n## 快速开始\n\n```bash\ngit clone https://github.com/andyleimc-source/md-cloud.git\ncd md-cloud\npython3 install.py\n```\n\n一条命令走完全流程，脚本会引导你：\n\n1. 创建 `.venv` 并安装依赖\n2. 获取 `MD_ACCOUNT_ID` / `MD_KEY`（默认走浏览器隐身窗口 OAuth 授权；也可手动输入已有凭据）\n3. 写入 `.env`\n4. 可选把 md-cloud 注册到 Claude Code（项目级 `.mcp.json` 或调 `claude mcp add` 写到用户级，或两个都配）\n5. 跑一次 token 换取验证\n\n完成后重启 Claude Code，就能直接对话操作明道：\n\n- \"帮我看看张三最近发了什么动态\"\n- \"创建一个明天上午 10 点的日程，邀请李四\"\n- \"给王五发一条消息说下午 3 点开会\"\n- \"列出公司所有部门\"\n\n### 高阶：手动安装\n\n不想跑 `install.py` 的老用户看这里：\n\n```bash\npython3 -m venv .venv\n.venv/bin/pip install .        # Python 3.14+ 必须用非 editable\n.venv/bin/mdcloud-auth          # 或手动 cp .env.example .env 填 MD_ACCOUNT_ID / MD_KEY\n```\n\n然后在 `.mcp.json`（项目级）或用 `claude mcp add`（用户级）注册：\n\n```json\n{\n  \"mcpServers\": {\n    \"md-cloud\": {\n      \"type\": \"stdio\",\n      \"command\": \"/绝对路径/md-cloud/.venv/bin/python3\",\n      \"args\": [\"-m\", \"md_cloud.server\"],\n      \"env\": {\n        \"MD_ACCOUNT_ID\": \"你的-uuid\",\n        \"MD_KEY\": \"你的-key\"\n      }\n    }\n  }\n}\n```\n\n可选环境变量（几乎不用动）：\n\n```env\n# MD_APPNAME=mdcloud\n# MD_HOOK_URL=https://api.mingdao.com/workflow/hooks2/xxx\n# MD_APP_KEY=\u003c自定义 OAuth 应用 app_key\u003e\n# MD_REGISTER_URL=\u003c自定义注册 hook URL\u003e\n# MD_CALLBACK_PORT=8080\n```\n\n## 与 mdold 的差异\n\n| 维度 | mdold | md-cloud |\n|------|-------|----------|\n| Token 获取 | 浏览器 OAuth + 本地 .secrets.json | POST hook，3 个字段换 token |\n| Token 刷新 | 客户端用 refresh_token 续期，14 天必失效 | 服务端代管，自动每日刷新，永不过期 |\n| 配置项 | app_key / app_secret / redirect_uri | account_id / key |\n| 本地凭证文件 | .secrets.json（敏感） | 无 |\n| 工具集 | 8 个模块 | 同 8 个模块 |\n| 适合 | 个人开发者，自己跑 OAuth | 团队/产品场景，运营方统一发放 key |\n\n## 工具明细\n\n每个 `tools_*.py` 文件顶部注释列出了该模块的全部工具及其参数。直接在 Claude Code 中用自然语言唤起即可，无需手动调用。\n\n## Token 缓存策略\n\n- 启动时不预拉，第一次工具调用触发 `ensure_access_token()` 拉一次\n- 命中后缓存到当天本地时间 23:59:59，次日 00:00 后下次调用时重新拉\n- 拉取失败抛 `RuntimeError`，工具调用失败但 MCP server 不退出\n\n不持久化到磁盘 — 重启进程即重新拉一次（多一个 ~200ms RTT，但无任何文件凭证残留）。\n\n## 故障排查\n\n| 现象 | 原因 | 解决 |\n|------|------|------|\n| `Missing MD_ACCOUNT_ID or MD_KEY` | .env 没配或 env 没注入 | 检查 .env / `.mcp.json` 的 env 字段 |\n| `Token endpoint returned no token` | 服务端拒绝（key 不对、account_id 不存在、appname 拼错） | 确认 key 与 account_id；联系运营方 |\n| HTTP 401 | token 失效（极少见，服务端日刷新） | 重启 MCP server 强制清缓存 |\n\n## 注册 hook 协议（给自部署运营方）\n\n`mdcloud-auth` 拿到 `code` 后会 POST 到 `MD_REGISTER_URL`（默认 `REGISTER_URL_DEFAULT`），协议：\n\n**请求**：\n\n```json\n{ \"code\": \"xxx\", \"redirect_uri\": \"http://localhost:8964/callback\" }\n```\n\n**服务端应做**：\n\n1. 用 `{app_key, app_secret, code, redirect_uri, grant_type=authorization_code}` 调 `https://api.mingdao.com/oauth2/access_token`\n2. 用返回的 `access_token` 调 `/v1/passport/get_detail` 拿 `account_id`\n3. Upsert `{account_id → refresh_token}` 到映射表；为该 `account_id` 复用或新生成一个 `key`\n4. 返回：\n\n```json\n{ \"account_id\": \"...\", \"key\": \"...\" }\n```\n\n后续该 `account_id` 的 token 刷新由你现有的日刷 hook 负责。\n\n## API 参考\n\n明道开放平台：\u003chttps://open.mingdao.com/document\u003e\n\n## License\n\nMIT\n\n---\n\n## 关于\n\n由 [雷码工坊](https://github.com/andyleimc-source) 维护。\n\n姊妹项目：\n\n- [mdold](https://github.com/andyleimc-source/mdold) — 本地 OAuth 完整版（功能等同，自己跑授权）\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyleimc-source%2Fmd-cloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandyleimc-source%2Fmd-cloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyleimc-source%2Fmd-cloud/lists"}