Content
# 🏛️ 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**](https://github.com/riflxz)
---
## Table of Contents
- [How It Works](#how-it-works)
- [Features](#features)
- [Architecture](#architecture)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [MCP Tools Reference](#mcp-tools-reference)
- [council_init](#council_init)
- [council_save](#council_save)
- [council_recall](#council_recall)
- [council_verify](#council_verify)
- [council_continue](#council_continue)
- [council_score](#council_score)
- [Phases & Personas](#phases--personas)
- [Three Core Principles](#three-core-principles)
- [Scoring System](#scoring-system)
- [Testing](#testing)
- [Project Structure](#project-structure)
- [License](#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
```bash
# 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:
```json
{
"mcp": {
"council": {
"type": "local",
"command": ["npx", "-y", "mcp-council-server"]
}
}
}
```
Atau pake path lokal setelah clone:
```json
{
"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)
```bash
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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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
```bash
# 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](https://github.com/riflxz)
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available