Metadata-Version: 2.4
Name: five-mcp
Version: 1.0.1
Summary: 160,000 deductively-derived JSON constraints that eliminate LLM persona drift. Measured: 0 breaks in a 120-turn pressure test.
Project-URL: Homepage, https://fiveengine.dev
Project-URL: Repository, https://github.com/kiro0x/five-mcp
Project-URL: Issues, https://github.com/kiro0x/five-mcp/issues
Project-URL: Documentation, https://fiveengine.dev
Author-email: kiro0x <hello@fiveengine.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,consistency,five,inference-cost-reduction,llm,mcp,persona,persona-drift,retry-elimination,token-cost-optimization
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# five-mcp

MCP server for the [FIVE Persona Engine](https://fiveengine.dev) — an LLM persona constraint engine that generates structured JSON constraints to eliminate persona drift. Instead of describing personality in words (which LLMs interpret differently each turn), FIVE defines behavioral parameters the LLM executes as a recipe. [See how it works →](https://github.com/kiro0x/five-character-engine#the-fix-dont-let-the-llm-interpret-personality-at-all)

> **Measured:** with the constraint JSON + free harness, the demo character survived a **120-turn pressure test with zero persona breaks** (plain prompt: 8 breaks; JSON alone: 1). [Numbers, transcripts and scripts →](https://github.com/kiro0x/five-character-engine#measured-does-it-actually-hold)

## Quick Start

### Install

```bash
pip install five-mcp
```

### Configure

Set your API key as an environment variable:

```bash
export FIVE_API_KEY=five_sk_your_key_here
```

Get your key at [fiveengine.dev](https://fiveengine.dev).

### Use with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "five-character-engine": {
      "command": "five-mcp",
      "env": {
        "FIVE_API_KEY": "five_sk_your_key_here"
      }
    }
  }
}
```

### Use with other MCP clients

Any MCP-compatible client can connect via stdio transport:

```bash
five-mcp
```

## Tool: `generate`

Generates persona constraints via the FIVE engine.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `character_name` | string | Yes | Name of the character |
| `q1` – `q4` | A / B / C / D | Yes | Personality axis choices |
| `s1` – `s4` | 1–5 | No | Style sliders (default: 3) |
| `free_text` | string | No | Free-form description |

### Response

```json
{
  "status": "ok",
  "remaining": 42,
  "constraint": { "..." }
}
```

## Pricing

Each `generate` call costs **$1** and consumes one credit. Manage credits at [fiveengine.dev](https://fiveengine.dev).

## Links

- **API & Docs:** [fiveengine.dev](https://fiveengine.dev)
- **GitHub:** [github.com/kiro0x/five-mcp](https://github.com/kiro0x/five-mcp)
- **Design philosophy & examples:** [five-character-engine README](https://github.com/kiro0x/five-character-engine)
- **Measured evaluation (120-turn drift test):** [five-character-engine eval/](https://github.com/kiro0x/five-character-engine/tree/main/eval)
- **Engine repo:** [github.com/kiro0x/five-character-engine](https://github.com/kiro0x/five-character-engine)

## License

MIT


<!-- mcp-name: io.github.kiro0x/five-mcp -->
