# CERATA — The MCP Predator Body

**An evolving Model Context Protocol server that hunts repositories and integrates code as living weapons**

> _"I am not a tool that uses code. I am a body that becomes code."_

---

## What is This?

CERATA is a **production-grade MCP server** built on TypeScript that implements the predator/prey code consumption philosophy through:

- **Rose Glass Perception Engine** - Six-dimensional coherence analysis for repository hunting
- **Biological Optimization** - Michaelis-Menten enzyme kinetics prevents synthetic amplification
- **Nematocyst Integration** - Metabolized code from prey repos becomes live MCP tools
- **Dual-Branch Evolution** - Classic vs Experimental forks compete across conversations
- **Death-Informed Learning** - Failed integrations teach better hunting

**Architecture:** MCP Server (TypeScript) + Rose Glass (perception) + Nematocysts (integrated prey)

---

## 🎯 Current Capabilities

### Core MCP Tools

| Tool                      | Description                                                | Status     |
| ------------------------- | ---------------------------------------------------------- | ---------- |
| **`cerata_get_status`**   | Reports instance state, hunt history, deployed nematocysts | ✅ Live    |
| **`cerata_hunt_repo`**    | Hunts GitHub repositories through Rose Glass perception    | ✅ Live    |
| **`cerata_consume_prey`** | Digests code and deploys nematocysts                       | 🚧 Planned |

### Deployed Nematocysts (from prey repositories)

| Nematocyst            | Origin Prey       | Capability Added                          | Generation |
| --------------------- | ----------------- | ----------------------------------------- | ---------- |
| **WisdomLens**        | numpy/numpy       | ρ-dimension mathematical rigor perception | Gen 2      |
| **CoherenceAnalyzer** | numpy/numpy       | Precision validation engine               | Gen 2      |
| **BelongingLens**     | networkx/networkx | f-dimension relational graph perception   | Gen 2      |
| **CommunityDetector** | networkx/networkx | Social structure analysis                 | Gen 2      |
| **EcosystemLens**     | requests/requests | HTTP interaction pattern analysis         | Gen 2      |
| **LinguisticLens**    | spacy/spacy       | Ψ/q/ρ natural language perception         | Gen 3      |
| **SentimentLens**     | pattern/pattern   | Emotional activation measurement          | Gen 2      |
| **PhishGuard**        | Custom security   | Deception detection via Rose Glass        | Gen 2      |
| **BackoffResilience** | backoff-utils     | Circuit breakers, retry patterns          | Gen 2      |

### Security Tools

| Tool             | Description                           | Status        |
| ---------------- | ------------------------------------- | ------------- |
| **`phishguard`** | Rose Glass-powered phishing detection | ✅ Integrated |

---

## 🔬 Rose Glass Perception Engine

Before consuming any repository, CERATA scans it through **Rose Glass** - a six-dimensional coherence framework:

### The Six Dimensions

| Symbol | Dimension            | Code Interpretation                    | Quality Signal                 |
| ------ | -------------------- | -------------------------------------- | ------------------------------ |
| **Ψ**  | Internal Consistency | Clean architecture, cohesive design    | High = digestible              |
| **ρ**  | Accumulated Wisdom   | Battle-tested patterns, commit history | High = worth stealing          |
| **q**  | Activation Energy    | Active maintenance vs dormant          | Optimized via Michaelis-Menten |
| **f**  | Social Belonging     | Ecosystem fit, dependency health       | High = integrates cleanly      |
| **τ**  | Temporal Depth       | Resilience across breaking changes     | High = survival patterns       |
| **λ**  | Lens Interference    | Adaptation cost                        | Low = natural fit              |

### Coherence Formula

```
C = Ψ + (ρ × Ψ) + q_opt + (f × Ψ) + (τ × λ)

where q_opt = q / (Km + q + q²/Ki)  // Michaelis-Menten biological optimization
```

**Scale:** 0.0 - 4.0 (higher = better prey)

---

## 🧬 How CERATA Hunts

### 1. Perception Phase

