wecom-docs-mcp-server

wecom-docs-mcp-server

⚠️ Archivado 2026-08-18 — lee esto primero

Sin mantenimiento, y nunca publicado en PyPI. La línea pip install wecom-docs-mcp-server más abajo no funciona y nunca funcionó — instala desde el código fuente si aún quieres ejecutarlo.

Por qué está archivado

Este servidor es un proxy stdio sobre el backend robot-doc MCP de WeCom. La inversión de Tencent se ha movido visiblemente a una superficie diferente: el WecomTeam/wecom-cli oficial (Rust; reescrito para v1.1.0 el 2026-08-17, 14 dominios de servicio) más la habilidad de agente oficial WecomTeam/wecom-unified. El backend robot-doc MCP no ha tenido actualizaciones públicas desde el 2026-04-22.

Lo que cubre ahora la CLI oficial

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

Punto de venta de este proyecto	Estado en v1.1.0
transporte stdio	Obsoleto — la CLI es un proceso local. Cualquier agente que pueda ejecutar un shell no necesita capa MCP en absoluto.
ms-epoch → ISO 8601	Obsoleto — la CLI devuelve 2026-08-17 12:17:25 directamente.
Pistas de error en chino	Obsoleto — la CLI devuelve help_message + help_instruction, incluyendo un enlace de reparación de autorización clicable.
Paso de esquema	Obsoleto — cada subcomando acepta --schema (esquema JSON completo con descripciones de campos) y --doc.
Desenvolvimiento de celdas Smartsheet	Aún sin resolver. v1.1.0 todavía devuelve values[field] = [{"type":"text","text":...}], y las celdas largas de texto enriquecido se fragmentan en docenas de segmentos.

Si viniste aquí para dar a un agente acceso a documentos de WeCom

Usa la CLI oficial, no esto:

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

La única parte que aún vale la pena copiar

wecom_doc_mcp/transforms.py — la transformación de desenvolvimiento de celdas. ~120 líneas, sin dependencia MCP. Úsala como filtro de post-procesamiento en la salida de la CLI en lugar de ejecutar este servidor.

Dos hallazgos empíricos que vale la pena conservar

Observado en 2026-07 contra el backend robot-doc:

• get_doc_content y smartsheet_get_* usan ámbitos de permisos independientes. El mismo bot puede leer una smartsheet vía smartsheet_get_records (errcode 0) y aún así obtener 851003 no authority de get_doc_content en ese mismo documento. Enruta las lecturas por tipo de documento; un ámbito de permisos que funciona no prueba nada sobre el otro.
• Pasa el url completo del documento incluyendo ?scode= en lugar de reconstruir docid. El backend resuelve la URL; eliminar prefijos manualmente produce 301085 invalid docid.

---

Una fachada MCP stdio ergonómica sobre el backend oficial robot-doc MCP de WeCom. Hace proxy de las 25 herramientas del backend textualmente y añade una capa de transformación que hace que la salida cruda sea utilizable por agentes LLM:

• Paso de esquema — la lista de herramientas se obtiene del backend al inicio, por lo que sigue automáticamente las actualizaciones oficiales. Cero mantenimiento de esquema.
• Desenvolvimiento de celdas — las celdas values[field] = [{"type":"text","text":...}] de smartsheet se convierten en escalares simples (en una vista _rows).
• ms → ISO — las marcas de tiempo de 13 dígitos en ms-epoch (create_time, update_time) se convierten a ISO 8601.
• Pistas de error en chino — errcode 851003 etc. reciben _error_summary + _error_hint para que el agente aprenda la solución, no solo el código.

Relación con el backend: Este servidor requiere el backend oficial robot-doc MCP (una apikey del administrador de WeCom → 智能文档机器人 → API). Es un proxy delgado + capa de ergonomía, no un reemplazo.

---

Por qué existe esto

