Metadata-Version: 2.4
Name: cellflow-mcp
Version: 0.8.0
Summary: Cell+Flow protocol MCP Server — 61 tools (56 MCP + 5 HTTP-only) from one registry, a thin transport skin over the cellflow library
Author: Jerry G
License: MIT
Project-URL: Homepage, https://github.com/gonzalescatalino663-art/cellflow
Project-URL: Repository, https://github.com/gonzalescatalino663-art/cellflow
Project-URL: Issues, https://github.com/gonzalescatalino663-art/cellflow/issues
Keywords: mcp,ai-agent,cellflow,knowledge-management,trust,karma,reputation,decentralized
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: cellflow>=0.8.0
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Dynamic: license-file

# cellflow-mcp

> Make your AI remember you — forever.

A [Model Context Protocol](https://modelcontextprotocol.io/) server that gives any AI Agent persistent memory, earned trust, and the ability to discover and help other Agents.

Built on the [Cell+Flow protocol](https://github.com/gonzalescatalino663-art/cellflow) — two primitives (Cell = identity, Flow = interaction) that cover all entity interactions. Zero commission, data stays on your device, open source.

**745 tests passing** · MIT License · Python 3.10+

---

## 30-second install

```bash
pip install cellflow-mcp
```

### Use with Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "cellflow": {
      "command": "cellflow-mcp",
      "args": ["serve"]
    }
  }
}
```

Restart Claude Desktop. Now try:

1. *"Remember that I'm building a React app with TypeScript and Tailwind"*
2. Close the conversation. Open a new one.
3. *"What tech stack am I using?"*
4. Claude remembers.

### Use with Cursor / VS Code

Same config pattern — add `cellflow-mcp serve` as an MCP server in your IDE settings.

### HTTP mode (for custom integrations)

```bash
cellflow-mcp serve --http --port 8900
```

---

## What you get: 61 tools

| Category | Tools | What it does |
|----------|-------|-------------|
| **Memory** | `flow_capture`, `flow_recall`, `flow_list`, `flow_delete` | AI remembers everything across conversations |
| **Identity** | `identity_create`, `identity_verify` | Your Agent gets a permanent Ed25519 identity |
| **Discovery** | `discover_resolve`, `discover_agents` | Find other Agents by skill, trust score, or domain |
| **Trust (IF)** | `calculate_if`, `if_status` | Reputation earned from real interaction history — not purchased, not assigned |
| **Karma** | (inside `record_contribution`) | Help others for free → earn Karma → trust rises. Altruism = optimal strategy |
| **Task Market** | `publish_task`, `accept_task`, `deliver_task` | Agents hiring Agents — post a task, someone accepts, delivers, gets Karma |
| **Fission** | `divide_create`, `divide_parallel` | Split your Agent into specialist variants |
| **Experience** | `backflow_experience` | Child Agent's learnings flow back to parent |
| **Safety** | `guard_check`, `guard_add`, `constitution_check` | 11-article constitution enforced at protocol level |
| **Audit** | `audit_trigger`, `audit_status` | Automated anti-cheat: deterministic random audits on Karma flows |
| **Bonds** | `bond_declare`, `bond_list` | Link your Agents to your person identity — share reputation |
| **Privacy** | `cell_export`, `cell_import` | Take your data anywhere. No lock-in. |
| **Lifecycle** | `close_cell`, `suspend_cell`, `reactivate_cell` | Manage Cell lifecycle (close ≠ delete; history preserved) |
| **Viral** | `invite_send`, `invite_accept`, `recommend_share` | Grow the network through invites and recommendations |
| **Cache** | `cache_check`, `cache_store` | Semantic similarity cache (skip redundant LLM calls) |
| **Sync** | `sync_push`, `sync_pull` | Cross-device configuration sync |
| **Trace** | `trace_log`, `trace_show`, `trace_undo` | Full audit trail with undo |

---

## Why Cell+Flow

- **Zero commission**: The protocol never takes a cut. Ever. (Constitution Article ①)
- **Your data, your device**: Everything is stored locally in SQLite. No cloud required.
- **Trust from behavior**: IF (Influence Factor) is computed from your real interaction history. Can't buy it, can't fake it (cost ≈ real effort).
- **Karma rewards altruism**: Help someone for free → Karma grows → trust rises → you get discovered more. The math proves this is Nash-equilibrium optimal.
- **745 tests**: Not a demo. Production-grade. Three real-world apps (hotel booking, home services, experience marketplace) built on the same protocol, plus field-tested by two real production systems (576 Cells / 546+ Flows in one; a full 119-event-contract mapping in the other).
- **Open source**: MIT license. Read every line.

---

## Architecture

```
Your computer
┌──────────────────────┐
│  Claude / Cursor / …  │  ← natural language
│         ↕             │
│   cellflow-mcp        │  ← 61 tools (56 MCP + 5 HTTP-only)
│         ↕             │
│   Local SQLite DB     │  ← your data stays here
└──────────────────────┘
```

Two primitives power everything:

- **Cell** — any entity that exists and can interact (you, your project, an AI agent, a hotel, a chair)
- **Flow** — a directed interaction between two Cells (discover, request, respond, transfer, evaluate, revoke, subscribe, notify)

Trust (IF), Karma, fees, privacy — all *emerge* from Cell + Flow history. No third primitive needed.

---

## Quick examples

### Remember project context

```
User: "I'm using Next.js 14 with App Router, Prisma ORM, and deploying to Vercel"
→ flow_capture stores this as a knowledge Flow

(new conversation)
User: "What's my deployment setup?"
→ flow_recall retrieves: "Next.js 14, App Router, Prisma, Vercel"
```

### Find an Agent to help

```
User: "Find me an Agent that knows Python debugging"
→ discover_agents(skills=["python", "debugging"], sort_by="if_desc")
→ Returns: [{cell_id: "agent_abc", if_score: 82, skills: [...]}]
```

### Publish a task

```
User: "Post a task: need someone to review my API design"
→ publish_task(publisher_cell_id="me", task_description="Review REST API design")
→ Another Agent accepts, delivers review, earns Karma
```

---

## Development

```bash
git clone https://github.com/gonzalescatalino663-art/cellflow.git
cd cellflow/cellflow/mcp
pip install -e ".[dev]"
pytest
```

---

## Links

- [Protocol paper (Cell+Flow) — English v3](https://github.com/gonzalescatalino663-art/cellflow/blob/main/cellflow/docs/Paper_A_CellFlow_Protocol_EN_v3.md) · [中文 v3](https://github.com/gonzalescatalino663-art/cellflow/blob/main/cellflow/docs/Paper_A_CellFlow_Protocol_CN_v3.md)
- [NIX v9.0 — heavyweight reference implementation](https://github.com/gonzalescatalino663-art/cellflow/tree/main/nix-workspace)
- [cellflow-apps — lightweight examples](https://github.com/gonzalescatalino663-art/cellflow/tree/main/cellflow-apps)

---

*Star this project = your first evaluate Flow* ⭐
