# COS MCP Server

<!-- mcp-name: io.github.semalytics/cos-mcp -->

MCP server for [COS](https://semalytics.com) (Communication Optimization System) — score content across 7 psychology frameworks.

## Quick Start

```bash
# Set your API key
export COS_API_KEY="cos_api_..."

# Run with uvx (no install needed)
uvx cos-mcp
```

Get your API key at [semalytics.com](https://semalytics.com).

## Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cos": {
      "command": "uvx",
      "args": ["cos-mcp"],
      "env": {
        "COS_API_KEY": "cos_api_..."
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add --transport stdio --env COS_API_KEY=cos_api_... cos -- uvx cos-mcp
```

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `COS_API_KEY` | Yes | — | Your COS developer API key |
| `COS_API_URL` | No | `https://semalytics.com/api` | COS API base URL |

## Tools (11)

### Core Analysis

| Tool | Credits | Description |
|------|---------|-------------|
| `analyze_content` | 5 | Full 4-framework analysis (HAPE + Big Five + Strategic Clarity + Framing Strategy) |
| `analyze_framework` | 2 | Single framework analysis |
| `analyze_full_comms` | 10 | All 7 frameworks in parallel |

### Extended Analysis

| Tool | Credits | Description |
|------|---------|-------------|
| `analyze_persuasion` | 3 | Domain-specific persuasion (business, politics, health, masculinity, comedy) |
| `analyze_platform` | 2 | Platform optimization (13 platforms) |
| `analyze_quality` | 2 | 5-dimension quality scoring |
| `profile_agent` | 3 | Infer OCEAN personality from writing samples |

### Conversational

| Tool | Credits | Description |
|------|---------|-------------|
| `chat` | 1 | Interactive analysis agent |

### Templates

| Tool | Credits | Description |
|------|---------|-------------|
| `get_templates` | Free | List available analysis templates |
| `get_template_details` | Free | Get template specifications |
| `execute_template` | 2 | Run a template with variables |

## Frameworks

**Core 4:**
- **HAPE** — Engagement scoring: impact, novelty, relevance, emotional valence
- **Big Five** — Personality-based communication using the OCEAN model (0.0–1.0 traits)
- **Strategic Clarity** — Message alignment: value proposition, differentiation, CTA strength
- **Framing Strategy** — Cognitive frames, metaphors, and power positioning

**Extended 3:**
- **Persuasion** — Domain-aware persuasion analysis (Cialdini's principles, ELM routes, moral foundations)
- **Platform** — Platform-specific optimization for 13 platforms (Twitter, LinkedIn, Email, TikTok, etc.)
- **Quality** — 5-dimension quality: clarity, coherence, correctness, completeness, conciseness

## Examples

### Analyze a LinkedIn post

```
Use analyze_content to score this LinkedIn post for engagement and personality fit:

"We just shipped our v2.0 and I couldn't be prouder of this team..."
```

### Profile a writer's personality

```
Use profile_agent with these 3 writing samples to identify the author's communication style:

Sample 1: "..."
Sample 2: "..."
Sample 3: "..."
```

### Run a full 7-framework analysis

```
Use analyze_full_comms on this sales email, targeting the business domain on the email platform:

"Subject: Quick question about your Q3 pipeline..."
```

## Development

```bash
git clone https://github.com/SEMalytics/cos-mcp
cd cos-mcp
uv pip install -e .
export COS_API_KEY="your-key"
cos-mcp
```

## License

MIT
