WeCom Bot MCP Server Abstraction Layer

This software package provides an Model Context Protocol (MCP) compliant intermediary service tailored specifically for dispatching messages through the WeCom (WeChat Work) application bot interface.

English Version | 中文文档

Core Capabilities

This utility supports transmission across various message formats: - Plain text payloads - Structured Markdown content - Binary data transmission (encoded via base64 for images) - Arbitrary file uploads - Direct support for user or phone-number based group mentions (@-notation) - Internal state management for communication history - Extensible, configurable telemetry/logging framework - Comprehensive static type declarations - Robust input data schema validation utilizing Pydantic principles

Prerequisites

• Requires Python version 3.10 or higher.
• A valid Webhook Uniform Resource Locator (URL) must be provisioned within the target WeCom group settings.

Acquisition Methods

Installation of the WeCom Bot MCP Server can be achieved via several avenues:

1. Automated Deployment (Preferred)

Via Smithery (For Claude Desktop Environments):

bash npx -y @smithery/cli install wecom-bot-mcp-server --client claude

Using VSCode with the Cline Extension:

1. Install the Cline Extension from the VSCode marketplace.
2. Access the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
3. Locate and select "Cline: Install Package".
4. Input "wecom-bot-mcp-server" when prompted and execute.

2. Manual Installation Procedures

Installing via Python Package Index (PyPI):

bash pip install wecom-bot-mcp-server

Manual MCP Configuration Setup:

Modify or generate your overarching MCP configuration file:

// Example for Windsurf utility: ~/.windsurf/config.json { "mcpServers": { "wecom": { "command": "uvx", "args": [ "wecom-bot-mcp-server" ], "env": { "WECOM_WEBHOOK_URL": "your-provided-webhook-identifier" } } } }

Parameterization and Environment Variables

Defining Runtime Environment Parameters

bash

For Windows PowerShell shell:

$env:WECOM_WEBHOOK_URL = "your-provided-webhook-identifier"

Optional parameters for operational fine-tuning

$env:MCP_LOG_LEVEL = "DEBUG" # Permissible verbosity levels: DEBUG, INFO, WARNING, ERROR, CRITICAL $env:MCP_LOG_FILE = "/custom/path/for/logs/service.log" # Override default log persistence location

Telemetry System Location

The internal logging mechanism leverages platformdirs.user_log_dir() to ensure OS-compliant persistence:

• Windows OS Path: C:\Users\<username>\AppData\Local\hal\wecom-bot-mcp-server
• Linux OS Path: ~/.local/share/hal/wecom-bot-mcp-server
• macOS Path: ~/Library/Application Support/hal/wecom-bot-mcp-server

The designated output artifact is named mcp_wecom.log within the respective directory.

Operational Guidance

Initiating the Server Process

Execute the following command in your terminal:

bash wecom-bot-mcp-server

Illustrative Use Cases (Within an MCP Context)

python

Use Case 1: Dispatching localized meteorological data to a WeCom channel

USER: "What is the current forecast for Shenzhen? Forward this information to the designated WeCom channel." ASSISTANT: "I will retrieve the Shenzhen weather conditions and relay them via WeCom."

await mcp.send_message( content="Shenzhen Forecast Update:\n- Temp: 25° Celsius\n- Conditions: Sunny Skies\n- Air Quality Index: Favorable", msg_type="markdown" )

Use Case 2: Notifying specific personnel about an upcoming session

USER: "Issue a notice for the 3 PM project review; ensure explicit notification for personnel Zhang San and Li Si." ASSISTANT: "Affirmative, the meeting notification will be disseminated."

await mcp.send_message( content="## Critical Project Review Notice\n\nScheduled Time: 15:00 Today\nVenue: Conference Room A\nAttendance is mandatory!", msg_type="markdown", mentioned_list=["zhangsan_userid", "lisi_phone_number"] )

Use Case 3: Transferring a document artifact

USER: "Transfer the finalized weekly operational summary document into the WeCom group." ASSISTANT: "Processing the upload of the weekly summary document."

await mcp.send_message( content=Path("reports/weekly_summary_2024.docx"), msg_type="file" )

Direct Library Invocation

Transmitting Messages

python from wecom_bot_mcp_server import mcp

Markdown transmission example

await mcp.send_message( content="System Alert: Initialization Complete!", msg_type="markdown" )

Text message with user targeting

await mcp.send_message( content="Attention required from team members: @engineer_a and @manager_b.", msg_type="text", mentioned_list=["engineer_a_alias", "manager_b_alias"] )

Sending Files

python from wecom_bot_mcp_server import send_wecom_file

Transmit a local file resource

await send_wecom_file("/absolute/path/to/system_config.yaml")

Dispatching Visual Assets

python from wecom_bot_mcp_server import send_wecom_image

Send an image stored locally

await send_wecom_image("/local/assets/logo.png")

Send an image referenced by a remote Uniform Resource Locator (URL)

await send_wecom_image("https://external-repo.net/approved_asset.png")

Development Lifecycle

Setting Up the Local Development Environment

1. Clone the source repository: bash git clone https://github.com/loonghao/wecom-bot-mcp-server.git cd wecom-bot-mcp-server

2. Establish an isolated Python environment and install required toolchains: bash

Utilizing the 'uv' package manager (recommended)

pip install uv uv venv uv pip install -e ".[dev]"

Alternative traditional method (venv):

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -e ".[dev]"

Execution of Automated Checks

bash

Run tests using 'uvx' wrapper:

uvx nox -s pytest

Or using standard 'nox' command:

nox -s pytest

Style Enforcement

bash

Static analysis check:

uvx nox -s lint

Automatic remediation of style violations:

uvx nox -s lint_fix

Artifact Generation and Distribution

bash

Compile the distribution archives

uv build

Build and upload the package artifacts to PyPI

uv build && twine upload dist/*

Internal Directory Map

wecom-bot-mcp-server/ ├── src/ │ └── wecom_bot_mcp_server/ # Core source code modules │ ├── init.py │ ├── server.py # Primary service execution logic │ ├── message.py # Message construction and formatting utilities │ ├── file.py # File transmission handlers │ ├── image.py # Image handling logic │ ├── utils.py # General support functions │ └── errors.py # Custom exception definitions ├── tests/ │ ├── test_server.py │ ├── test_message.py │ ├── test_file.py │ └── test_image.py ├── docs/ ├── pyproject.toml # Project metadata and build configuration ├── noxfile.py # Automation task definitions └── README.md

Licensing Information

This intellectual property is distributed under the permissive MIT License. Full terms are detailed in the accompanying LICENSE file.

Points of Contact

• Primary Developer: longhao
• Electronic Mail: hal.long@outlook.com