Metadata-Version: 2.4
Name: mcp-server-nucleus
Version: 0.2.1
Summary: The Core of Your AI Agents - Model Context Protocol Server
Author-email: Nucleus Team <hello@nucleus-mcp.com>
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: fastmcp
Requires-Dist: pydantic
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# 🧠 Nucleus MCP Server

[![PyPI version](https://badge.fury.io/py/mcp-server-nucleus.svg)](https://badge.fury.io/py/mcp-server-nucleus)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **The Core of Your AI Agents** — Multi-agent orchestration MCP server

`mcp-server-nucleus` connects your local "Nuclear Brain" agentic system with MCP-compatible clients like Claude Desktop, Cursor, and more.

## ✨ Features

- **10 MCP Tools** for agent orchestration
- **3 MCP Resources** for subscribable state
- **2 MCP Prompts** for pre-built orchestration
- **Local Intelligence** — Directly manipulates your `.brain/` directory
- **Event-Driven** — Emit and listen to system events
- **Zero-Knowledge Default** — Your data stays local

## 🚀 Quick Start

### Installation

```bash
# Requires Python 3.10+
python3 -m pip install mcp-server-nucleus
```

### Initialize Your Brain

```bash
# Create a new .brain/ directory with sample config
python3 -m mcp_server_nucleus.cli init
```

### Configuration (Claude Desktop)

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

```json
{
  "mcpServers": {
    "nucleus-brain": {
      "command": "python3",
      "args": ["-m", "mcp_server_nucleus"],
      "env": {
        "NUCLEAR_BRAIN_PATH": "/path/to/your/.brain"
      }
    }
  }
}
```

Restart Claude Desktop and try: *"What's my current sprint focus?"*

## 🛠 Available Tools

| Tool | Description |
|------|-------------|
| `brain_emit_event` | Emit a new event to the ledger |
| `brain_read_events` | Read recent events |
| `brain_get_state` | Get current brain state |
| `brain_update_state` | Update brain state |
| `brain_read_artifact` | Read an artifact file |
| `brain_write_artifact` | Write to an artifact file |
| `brain_list_artifacts` | List all artifacts |
| `brain_trigger_agent` | Trigger an agent with a task |
| `brain_get_triggers` | Get all neural triggers |
| `brain_evaluate_triggers` | Evaluate trigger activation |

## 📡 MCP Resources

| Resource | Description |
|----------|-------------|
| `brain://state` | Live state.json content |
| `brain://events` | Recent events stream |
| `brain://triggers` | Trigger definitions |

## 💬 MCP Prompts

| Prompt | Description |
|--------|-------------|
| `activate_synthesizer` | Orchestrate current sprint |
| `start_sprint` | Initialize a new sprint |

## 📁 Expected `.brain/` Structure

```
.brain/
├── ledger/
│   ├── events.jsonl
│   ├── state.json
│   └── triggers.json
├── artifacts/
│   ├── research/
│   ├── strategy/
│   └── ...
└── agents/
    └── *.md
```

## 📜 License

MIT © Nucleus Team

