Metadata-Version: 2.4
Name: opensoul-mcp
Version: 0.3.1
Summary: Open Source Personality Profiling System based on MCP Protocol
Author-email: Brother Butterfly <zbfzbf704@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://opensoul.top
Project-URL: Repository, https://github.com/OpenSoul-MCP/opensoul-mcp
Project-URL: Documentation, https://opensoul.top/docs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Dynamic: license-file

# OpenSoul MCP

**When was the last time you truly listened to yourself?**

OpenSoul is an open-source personality profiling system. It records every disagreement with AI, every moment of silence, every hesitation—not to monitor you, but to help you see yourself.

[![PyPI](https://img.shields.io/pypi/v/opensoul-mcp.svg)](https://pypi.org/project/opensoul-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-green.svg)](https://modelcontextprotocol.io/)

---

## Quick Install

### Option 1: pip Install (Recommended)

```bash
pip install opensoul-mcp
opensoul-mcp install
```

Done. Restart Claude Code and you're ready to go.

`opensoul-mcp install` automatically:
- Creates config directory `~/.opensoul/` and data directory `~/.opensoul/data/`
- Generates a random API key
- Registers OpenSoul in Claude Code's MCP settings (`~/.claude/settings.json`)

### Option 2: Install from Source

```bash
git clone https://github.com/OpenSoul-MCP/opensoul-mcp.git
cd opensoul-mcp
pip install -e .
opensoul-mcp install
```

### Option 3: Manual Configuration (No pip)

```bash
git clone https://github.com/OpenSoul-MCP/opensoul-mcp.git
cd opensoul-mcp
pip install -r requirements.txt
```

Then edit `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "opensoul": {
      "command": "python3",
      "args": ["/your/path/opensoul-mcp/src/opensoul_mcp/server.py"]
    }
  }
}
```

### Optional: Semantic Search

Install [Ollama](https://ollama.ai/) and pull the embedding model to enable semantic search:

```bash
ollama pull bge-m3
```

OpenSoul works without Ollama—search will fall back to keyword matching.

---

## Verify Installation

After restarting Claude Code, say to Claude:

```
Record a soul fragment:
- Context: Choosing between job offers
- AI suggestion: Pick the high-paying one
- My choice: Choose the one with growth potential
- Reason: Learning matters more than money at this stage
```

If Claude calls `record_soul` and returns results, installation is successful.

Other commands:

```bash
opensoul-mcp version   # Check version
opensoul-mcp run       # Start MCP server manually (for debugging)
```

---

## Why OpenSoul?

| Scenario | Pain Point | What OpenSoul Does |
|----------|------------|-------------------|
| Decision Review | "Why do I always regret my choices?" | Records AI suggestions vs your choices to discover decision patterns |
| Emotion Tracking | "I don't know why I suddenly broke down" | 7-dimensional emotion coordinates to find hidden stress sources |
| Self-Dialogue | "I want to understand myself better" | Continuous recording builds a personality profile—not labels, but a flowing self |

---

## Core Capabilities

| Capability | Description |
|------------|-------------|
| **40+ MCP Tools** | Full coverage for recording, querying, analysis, and personality assessment |
| **INSERT-only Architecture** | Append-only, no modifications, complete history preserved |
| **SHA256 Hash Chain** | Each record cryptographically linked, tamper-proof |
| **Semantic Search** | Vector search + keyword matching (requires Ollama configuration) |
| **Personality Profile** | 7-dimensional personality model analysis |
| **Emotion Coordinates** | Valence, intensity, duration, trigger source |
| **Persona Card System** | 60-question three-tier personality assessment (shares question bank with copywriting system) |
| **Relationship Network** | Record interpersonal relationships and interaction events |
| **Narrative Engine** | Guided deep conversations, layer-by-layer exploration |
| **Local-First** | SQLite storage, data never leaves your computer |

---

## Tech Stack

- **Protocol**: MCP (Model Context Protocol)
- **Language**: Python 3.11+
- **Database**: SQLite (WAL mode)
- **Vectors**: bge-m3 via Ollama (optional, works offline)
- **Full-Text Search**: FTS5
- **Data Integrity**: SHA256 Hash Chain

---

## Documentation

- [Quick Start](docs/quickstart.md) - Get started in 5 minutes
- [Complete Tutorial](docs/tutorial.md) - From beginner to expert
- [Core Concepts](docs/concepts.md) - What is soul logging
- [Complete Tool List](docs/tools.md) - 40+ tools explained
- [Persona Card System](docs/persona.md) - 60-question three-tier personality assessment
- [Narrative Engine](docs/narrative.md) - Guided deep conversations
- [Relationship Network](docs/relations.md) - Interpersonal relationship recording
- [Example Data](docs/examples.md) - Quick experience dataset
- [Architecture](docs/architecture.md) - Technical implementation
- [Self-Hosting](docs/self-hosting.md) - Server deployment
- [FAQ](docs/faq.md)

---

## License

MIT License - Free to use, modify, and commercialize. Just retain the copyright notice.

---

**OpenSoul** was created by [Butterfly Brother](https://github.com/zbfzbf704). Domain: [opensoul.top](https://opensoul.top)

> Every thought that goes unrecorded is a tiny act of forgetting.
