Installation‐and‐Quickstart

Installation & Quickstart

Back to M-COP WIKI | See also: Architecture | API-Reference

---

Prerequisites

Before installing MCOP Framework 2.0, ensure you have:

Requirement	Version	Notes
Node.js	20+	Use .nvmrc for exact version (20.11.0)
pnpm	9+	Exact: 9.15.0 via corepack
Git	Any recent	For cloning the repository
Python	3.10+	Only needed for mcop_package Python implementation

---

Installation

1. Clone the repository

git clone https://github.com/Kuonirad/MCOP-Framework-2.0.git
cd MCOP-Framework-2.0

2. Enable pnpm via Corepack (first time only)

corepack enable
corepack prepare pnpm@9.15.0 --activate

3. Select the correct Node version

nvm use   # picks 20.11.0 from .nvmrc

4. Install dependencies

pnpm install --frozen-lockfile

Note: When contributing (not just installing), use pnpm install (without --frozen-lockfile) to allow lockfile updates.

5. Configure environment

cp .env.example .env
# Edit .env with your platform credentials and configuration

6. (Optional) Docker setup

cp .env.example .env
docker compose up -d

---

Development Server

pnpm dev
# Starts Next.js dev server at http://localhost:3000

---

Quickstart: TypeScript (Core Triad)

Minimal usage — directly invoking the three core kernels:

import { NovaNeoEncoder, StigmergyV5, HolographicEtch } from '@/core';

// 1. Initialize the triad
const encoder = new NovaNeoEncoder({ dimensions: 64, normalize: true });
const stigmergy = new StigmergyV5();
const etch = new HolographicEtch();

// 2. Encode an input into a context tensor
const context = encoder.encode('dialectical synthesis');

// 3. Record a pheromone trace in shared memory
const trace = stigmergy.recordTrace(context, context, { note: 'bootstrap' });

// 4. Query resonance (cosine similarity recall)
const resonance = stigmergy.getResonance(context);

// 5. Apply a micro-etch (confidence-delta update)
const etchRecord = etch.applyEtch(context, trace.synthesisVector, 'unit test');

console.log({ trace, resonance, etchRecord });

---

Quickstart: TypeScript (Magnific Adapter)

Using the Universal Adapter Protocol with the Magnific image platform:

import { NovaNeoEncoder, StigmergyV5, HolographicEtch } from '@/core';
import { MagnificMCOPAdapter } from '@/adapters';

const adapter = new MagnificMCOPAdapter({
  encoder: new NovaNeoEncoder({ dimensions: 64, normalize: true }),
  stigmergy: new StigmergyV5({ resonanceThreshold: 0.4 }),
  holographicEtch: new HolographicEtch({ confidenceFloor: 0 }),
});

const { result, merkleRoot, provenance } = await adapter.generateOptimizedImage(
  'aurora-lit cathedral at dawn, crystalline geometry',
  { model: 'mystic-2.5-fluid', resolution: '4k' }
);

console.log('merkleRoot:', merkleRoot);
console.log('provenance:', provenance);

---

Quickstart: Python (mcop_package)

Using the Python mirror implementation with the Higgsfield video adapter:

from mcop_package import NovaNeoEncoder, StigmergyV5, HolographicEtch
from mcop_package.adapters import HiggsfieldMCOPAdapter

adapter = HiggsfieldMCOPAdapter(
    encoder=NovaNeoEncoder(dimensions=64, normalize=True),
    stigmergy=StigmergyV5(resonance_threshold=0.4),
    holographic_etch=HolographicEtch(confidence_floor=0),
)

result = adapter.optimize_cinematic_video(
    prompt='storm-lit ocean, slow motion waves',
    model='higgsfield-cinema-v2',
)

print(result.merkle_root)
print(result.provenance)

---

Configuration Reference

Configuration is passed to constructors or loaded from config/examples/mcop.config.example.json.

Parameter	Component	Default	Description
dimensions	NovaNeoEncoder	64	Output tensor dimensionality
normalize	NovaNeoEncoder	true	Whether to L2-normalize the output vector
resonanceThreshold	StigmergyV5	0.4	Minimum cosine similarity to return a match
confidenceFloor	HolographicEtch	0	Minimum allowed confidence delta

Example mcop.config.example.json:

{
  "encoder": {
    "dimensions": 64,
    "normalize": true
  },
  "stigmergy": {
    "resonanceThreshold": 0.4
  },
  "holographicEtch": {
    "confidenceFloor": 0
  }
}

---

Common Commands

pnpm dev          # Start development server (localhost:3000)
pnpm build        # Production build
pnpm test         # Run Jest test suite
pnpm lint         # ESLint + Prettier check
pnpm typecheck    # TypeScript strict type check
pnpm test:hybrid  # Jest + Cypress combined
pnpm cypress:run  # E2E tests (exploratory, non-blocking)

---

Troubleshooting

corepack: command not found Ensure Node.js 20+ is installed. Corepack ships with Node 16.9+ but may need enabling: npm install -g corepack.

pnpm version mismatch Run corepack prepare pnpm@9.15.0 --activate to pin to the correct version.

Module not found: @/core Make sure you ran pnpm install and that tsconfig.json path aliases are configured. Check that @/* maps to ./src/*.

Docker issues Ensure .env exists (copy from .env.example) before running docker compose up -d.

---

See Contributing-Guide for contributor-specific setup details.