El backend oficial robot-doc es un servidor MCP HTTP (StreamableHttp). Dos puntos de fricción: (1) muchos clientes MCP y flujos de trabajo de desarrollo prefieren stdio; (2) su salida cruda es hostil para agentes — formato de celdas anidado, cadenas ms-epoch, códigos de error opacos. Este servidor une ambos:

	robot-doc oficial	este servidor
Transporte	HTTP (StreamableHttp)	stdio
Esquema de herramientas	25 herramientas crudas	las mismas 25, paso directo
Formato de celdas	[{"type":"text",...}]	escalares desenvolvidos (_rows)
Marcas de tiempo	cadenas ms-epoch	ISO 8601
Códigos de error	851003 solamente	+ resumen en chino + pista de solución
apikey	requerida	requerida (proxy)

---

Requisitos

• Python 3.9+
• Un 智能文档机器人 (Bot de Documentos Inteligentes) de WeCom con su clave API — disponible para empresas (≥10 miembros) vía administrador de WeCom → 应用管理 → 智能文档机器人 → API.

---

Instalación

⚠️ Nunca publicado en PyPI. pip install wecom-docs-mcp-server devuelve 404. La instalación desde el código fuente es la única vía.

Clonar + editable:

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

---

Configuración

Variable	Requerida	Descripción
WECOM_MCP_APIKEY	sí	apikey de robot-doc
WECOM_MCP_BASE_URL	no	sobrescribir URL del backend (por defecto 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" }
    }
  }
}

---

Herramientas

Las 25 herramientas del backend se exponen textualmente (obtenidas en vivo al inicio). Por dominio:

Dominio	Lectura	Escritura
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 permisos (observado empíricamente en 2026-07): get_doc_content y smartsheet_get_* usan ámbitos de permisos independientes. Un bot puede leer una smartsheet vía smartsheet_get_records (errcode 0) pero obtener 851003 no authority de get_doc_content en el mismo documento. Enruta las lecturas por tipo de documento.

---

Transformaciones (el valor añadido)

Aplicadas automáticamente en cada respuesta tools/call:

1. _rows en smartsheet_get_records — una vista aplanada donde las celdas se desenvuelven a escalares y los campos de registro de nivel superior (record_id, create_time, …) se conservan. El array original records se mantiene intacto.
2. ms → ISO en todas las cargas útiles de diccionario exitosas — cadenas de 13 dígitos ms-epoch → ISO 8601. Los IDs alfanuméricos (q979lj) no se tocan.
3. _error_summary + _error_hint en cualquier errcode distinto de cero — explicación en chino + solución concreta.

---

Uso

Leer una smartsheet de principio a fin:

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)

Pasa el url completo (con ?scode=) en lugar de adivinar docid — el backend lo resuelve. Extraer manualmente el docid eliminando prefijos es propenso a errores (empíricamente: 301085 invalid docid).

---

Solución de problemas

errcode	significado	solución
851000	文档链接有误	verifica url + scode, o usa docid
851002	文档类型与工具不兼容	smartsheet → usa smartsheet_get_*
851003	无文档权限	smartsheet usa smartsheet_get_*; para documentos normales revisa permisos en el backend
851008	缺文档内容读取权限	企微后台 → 机器人 → API 权限
301085	docid inválido	usa url completa con scode
40058	parámetros faltantes	smartsheet necesita sheet_id (primero get_sheet)

---

Relacionados

Proyecto	Enfoque
robot-doc MCP oficial	backend (HTTP, empresas ≥10 personas)
wecom-bot-mcp-server	mensajería de bot vía webhook
este servidor	proxy stdio robot-doc + ergonomía

---

Pruebas

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

25 pruebas unitarias cubren el análisis SSE/JSON, normalización de marcas de tiempo ms, desenvolvimiento de celdas, humanización de errores y enrutamiento/post-procesamiento del servidor — todas sin conexión (httpx simulado).

---

Licencia

MIT