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
- How It Works
- Features
- Architecture
- Installation
- Quick Start
- MCP Tools Reference
- Phases & Personas
- Three Core Principles
- Scoring System
- Testing
- Project Structure
- License
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 │
└──────────────────────┘
| 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 |
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
Tool Call → tools.js handler → memory/* → analysis/* → prinsip/*
↓ ↓
verify/* ←─────────────── score/*
↓
JSON response to MCP client
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 |
# 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- Node.js >= 18.0.0
- No native compilation needed — works on arm64 Linux (Node.js v26+)
- No database — pure JSON file persistence
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.
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 startIni adalah contoh sesi nyata menggunakan Council + opencode. Setiap langkah menunjukkan tool yang dipanggil dan respons yang diterima AI.
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.
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
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 |
Setelah semua fase selesai, AI memanggil council_score:
overall: 87 (good)
quality: 89 | adaptability: 85 | transparency: 100 | agentic: 71
| 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. |
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 }
}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
}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 }
}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 }
}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": { ... }
}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" }
}
}| 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 |
Each phase transition includes a formal handshake:
- From Persona sends context + unresolved items
- To Persona acknowledges context
- Conflicts between phases are documented
- Scoring ≥ 70 required to proceed to next phase
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
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 knownwhatIAssume— working assumptionswhatIDontKnow— known unknownswhatNeedsVerification— requires external validation
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.
| 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 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 |
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
# Run full integration test (5 phases + final score)
node test_full.mjsThe test script:
- Creates a session with a migration task
- Runs all 5 phases (decompile → design → critique → synthesis → verify)
- Verifies phase gating (cannot skip phases)
- Tests recall and continue tools
- Generates final council_score
- 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
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
Council does NOT call any LLM internally. Instead:
- The AI (opencode/Claude/etc.) is the reasoner — it reads the tool responses, produces phase outputs, and makes decisions
- Council provides the scaffolding — memory, state, structure, scoring, and guardrails
- Pure deterministic logic — no API costs, no latency, no black-box behavior
- 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
MIT © riflxz