wecom-docs-mcp-server

> ## ⚠️ Archived 2026-08-18 — read this first

>

> Unmaintained, and never published to PyPI. The `pip install wecom-docs-mcp-server` line further down does not work and never did — install from source if you still want to run it.

>

> ### Why it's archived

>

> This server is a stdio proxy over WeCom's robot-doc MCP backend. Tencent's investment has visibly moved to a different surface: the official `WecomTeam/wecom-cli` (Rust; rewritten for v1.1.0 on 2026-08-17, 14 service domains) plus the official `WecomTeam/wecom-unified` agent skill. The robot-doc MCP backend has had no public update since 2026-04-22.

>

> ### What the official CLI now covers

>

> Verified against `@wecom/cli` v1.1.0 on 2026-08-18:

>

>

> ### If you came here to give an agent access to WeCom documents

>

> Use the official CLI, not this:

>

> ```bash

> npm install -g @wecom/cli

> npx skills add WecomTeam/wecom-unified -y -g

> wecom-cli auth init

> ```

>

> ### The one part still worth copying

>

> `wecom_doc_mcp/transforms.py` — the cell-unwrap transform. ~120 lines, no MCP dependency. Lift it as a post-processing filter on CLI output rather than running this server.

>

> ### Two empirical findings worth keeping

>

> Observed 2026-07 against the robot-doc backend:

>

> - **`get_doc_content` and `smartsheet_get_*` use independent permission scopes.** The same bot can read a smartsheet via `smartsheet_get_records` (errcode 0) and still get `851003 no authority` from `get_doc_content` on that same document. Route reads by document type; one working scope proves nothing about the other.

> - Pass the full document `url` including `?scode=` rather than reconstructing `docid`. The backend resolves the URL; stripping prefixes by hand yields `301085 invalid docid`.

An ergonomic stdio MCP facade over WeCom's official robot-doc MCP backend. It proxies all 25 backend tools verbatim and adds a transform layer that makes the raw output usable by LLM agents:

• Schema passthrough — the tool list is fetched from the backend at startup, so it auto-tracks official updates. Zero schema maintenance.
• Cell unwrap — smartsheet `values[field] = [{"type":"text","text":...}]` cells become plain scalars (in a `_rows` view).
• ms → ISO — 13-digit ms-epoch timestamps (`create_time`, `update_time`) convert to ISO 8601.
• Chinese error hints — `errcode` 851003 etc. get `_error_summary` + `_error_hint` so the agent learns the fix, not just the code.

> Relationship to the backend: This server *requires* the official robot-doc MCP backend (an apikey from WeCom admin → 智能文档机器人 → API). It is a thin proxy + ergonomics layer, not a replacement.

Why this exists

The official robot-doc backend is an HTTP (StreamableHttp) MCP server. Two friction points: (1) many MCP clients and dev workflows prefer stdio; (2) its raw output is agent-hostile — nested cell format, ms-epoch strings, opaque error codes. This server bridges both:

Requirements

• Python 3.9+
• A WeCom 智能文档机器人 (Smart Doc Bot) with its API key — available to enterprises (≥10 members) via WeCom admin → 应用管理 → 智能文档机器人 → API.

Install

> ⚠️ Never published to PyPI. `pip install wecom-docs-mcp-server` returns 404. Source install is the only path.

Clone + editable:

git clone https://github.com/Beltran12138/wecom-docs-mcp-server
cd wecom-docs-mcp-server
pip install -e .

Configuration

Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "wecom-doc": {
      "command": "wecom-docs-mcp-server",
      "env": { "WECOM_MCP_APIKEY": "your_apikey_here" }
    }
  }
}

Tools

All 25 backend tools are exposed verbatim (fetched live at startup). By domain:

> Permission model (empirically observed 2026-07): `get_doc_content` and `smartsheet_get_*` use independent permission scopes. A bot may read a smartsheet via `smartsheet_get_records` (errcode 0) yet get `851003 no authority` from `get_doc_content` on the same doc. Route reads by doc type.

Transforms (the value-add)

Applied automatically on every `tools/call` response:

1. `_rows` on `smartsheet_get_records` — a flattened view where cells are unwrapped to scalars and top-level record fields (`record_id`, `create_time`, …) are preserved. The original `records` array is kept intact.

2. ms → ISO on all successful dict payloads — 13-digit ms-epoch strings → ISO 8601. Alphanumeric IDs (`q979lj`) are untouched.

3. `_error_summary` + `_error_hint` on any non-zero errcode — Chinese explanation + concrete fix.

Usage

Read a smartsheet end-to-end:

User: read https://doc.weixin.qq.com/smartsheet/s3_xxx?scode=yyy

Agent:
1. smartsheet_get_sheet(url=...)          → sheet_id (e.g. "q979lj")
2. smartsheet_get_fields(sheet_id, url)   → field schema (types, IDs)
3. smartsheet_get_records(sheet_id, url)  → records + _rows (cells unwrapped, timestamps ISO)

> Pass the full `url` (with `?scode=`) rather than guessing `docid` — the backend resolves it. Manually extracting docid by stripping prefixes is error-prone (empirically: `301085 invalid docid`).

Troubleshooting

Related

Tests

pip install -e ".[dev]"  # or: pip install pytest httpx
pytest

25 unit tests cover SSE/JSON parsing, ms-timestamp normalization, cell unwrap, error humanizing, and server routing/post-processing — all offline (httpx mocked).

License

MIT