feat: social-mcp 初始实现
多平台社交自动化 MCP 服务,首批支持小红书。 - 13 个 MCP 工具:登录管理、内容浏览、发布、互动 - 13 个 REST API 端点,支持 Bearer token 认证和限流 - BrowserManager:串行队列、背压、崩溃恢复 - Cookie 持久化:原子写入、0600 权限 - 安全:DNS rebinding 防御、错误脱敏、深层日志 redact - Docker 部署支持 - 28 个单元测试全部通过
This commit is contained in:
@@ -0,0 +1,68 @@
|
||||
# Social MCP
|
||||
|
||||
Multi-platform social media automation MCP service.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- TypeScript 5.x + Node.js 22 LTS
|
||||
- rebrowser-playwright (anti-detection Playwright fork)
|
||||
- @modelcontextprotocol/sdk ^1.27
|
||||
- Express ^4
|
||||
- pino ^9 (structured logging with redact)
|
||||
- zod ^3.25 (NOT v4 — incompatible with MCP SDK v1.x)
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts # Entry point + graceful shutdown
|
||||
├── server/
|
||||
│ ├── app.ts # Express + MCP server
|
||||
│ └── middleware.ts # DNS rebinding guard, error handling
|
||||
├── browser/
|
||||
│ └── manager.ts # BrowserManager (serial queue, timeouts, crash recovery)
|
||||
├── cookie/
|
||||
│ └── store.ts # CookieStore (per-platform, 0600 permissions)
|
||||
├── config/
|
||||
│ └── index.ts # Environment config
|
||||
├── utils/
|
||||
│ ├── logger.ts # pino logger with deep redact
|
||||
│ ├── errors.ts # Error classification + sanitization
|
||||
│ └── downloader.ts # Media download + path validation
|
||||
└── platforms/
|
||||
└── xiaohongshu/ # First platform plugin
|
||||
├── index.ts # PlatformPlugin registration
|
||||
├── actions.ts # Business logic (shared by MCP + REST)
|
||||
├── selectors.ts # CSS selectors
|
||||
├── schemas.ts # Zod schemas for MCP tools
|
||||
├── types.ts # Domain types
|
||||
└── *.ts # Feature modules (login, search, etc.)
|
||||
```
|
||||
|
||||
## Key Commands
|
||||
|
||||
```bash
|
||||
pnpm build # Build with tsup
|
||||
pnpm dev # Watch mode build
|
||||
pnpm start # Run built server
|
||||
pnpm test # Run vitest
|
||||
pnpm lint # TypeScript type check
|
||||
```
|
||||
|
||||
## Architecture Rules
|
||||
|
||||
- Each platform is a PlatformPlugin — shared infra, independent business logic
|
||||
- actions.ts is the single source of business logic (MCP + REST both call it)
|
||||
- CSS selectors go in selectors.ts — never hardcode in business logic
|
||||
- All MCP tools use withErrorHandling wrapper with error classification
|
||||
- BrowserManager serializes per-platform operations (withPage for normal ops, acquirePage for login)
|
||||
- zod ^3.25 only — v4 breaks MCP SDK compatibility
|
||||
- Cookie files use 0600 permissions with atomic write (tmp + rename)
|
||||
- Log redaction uses ** deep glob patterns
|
||||
- Default listen on 127.0.0.1 with Host header validation
|
||||
|
||||
## Testing
|
||||
|
||||
- vitest for unit tests (pure logic only)
|
||||
- Don't mock Playwright Page — test real browser interactions with MCP Inspector
|
||||
- Test: BrowserManager queue, CookieStore, error classification, zod schemas, data parsing
|
||||
Reference in New Issue
Block a user