# 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