wecom-docs-mcp-server

wecom-docs-mcp-server

⚠️ Arquivado em 2026-08-18 — leia isto primeiro

Sem manutenção, e nunca publicado no PyPI. A linha pip install wecom-docs-mcp-server mais abaixo não funciona e nunca funcionou — instale a partir do código-fonte se ainda quiser executá-lo.

Por que foi arquivado

Este servidor é um proxy stdio sobre o backend robot-doc MCP do WeCom. O investimento da Tencent visivelmente migrou para uma superfície diferente: o WecomTeam/wecom-cli oficial (Rust; reescrito para v1.1.0 em 2026-08-17, 14 domínios de serviço) além da habilidade oficial de agente WecomTeam/wecom-unified. O backend robot-doc MCP não recebe atualizações públicas desde 2026-04-22.

O que a CLI oficial agora cobre

Verificado contra @wecom/cli v1.1.0 em 2026-08-18:

Diferencial deste projeto	Status na v1.1.0
Transporte stdio	Obsoleto — a CLI é um processo local. Qualquer agente que execute um shell não precisa de camada MCP alguma.
ms-epoch → ISO 8601	Obsoleto — a CLI retorna 2026-08-17 12:17:25 diretamente.
Dicas de erro em chinês	Obsoleto — a CLI retorna help_message + help_instruction, incluindo um link clicável de reparo de autorização.
Passagem de esquema	Obsoleto — todo subcomando aceita --schema (JSON Schema completo com descrições de campos) e --doc.
Desempacotamento de células do Smartsheet	Ainda não resolvido. A v1.1.0 ainda retorna values[field] = [{"type":"text","text":...}], e células longas de rich text se fragmentam em dezenas de segmentos.

Se você veio aqui para dar a um agente acesso a documentos do WeCom

Use a CLI oficial, não esta:

npm install -g @wecom/cli
npx skills add WecomTeam/wecom-unified -y -g
wecom-cli auth init

A única parte que ainda vale copiar

wecom_doc_mcp/transforms.py — a transformação de desempacotamento de células. ~120 linhas, sem dependência de MCP. Reaproveite como filtro de pós-processamento na saída da CLI em vez de executar este servidor.

Duas descobertas empíricas que valem manter

Observado em 2026-07 contra o backend robot-doc:

• get_doc_content e smartsheet_get_* usam escopos de permissão independentes. O mesmo bot pode ler um smartsheet via smartsheet_get_records (errcode 0) e ainda receber 851003 no authority de get_doc_content no mesmo documento. Roteie leituras por tipo de documento; um escopo funcional não prova nada sobre o outro.
• Passe o url completo do documento, incluindo ?scode=, em vez de reconstruir docid. O backend resolve a URL; remover prefixos manualmente resulta em 301085 invalid docid.

---

Uma fachada MCP stdio ergonômica sobre o backend oficial robot-doc MCP do WeCom. Ela faz proxy de todas as 25 ferramentas do backend verbatim e adiciona uma camada de transformação que torna a saída bruta utilizável por agentes de LLM:

• Passagem de esquema — a lista de ferramentas é buscada do backend na inicialização, então ela acompanha automaticamente as atualizações oficiais. Zero manutenção de esquema.
• Desempacotamento de células — células values[field] = [{"type":"text","text":...}] do smartsheet tornam-se escalares simples (em uma visão _rows).
• ms → ISO — timestamps ms-epoch de 13 dígitos (create_time, update_time) convertem para ISO 8601.
• Dicas de erro em chinês — errcode 851003 etc. recebem _error_summary + _error_hint para que o agente aprenda a correção, não apenas o código.

Relação com o backend: Este servidor requer o backend oficial robot-doc MCP (uma apikey do admin do WeCom → 智能文档机器人 → API). É um proxy fino + camada de ergonomia, não um substituto.

---

Por que isto existe

O backend oficial robot-doc é um servidor MCP HTTP (StreamableHttp). Dois pontos de atrito: (1) muitos clientes MCP e fluxos de trabalho de desenvolvimento preferem stdio; (2) sua saída bruta é hostil a agentes — formato de célula aninhado, strings ms-epoch, códigos de erro opacos. Este servidor resolve ambos:

	robot-doc oficial	este servidor
