🏛️ Council MCP Server

Council MCP Server provides memory, state, and reasoning scaffolding for an AI (like opencode) to solve complex problems through 5 ordered phases — all without any internal LLM calls. It uses pure deterministic logic + JSON file persistence.

Dibuat oleh riflxz

Table of Contents

• How It Works
• Features
• Architecture
• Installation
• Quick Start
• MCP Tools Reference
  • council_init
  • council_save
  • council_recall
  • council_verify
  • council_continue
  • council_score
• Phases & Personas
• Three Core Principles
• Scoring System
• Testing
• Project Structure
• License

How It Works

Task Input
    │
    ▼
┌──────────────────────────────────────────────────────────┐
│  council_init                                            │
│  • Parse task & assess complexity                        │
│  • Generate adaptive pipeline depth                      │
│  • Assign first persona                                  │
│  • Initialize session state                              │
└──────────────────────┬───────────────────────────────────┘
                       │
                       ▼
         ┌─────────────────────┐
         │  PERSONA:           │ ◄── Each phase has a
         │  Analyst            │     unique persona with
         │  Architect          │     defined authority
         │  Auditor            │     boundaries
         │  Engineer           │
         │  QA                 │
         └────────┬────────────┘
                  │
    ┌─────────────┴─────────────┐
    │   council_save            │
    │   • Validate authority    │
    │   • Score output          │
    │   • Check contradictions  │
    │   • Build handshake       │
    │   • Unlock next phase     │
    └─────────────┬─────────────┘
                  │
                  ▼
         ┌──────────────────┐
         │  Score ≥ 70?     │
         └──────┬───┬───────┘
            Yes │   │ No
                │   └──→ Improve & re-save
                ▼
    ┌──────────────────────┐
    │  Unlock next phase   │
    │  Handoff to next     │
    │  persona             │
    └──────────────────────┘
                │
    ┌───────────┴───────────┐
    │  Loop through 5       │
    │  phases:              │
    │  decompile → design   │
    │  → critique → synth   │
    │  → verify             │
    └───────────┬───────────┘
                │
                ▼
    ┌──────────────────────┐
    │  council_score       │
    │  Final assessment    │
    └──────────────────────┘

Features

| Feature | Description | |---------|-------------| | 🧠 5-Phase Reasoning Pipeline | Decompile → Design → Critique → Synthesis → Verify | | 👤 Persona-Based Execution | Each phase has a unique persona (Analyst, Architect, Auditor, Engineer, QA) with defined authority boundaries | | 📊 Complexity-Adaptive Pipeline | Automatically selects light/standard/full pipeline based on task complexity scoring | | 🔍 Contradiction Detection | Cross-phase numerical and polarity contradiction detection | | 📝 Transparency Logging | Certainty levels (5 tiers), knowledge boundaries, assumption flags | | 🔐 Authority Enforcement | Each persona has strict authority boundaries — violations generate warnings | | 🤝 Handshake Protocol | Structured phase-to-phase handoff with context passing and conflict resolution | | 💾 JSON Persistence | Zero-dependency JSON file store — collections: sessions, phases, decisions, claims, transparency_log, phase_handoffs | | 📈 Multi-Dimensional Scoring | Completeness, consistency, decision quality, structure, transparency, agentic — weighted aggregate | | 🔌 MCP Protocol | 6 tools exposed via stdio MCP transport — compatible with any MCP host |

Architecture

src/
├── index.js              # Entry point — McpServer + StdioServerTransport
├── tools.js              # All 6 MCP tool handlers (~600 lines)
├── db/
│   └── json-store.js     # Generic JSON file CRUD (getAll, insert, updateWhere, etc.)
├── memory/
│   ├── session.js        # Session CRUD & lifecycle
│   ├── phase.js          # Phase state machine & transitions
│   ├── decision.js       # Decision trace storage
│   └── recall.js         # Context composer (full/summary/decisions formats)
├── analysis/
│   └── parser.js         # Task structure parser (sentence splitting, keyword extraction)
├── prinsip/
│   ├── adaptive.js       # Complexity detector + pipeline generator
│   ├── transparency.js   # Certainty validation, knowledge boundaries, assumption flags
│   └── agentic.js        # Persona definitions, authority validation, handshake builder
├── verify/
│   ├── contradiction.js  # Numerical + polarity contradiction detection
│   └── grounding.js      # Claim source verification
└── score/
    ├── completeness.js   # Per-phase field requirement checker
    ├── consistency.js    # Contradiction-based consistency scoring
    ├── transparency.js   # 3-dimension transparency scoring
    ├── agentic.js        # Authority violation + persona match scoring
    └── index.js          # Weighted aggregator -> final score + verdict + suggestions