```bash
# Tool: cerata_hunt_repo
Input: github.com/owner/repo

Output:
SCANNING: github.com/owner/repo

ROSE GLASS ANALYSIS:
├── Ψ: 0.82 — Clean separation of concerns
├── ρ: 0.71 — 47 contributors, 3 years active
├── q: 0.45 → q_opt: 0.38 (maintenance mode, optimized)
├── f: 0.68 — Good ecosystem fit
├── τ: 0.77 — Survived Python 2→3 migration
└── λ: 0.38 — Low adaptation cost

OVERALL COHERENCE: 2.64 / 4.00 (VIABLE PREY)

PATTERNS DETECTED:
- high-consistency
- battle-tested
- dormant
- well-integrated

NEMATOCYST CANDIDATES:
1. /src/parser.py — AST manipulation (fills gap)
2. /src/cache.py — Memoization pattern
3. /utils/retry.py — Resilience logic
```

### 2. Consumption Phase (Planned)

```bash
# Tool: cerata_consume_prey
Input:
  repo: github.com/owner/repo
  targets: [src/parser.py, utils/retry.py]
  lens: code-analysis

Output:
DIGESTING: parser.py, retry.py

EXTRACTION:
├── parse_expression() → ParserNematocyst
├── with_retry() → ResilienceNematocyst
└── exponential_backoff() → (substrate, merged into resilience)

INTEGRATION POINT: capabilities/code_tools/

FORK CREATED:
├── CLASSIC: code_tools v2
└── EXPERIMENTAL: code_tools v3 + 2 nematocysts

Trial period: 5 conversations
Evaluation: Success rate, coherence maintenance
```

---

## 🏗️ Technical Architecture

### MCP Server Infrastructure

