XiaoheiheMcpServer

XiaoheiheMcpServer is a .NET 10.0-based MCP (Model Context Protocol) server that automates interactions with the XiaoHeiHi (小黑盒) social platform. It leverages the ModelContextProtocol SDK, dependency injection, and Playwright for browser automation to publish content, handle login, and fetch/post data through MCP endpoints. The server exposes HTTP as its primary mode of operation (and also supports a stdio variant in releases), enabling tools to create and manage posts, articles, and videos, as well as perform search and retrieval actions. Typical use involves starting the server (via HTTP package or a container) and using the provided MCP client commands to check login status, publish content, and query posts or comments.

Key capabilities include:

• check_login_status and interactive_login for authentication state management via browser automation
• publish_content for text/image posts with optional communities and tags
• publish_article for long-form posts with embedded images and optional communities and tags
• publish_video for video posts with optional cover images and metadata
• search_content to discover posts, and get_post_detail to fetch detailed post data
• post_comment to add comments with optional images

To interact, point your MCP client at the server (e.g., http://localhost:5000/mcp for the HTTP package) and use the available actions described in the MCP protocol and server documentation. Cookies are stored locally (data/cookies.json) after login, enabling seamless subsequent sessions.

Prerequisites:

• For HTTP package: Windows/Linux host to run the provided XiaoheiheMcpServer.Http.exe (or the corresponding release)
• For docker: Docker installed on the host
• Optional: .NET SDK if you are building from source

Option A: 使用发布的 HTTP 包（推荐）

1. 下载并解压发布包，获得 XiaoheiheMcpServer.Http.exe 与相关脚本
2. 安装浏览器依赖（首次需要）: 运行 install-chromium.bat（Windows）或等效脚本
3. 直接运行，默认监听 HTTP 端口 5000: XiaoheiheMcpServer.Http.exe
4. 访问 API：http://localhost:5000/mcp

Option B: 使用发布的单文件 exe（stdio）

1. 下载 XiaoheiheMcpServer-win-x64.zip 并解压
2. 直接运行主执行文件，支持 stdio 模式，配置在 VSCode 里对应的路径即可
3. 访问 API 端点或通过 stdio 客户端进行交互

Option C: 从源码构建（开发/自定义）

1. 克隆仓库并还原依赖: git clone https://github.com/wsmxd/XiaoheiheMcpServer.git cd XiaoheiheMcpServer dotnet restore
2. 构建并安装 Playwright 浏览器: dotnet build .\playwright.ps1 install (或使用初始化 install-chromium.bat 脚本)
3. 运行（开发模式）: dotnet run --project src/XiaoheiheMcpServer.Stdio/XiaoheiheMcpServer.Stdio.csproj

如果你选择使用 Docker，请确保镜像可用并使用以下示例命令启动容器：

• docker pull xiaoheihemcpserver:latest
• docker run -d -p 5000:5000 --name xiaoheihemcpserver xiaoheihemcpserver:latest

注意事项与故障排查要点：

• 初次运行需要安装 Chromium 浏览器，命令 install-chromium.bat 或 playwright install chromium（取决于包的提供方式）
• 图片路径及媒体资源应使用本地绝对路径
• 如果页面结构更新，XiaoheiheService.cs 中的选择器可能需要调整
• 推荐在生产环境使用无头模式（默认），开发/调试可开启有头模式
• 登录态cookies 存储在 data/cookies.json，Cookie 过期需重新扫码登录
• 如遇服务器无法启动，检查浏览器依赖是否正确安装，或删除 data/cookies.json 重新登录