Data Flow

Tool Call  →  tools.js handler  →  memory/*  →  analysis/*  →  prinsip/*
                                  ↓                              ↓
                               verify/*  ←─────────────── score/*
                                  ↓
                    JSON response to MCP client

JSON Store

Six collections in ./data/: | Collection | Purpose | |-----------|---------| | sessions.json | Session metadata, status, complexity score | | phases.json | Phase records with output, confidence, authority warnings | | decisions.json | Decision trace per phase | | claims.json | Claims with certainty levels and sources | | transparency_log.json | Transparency log entries | | phase_handoffs.json | Phase-to-phase handshake records |

Installation

# Install globally
npm install -g mcp-council-server

# Or run directly with npx (fast — bundled single file, no npm install needed)
npx -y mcp-council-server

# Or clone and run locally
git clone https://github.com/riflxz/mcp-council-server.git
cd mcp-council-server
npm install
npm run build
npm start

Requirements

• Node.js >= 18.0.0
• No native compilation needed — works on arm64 Linux (Node.js v26+)
• No database — pure JSON file persistence

Quick Start

1. Integrasi dengan opencode (recommended)

Di ~/.config/opencode/opencode.json, tambahkan:

{
  "mcp": {
    "council": {
      "type": "local",
      "command": ["npx", "-y", "mcp-council-server"]
    }
  }
}

Atau pake path lokal setelah clone:

{
  "mcp": {
    "council": {
      "type": "local",
      "command": ["node", "/path/to/mcp-council-server/dist/bundle.cjs"]
    }
  }
}

Lalu restart opencode. Council akan otomatis terdeteksi sebagai MCP server.

2. Atau via CLI (MCP Inspector)

git clone https://github.com/riflxz/mcp-council-server.git
cd mcp-council-server
npm install

# Start dengan MCP Inspector
npm run inspect

# Atau langsung
npm start

3. Contoh Sesi Lengkap — Migrasi Database

Ini adalah contoh sesi nyata menggunakan Council + opencode. Setiap langkah menunjukkan tool yang dipanggil dan respons yang diterima AI.

Step 1: Init — Mulai sesi

AI memanggil council_init dengan task user:

Task: "Migrasi database MySQL ke PostgreSQL. 2GB data, 
       downtime <30 menit. Handling JSON dan ENUM types."

Response dari Council:

complexity: moderate (49/100) → 5-phase pipeline
persona: Systems Analyst
fase aktif: decompile

AI sekarang tahu: harus memulai fase DECOMPILE sebagai Systems Analyst.

Step 2: Decompile — Analisa masalah

AI bekerja sebagai Systems Analyst, menghasilkan output fase decompile, lalu memanggil council_save:

sessionId: "xxx"
phase: "decompile"
output: {
  summary: "Tiga sub-masalah: strategi migrasi 2GB data...",
  decisions: [...],
  constraints: ["downtime_30_menit", "data_2GB", ...],
  claims: [{ text: "pg_dump cocok untuk 2GB", certainty: "confirmed", ... }],
  knowledgeBoundary: { whatIKnow: [...], whatIAssume: [...], ... }
}

Response Council:

score: 93 (excellent) ✓
canProceed: true
nextPhase: design
handoff: Systems Analyst → Solution Architect

Step 3–6: Lanjut ke fase berikutnya

Council mengunci fase yang sudah selesai dan membuka fase berikutnya. AI mengikuti persona baru setiap fase:

| Fase | Persona | Contoh Output | |------|---------|--------------| | design | Solution Architect | 2 approaches dievaluasi, tradeoffs, rekomendasi | | critique | Security & Quality Auditor | Vulnerabilities, riskLevel, mitigations | | synthesis | Implementation Engineer | Langkah implementasi, test plan, warnings | | verify | Quality Assurance | Checks, pass/fail count, keputusan APPROVED/REJECTED |

Step 7: Final score

Setelah semua fase selesai, AI memanggil council_score:

overall: 87 (good)
quality: 89 | adaptability: 85 | transparency: 100 | agentic: 71

4. Troubleshooting

| Masalah | Solusi | |---------|--------| | Server timeout | Jika opencode melaporkan timeout, gunakan path lokal (node /path/src/index.js) bukan npx. Npx perlu download package dulu yang bisa lambat. | | Data directory error | Pastikan working directory bisa di-write. Server membuat folder ./data/ untuk menyimpan session JSON. | | Tool not found | Restart opencode setelah mengubah opencode.json. Jalankan tools/list untuk verifikasi. | | Session tiba-tiba hilang | Session disimpan di ./data/ sebagai JSON file. Jika folder terhapus, session hilang. |

MCP Tools Reference

council_init

Creates a new reasoning session. Parses the task, assesses complexity, generates an adaptive pipeline, assigns the first persona.

Parameters:

| Field | Type | Required | Description | |-------|------|----------|-------------| | task | string | ✅ | The problem or task to solve | | title | string | ❌ | Optional session title | | context | string | ❌ | Additional context for the AI |

Response:

{
  "type": "council_init",
  "sessionId": "uuid",
  "adaptation": {
    "complexity": { "raw": 49, "normalized": 49, "level": "moderate", "pipelineDepth": "standard" },
    "pipeline": [
      { "name": "decompile", "persona": "analyst", "depth": "standard", "order": 1 },
      { "name": "design", "persona": "architect", "depth": "standard", "order": 2 },
      { "name": "critique", "persona": "auditor", "depth": "standard", "order": 3 },
      { "name": "synthesis", "persona": "engineer", "depth": "standard", "order": 4 },
      { "name": "verify", "persona": "qa", "depth": "standard", "order": 5 }
    ],
    "adaptiveReason": "Complexity score 49/100 (moderate). Pipeline: standard."
  },
  "personas": { "current": { "name": "Systems Analyst", "identity": "...", "authority": [...], "notAuthority": [...], "handoffMessage": "..." } },
  "phase": "decompile",
  "phasePlan": [ { "name": "decompile", "status": "active" }, { "name": "design", "status": "locked" }, ... ],
  "instructions": "Fase DECOMPOSE (standar): Uraikan task ke komponen-komponen...",
  "memorySlots": { "originalTask": "...", "decompositions": [], "decisions": [], "constraints": [], "criticalQuestions": [] },
  "transparencyLog": { "entries": [], "count": 0 }
}

council_save

Saves phase output, scores it, detects contradictions, builds a handshake to the next phase.

Parameters:

| Field | Type | Required | Description | |-------|------|----------|-------------| | sessionId | string | ✅ | Session ID from council_init | | phase | string | ✅ | Phase name (decompile/design/critique/synthesis/verify) | | output | object | ✅ | Phase-specific output fields |

Phase-Specific Output Fields:

| Phase | Required Fields | Optional Fields | |-------|----------------|-----------------| | decompile | summary, decisions, constraints, confidence, criticalQuestions, claims | knowledgeBoundary | | design | summary, approaches, justification, tradeoffs, recommended, decisions | claims, knowledgeBoundary, confidence | | critique | summary, vulnerabilities, riskLevel, mitigation, confidence | claims, knowledgeBoundary, constraints | | synthesis | summary, implementation, testing, warnings | decisions, claims, knowledgeBoundary, confidence | | verify | summary, checks, passedCount, failedCount, finalConfidence | decision, recommendations, claims, knowledgeBoundary |

Response:

{
  "type": "council_save",
  "status": "saved",
  "phase": "decompile",
  "scoring": {
    "finalScore": 93,
    "verdict": "excellent",
    "dimensions": {
      "completeness": { "score": 100, "passed": [...], "failed": [] },
      "consistency": { "score": 100, "contradictions": [], "warnings": [] },
      "transparency": { "score": 87, "details": { "certainty": 35, "knowledgeBoundary": 32, "assumptions": 20 } },
      "agentic": { "score": 100, "violations": [] }
    }
  },
  "canProceed": true,
  "handoff": {
    "from": "decompile",
    "to": "design",
    "personaTransition": { "fromPersona": "Systems Analyst", "toPersona": "Solution Architect" },
    "conflicts": [],
    "handshake": { "fromAuthority": [...], "toAuthority": [...], "context": [...] }
  },
  "nextPhase": "design",
  "phasePlan": [ { "name": "decompile", "status": "locked" }, { "name": "design", "status": "active" }, ... ],
  "sessionComplete": false
}

council_recall

Retrieves session context for the AI to maintain state continuity.

Parameters:

| Field | Type | Required | Description | |-------|------|----------|-------------| | sessionId | string | ✅ | Session ID | | format | string | ❌ | "full" (default), "summary", or "decisions" |

Response:

{
  "type": "council_recall",
  "sessionId": "uuid",
  "status": "active",
  "progress": "2/5",
  "currentPhase": { "name": "design", "persona": "Solution Architect", "status": "active" },
  "phases": [{ "name": "decompile", "status": "done", "score": 93 }, { "name": "design", "status": "active", "score": null }],
  "summary": "...",
  "decisions": [...],
  "warnings": [],
  "transparencyLog": { "entries": [...], "count": 2 }
}

council_verify

Verifies claims against the session store — detects contradictions and checks grounding.

Parameters:

| Field | Type | Required | Description | |-------|------|----------|-------------| | sessionId | string | ✅ | Session ID | | claims | array | ✅ | Array of claims to verify: [{ text, source }] | | mode | string | ❌ | "contradiction", "grounding", or "all" (default) |

Response:

{
  "type": "council_verify",
  "mode": "all",
  "results": {
    "contradictions": [...],
    "grounding": { "verified": 1, "unverified": 1, "verifiedPct": 50 }
  },
  "summary": { "total": 2, "passed": 1, "failed": 1 }
}

council_continue

Resumes a session from where it left off — restores full context.

Parameters:

| Field | Type | Required | Description | |-------|------|----------|-------------| | sessionId | string | ✅ | Session ID |

Response:

{
  "type": "council_continue",
  "sessionId": "uuid",
  "status": "active",
  "currentPhase": { "name": "critique", "persona": "Security & Quality Auditor", "status": "active" },
  "personas": { "current": { ... } },
  "phasePlan": [...],
  "instructions": "...",
  "memorySlots": { ... },
  "transparencyLog": { ... }
}

council_score

Generates a final multi-dimensional quality assessment for the completed session.

Parameters:

| Field | Type | Required | Description | |-------|------|----------|-------------| | sessionId | string | ✅ | Session ID |

Response:

{
  "type": "council_score",
  "sessionId": "uuid",
  "overall": {
    "finalScore": 87,
    "verdict": "good",
    "qualityScore": 89,
    "adaptabilityScore": 85,
    "transparencyScore": 100,
    "agenticScore": 71
  },
  "phaseScores": {
    "decompile": { "score": 93, "verdict": "excellent" },
    "design": { "score": 93, "verdict": "excellent" },
    "critique": { "score": 82, "verdict": "good" },
    "synthesis": { "score": 91, "verdict": "excellent" },
    "verify": { "score": 82, "verdict": "good" }
  }
}

Phases & Personas

| Phase | Persona | Authority | Not Authority | |-------|---------|-----------|---------------| | decompile | Systems Analyst | Decompose tasks, identify constraints & hidden requirements, ask clarifying questions | ❌ No solutions ❌ No tech evaluation ❌ No design decisions | | design | Solution Architect | Define approaches, evaluate tradeoffs, recommend solutions | ❌ No implementation ❌ No code ❌ No detailed testing | | critique | Security & Quality Auditor | Identify risks, verify constraints, check security | ❌ No solutions ❌ No designs ❌ No implementation | | synthesis | Implementation Engineer | Write implementation steps, create test plans | ❌ No architecture changes ❌ No requirement changes | | verify | Quality Assurance | Run checks, validate completeness, approve/reject | ❌ No redesign ❌ No reimplementation |

Handshake Protocol

Each phase transition includes a formal handshake:

1. From Persona sends context + unresolved items
2. To Persona acknowledges context
3. Conflicts between phases are documented
4. Scoring ≥ 70 required to proceed to next phase

Three Core Principles

🔄 ADAPTIF — Adaptive Pipeline Depth

The server assesses task complexity and adjusts pipeline depth:

| Complexity Score | Level | Pipeline Depth | Description | |----------------|-------|---------------|-------------| | 0–20 | Simple | Light | decompile → synthesis → verify | | 21–60 | Moderate | Standard | decompile → design → critique → synthesis → verify | | 61–100 | Complex | Full | decompile → design → critique → synthesis → verify (deep) + looping |

Complexity factors:

• Baseline: 10
• Keywords per hit: +8 (migration, security, kubernetes, performance, etc.)
• Domain boost: +10 (migration/security/kubernetes/performance)
• Numbers detected: +5

👁️ TRANSPARANSI — Certainty & Knowledge Boundaries

5 Certainty Levels:

| Level | Label | Description | |-------|-------|-------------| | 1 | Confirmed | Verified from reliable source | | 2 | Likely | High confidence, not yet verified | | 3 | Uncertain | Need further investigation | | 4 | Unknown | No information available | | 5 | Assumption | Used as working hypothesis |

Knowledge Boundary tracking:

• whatIKnow — confidently known
• whatIAssume — working assumptions
• whatIDontKnow — known unknowns
• whatNeedsVerification — requires external validation

🤖 AGENTIC — Persona Authority

Each persona has defined:

• Identity — who they are
• Authority — what they CAN do
• Not Authority — what they CANNOT do
• Handoff Message — what they pass to the next persona

Authority violations (e.g., decompile suggesting a solution) are flagged with warnings and penalty scoring.

Scoring System

Per-Phase Scoring

| Dimension | Weight | Description | |-----------|--------|-------------| | Completeness | 25% | Required fields present, correct types, minimum lengths | | Consistency | 25% | No contradictions with previous phases (numerical, polarity, constraint compliance) | | Decision Quality | 15% | Quality of decisions made in the phase | | Structure | 10% | Structural organization of output | | Transparency | 15% | Certainty levels, knowledge boundaries, assumption flags | | Agentic | 10% | No authority violations, persona identity keywords present |

Score Thresholds

| Score Range | Verdict | Action | |-------------|---------|--------| | ≥ 90 | Excellent | Auto-proceed to next phase | | 70–89 | Good | Proceed to next phase | | 50–69 | Needs Improvement | Can still proceed, but review suggestions | | < 50 | Insufficient | Must improve before proceeding |

Final Session Score

Weighted aggregate of all phase scores plus cross-cutting assessments:

• Quality Score — average phase quality
• Adaptability Score — how well pipeline depth matches task
• Transparency Score — consistency of transparency across phases
• Agentic Score — authority compliance across phases

Testing

# Run full integration test (5 phases + final score)
node test_full.mjs

The test script:

1. Creates a session with a migration task
2. Runs all 5 phases (decompile → design → critique → synthesis → verify)
3. Verifies phase gating (cannot skip phases)
4. Tests recall and continue tools
5. Generates final council_score
6. Reports pass/fail for each step

Example output:

1. INIT          → moderate (49) 5ph persona:Systems Analyst
2. DECOMPILE     → 93 (excellent) proceed:true → design
3. DESIGN        → 93 (excellent) proceed:true → critique
4. CRITIQUE      → 82 (good) proceed:true → synthesis
5. SYNTHESIS     → 91 (excellent) proceed:true → verify
6. VERIFY        → 82 (good) proceed:true complete:true
7. SCORE         → 87 (good) q:89 a:85 t:100 ag:71

✅ 7/7 passed

Project Structure

mcp-council-server/
├── package.json
├── README.md
├── .env.example
├── .gitignore
├── src/
│   ├── index.js              # Entry point
│   ├── tools.js              # MCP tool handlers
│   ├── db/
│   │   └── json-store.js     # JSON file persistence
│   ├── memory/
│   │   ├── session.js        # Session lifecycle
│   │   ├── phase.js          # Phase state machine
│   │   ├── decision.js       # Decision trace
│   │   └── recall.js         # Context composer
│   ├── analysis/
│   │   └── parser.js         # Task parser
│   ├── prinsip/
│   │   ├── adaptive.js       # Complexity detection
│   │   ├── transparency.js   # Certainty & knowledge boundaries
│   │   └── agentic.js        # Personas & authority
│   ├── verify/
│   │   ├── contradiction.js  # Contradiction detection
│   │   └── grounding.js      # Claim verification
│   └── score/
│       ├── completeness.js   # Completeness checker
│       ├── consistency.js    # Consistency scoring
│       ├── transparency.js   # Transparency scoring
│       ├── agentic.js        # Agentic scoring
│       └── index.js          # Aggregator
├── test_flow.mjs             # Test script
├── test_debug.mjs            # Debug tool
└── test_full.mjs             # Full integration test

Why Not an Internal LLM?

Council does NOT call any LLM internally. Instead:

1. The AI (opencode/Claude/etc.) is the reasoner — it reads the tool responses, produces phase outputs, and makes decisions
2. Council provides the scaffolding — memory, state, structure, scoring, and guardrails
3. Pure deterministic logic — no API costs, no latency, no black-box behavior
4. Full transparency — every score, contradiction, and authority warning is explainable

This separation of concerns means:

• The AI stays focused on reasoning
• Council stays focused on structure and quality
• No vendor lock-in — works with any MCP-compatible AI

License

MIT © riflxz