Transporte	HTTP (StreamableHttp)	stdio
Esquema de ferramentas	25 ferramentas brutas	as mesmas 25, passagem direta
Formato de célula	[{"type":"text",...}]	escalares desempacotados (_rows)
Timestamps	strings ms-epoch	ISO 8601
Códigos de erro	apenas 851003	+ resumo em chinês + dica de correção
apikey	obrigatória	obrigatória (proxied)

---

Requisitos

• Python 3.9+
• Um 智能文档机器人 (Smart Doc Bot) do WeCom com sua chave de API — disponível para empresas (≥10 membros) via admin do WeCom → 应用管理 → 智能文档机器人 → API.

---

Instalação

⚠️ Nunca publicado no PyPI. pip install wecom-docs-mcp-server retorna 404. Instalação a partir do código-fonte é o único caminho.

Clone + instalável:

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

---

Configuração

Variável	Obrigatória	Descrição
WECOM_MCP_APIKEY	sim	apikey do robot-doc
WECOM_MCP_BASE_URL	não	sobrescreve a URL do backend (padrão https://qyapi.weixin.qq.com/mcp/robot-doc)

Claude Desktop (claude_desktop_config.json)

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

---

Ferramentas

Todas as 25 ferramentas do backend são expostas verbatim (buscadas ao vivo na inicialização). Por domínio:

Domínio	Leitura	Escrita
doc	get_doc_content	create_doc, edit_doc_content, upload_doc_image, upload_doc_file
smartsheet (智能表)	get_sheet, get_fields, get_records	add/update/delete × sheet/fields/records
sheet (电子表格)	get_info	add_sub, delete_sub, update_range_data, append_data
smartpage (智能页面)	get_export_result	create, export_task

Modelo de permissão (observado empiricamente em 2026-07): get_doc_content e smartsheet_get_* usam escopos de permissão independentes. Um bot pode ler um smartsheet via smartsheet_get_records (errcode 0) e ainda receber 851003 no authority de get_doc_content no mesmo documento. Roteie leituras por tipo de documento.

---

Transformações (o valor agregado)

Aplicadas automaticamente em toda resposta tools/call:

1. _rows em smartsheet_get_records — uma visão achatada onde células são desempacotadas para escalares e campos de registro de nível superior (record_id, create_time, …) são preservados. O array original records é mantido intacto.
2. ms → ISO em todos os payloads de dict bem-sucedidos — strings ms-epoch de 13 dígitos → ISO 8601. IDs alfanuméricos (q979lj) não são alterados.
3. _error_summary + _error_hint em qualquer errcode não-zero — explicação em chinês + correção concreta.

---

Uso

Leia um smartsheet de ponta a ponta:

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)

Passe o url completo (com ?scode=) em vez de adivinhar docid — o backend resolve. Extrair manualmente o docid removendo prefixos é propenso a erros (empiricamente: 301085 invalid docid).

---

Solução de problemas

errcode	significado	correção
851000	文档链接有误	verifique url + scode, ou use docid
851002	文档类型与工具不兼容	smartsheet → use smartsheet_get_*
851003	无文档权限	smartsheet 用 smartsheet_get_*；普通文档查后台权限
851008	缺文档内容读取权限	企微后台 → 机器人 → API 权限
301085	docid inválido	use url completa com scode
40058	parâmetro ausente	smartsheet precisa de sheet_id (primeiro get_sheet)

---

Relacionados

Projeto	Foco
robot-doc MCP oficial	backend (HTTP, empresas ≥10 pessoas)
wecom-bot-mcp-server	mensagens de bot via webhook
este servidor	proxy stdio robot-doc + ergonomia

---

Testes

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

25 testes unitários cobrem parsing SSE/JSON, normalização de timestamps ms, desempacotamento de células, humanização de erros e roteamento/pós-processamento do servidor — todos offline (httpx mockado).

---

Licença

MIT