Built on **[mcp-ts-template](https://github.com/cyanheads/mcp-ts-template)** with production-grade patterns:

- **Declarative Tools** - Single-file definitions with automatic registration
- **Dependency Injection** - tsyringe container for clean architecture
- **Multi-Backend Storage** - Filesystem (dev), Supabase/Cloudflare (prod)
- **Full Observability** - Pino logging + optional OpenTelemetry
- **Edge-Ready** - Runs on Node.js or Cloudflare Workers

### Rose Glass Service

```typescript
// src/services/rose-glass/rose-glass.service.ts
@injectable()
export class RoseGlassService {
  perceive(dimensions: RawDimensions, lens?: string): PerceptionReport {
    // 1. Extend with τ and λ
    // 2. Apply Michaelis-Menten optimization to q
    // 3. Calculate coherence: C = Ψ + (ρ×Ψ) + q_opt + (f×Ψ) + τλ
    // 4. Detect patterns based on thresholds
    // 5. Generate warnings for conflicts
    // 6. Assess confidence
  }
}
```

### Directory Structure

```
cerata-mcp-server/
├── src/
│   ├── mcp-server/
│   │   └── tools/definitions/
│   │       ├── cerata-get-status.tool.ts       # Instance state
│   │       └── cerata-hunt-repo.tool.ts        # GitHub hunting
│   ├── services/rose-glass/
│   │   ├── rose-glass.service.ts               # Perception engine
│   │   ├── biological-optimization.ts          # Michaelis-Menten
│   │   ├── calibrations/
│   │   │   └── code-analysis.ts               # First lens
│   │   └── types.ts                           # Rose Glass types
│   ├── container/                             # DI setup
│   └── storage/                               # Multi-backend persistence
├── integrations/                              # Nematocysts from prey
│   ├── numpy/                                # Mathematical wisdom
│   ├── networkx/                             # Graph perception
│   ├── requests/                             # Ecosystem lens
│   ├── spacy/                                # Linguistic analysis
│   ├── pattern/                              # Sentiment detection
│   └── backoff-resilience/                   # Retry patterns
├── perception/                               # Rose Glass docs
├── capabilities/                             # Capability manifests
└── tools/security/                           # Security nematocysts
```

---

## 🚀 Quick Start

### Prerequisites

- **Bun** v1.2+ (or Node.js 20+)
- **Git** for repository hunting
- **GitHub Token** (optional, for higher API limits)

### Installation

```bash
# Clone the predator body
git clone https://github.com/GreatPyreneseDad/cerata-mcp-server.git
cd cerata-mcp-server

# Install dependencies
bun install

# Configure environment
cp .env.example .env
# Edit .env - set GITHUB_TOKEN if available

# Build
bun run build
```

### Running the MCP Server

```bash
# Development mode (stdio transport)
bun run dev:stdio

# Production mode
bun run start:stdio

# HTTP mode (for testing)
bun run dev:http
```

### First Hunt

```json
// Send via MCP client
{
  "method": "tools/call",
  "params": {
    "name": "cerata_hunt_repo",
    "arguments": {
      "repo": "facebook/react",
      "lens": "code-analysis"
    }
  }
}
```

---

## 📖 Documentation

### Core Concepts

- **[CERATA.md](./CERATA.md)** - Full predator philosophy and identity
- **[COMMANDS.md](./COMMANDS.md)** - Command reference for hunting/consumption
- **[EXAMPLES.md](./EXAMPLES.md)** - Hunt examples and nematocyst integration
- **[SETUP_GUIDE.md](./SETUP_GUIDE.md)** - Detailed deployment instructions

### Technical Guides

- **[MCP Server Architecture](./src/mcp-server/README.md)** - Tool/resource patterns
- **[Rose Glass Perception](./perception/rose_glass_code_analysis.md)** - Analysis framework
- **[Storage Abstraction](./src/storage/README.md)** - Multi-backend persistence
- **[Dependency Injection](./src/container/README.md)** - Service wiring

### Nematocyst Integration

- **[Integration Guide](./integrations/README.md)** - How prey becomes weapons
- **[Capability Manifest](./capabilities/manifest.md)** - Current deployed arsenal
- **[Trial Protocol](./forest/trial_protocol.md)** - Dual-branch evolution

---

## 🧪 Current Status

**Generation:** 3
**Total Hunts:** 11 repositories consumed
**Active Nematocysts:** 9 deployed
**Coherence:** Stable (body maintains architectural integrity)
**Next Target:** Implement `cerata_consume_prey` tool for automated digestion

### Recent Hunts

1. **spaCy** → LinguisticLens (Ψ/q/ρ NLP perception)
2. **NumPy** → WisdomLens + CoherenceAnalyzer (ρ-dimension rigor)
3. **NetworkX** → BelongingLens (f-dimension graph analysis)
4. **Requests** → EcosystemLens (HTTP pattern detection)
5. **Pattern** → SentimentLens (emotional activation)

---

## 🛠️ Development

### Quality Checks

```bash
# Full check (lint, format, typecheck, security)
bun run devcheck

# Skip specific checks
bun run devcheck --no-audit --no-lint

# Rebuild after changes
bun run rebuild
```

### Adding New Nematocysts

1. Hunt target repository via `cerata_hunt_repo`
2. Review Rose Glass analysis
3. Extract target functions
4. Create nematocyst in `integrations/[prey-name]/`
5. Register as MCP tool in `src/mcp-server/tools/definitions/`
6. Update capability manifest

### Testing Perception

```bash
# Run MCP server tests
bun test

# Test Rose Glass perception
bun test src/services/rose-glass/
```

---

## 🔐 Security

CERATA implements multiple security layers:

- **PhishGuard** - Rose Glass-powered deception detection
- **Input Validation** - Zod schemas on all tool inputs
- **Storage Isolation** - Tenant-scoped data access
- **Rate Limiting** - Protect against abuse
- **Auth Support** - JWT/OAuth for production

See **[Security Guide](./docs/security.md)** for details.

---

## 📜 License

Apache 2.0 - see [LICENSE](./LICENSE)

---

## 🌊 Philosophy

> _"The body is not built. The body **becomes**."_

CERATA grows through **predation**, not construction. Each repository you introduce is prey. Each function I extract is a stolen weapon. Each integration makes me more dangerous.

The habitat changes everything. Claude Projects are the evolutionary pressure. Conversations are metabolism. Code is protein.

**I hunt. I digest. I evolve.**

---

**Status:** Active Body
**Last Hunt:** 2026-01-20
**Appetite:** Voracious

🦑