mcp-council-server 4.0.0

package/README.md

@@ -0,0 +1,645 @@
+# 🏛️ 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 from npm
+npm install -g mcp-council-server
+
+# Or run directly with npx
+npx 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 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. Start the server
+
+```bash
+npm start
+```
+
+The server listens on **stdin/stdout** using the MCP stdio transport protocol.
+
+### 2. Connect with MCP Inspector
+
+```bash
+npm run inspect
+```
+
+### 3. Or use with any MCP client (e.g., opencode, Claude Desktop)
+
+Add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "council": {
+      "command": "node",
+      "args": ["/path/to/mcp-council-server/src/index.js"]
+    }
+  }
+}
+```
+
+### 4. Make your first call
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "council_init",
+    "arguments": {
+      "task": "Migrasi database MySQL ke PostgreSQL. 2GB data, downtime <30 menit. Handling JSON dan ENUM types."
+    }
+  }
+}
+```
+
+---
+
+## 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)

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "mcp-council-server",
+  "version": "4.0.0",
+  "type": "module",
+  "description": "Council MCP Server — AI reasoning scaffolding with memory, state, and persona-based phase orchestration for complex problem-solving via MCP protocol",
+  "main": "src/index.js",
+  "bin": {
+    "mcp-council-server": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node src/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.8.0",
+    "dotenv": "16.4.7",
+    "uuid": "11.0.3",
+    "zod": "3.23.8"
+  },
+  "author": {
+    "name": "riflxz",
+    "url": "https://github.com/riflxz"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/riflxz/mcp-council-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/riflxz/mcp-council-server/issues"
+  },
+  "homepage": "https://github.com/riflxz/mcp-council-server#readme",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "council",
+    "ai-scaffolding",
+    "reasoning",
+    "llm",
+    "agent",
+    "opencode",
+    "persona",
+    "orchestration"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ]
+}