Skip to content

About

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.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 

Repository files navigation

🏛️ 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

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

About

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.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages