mcp-council-server 4.0.0 → 4.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 riflxz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -166,16 +166,17 @@ Six collections in `./data/`:
 ## Installation
 
 ```bash
-# Install from npm
+# Install globally
 npm install -g mcp-council-server
 
-# Or run directly with npx
-npx 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
 ```
 
@@ -188,51 +189,125 @@ npm start
 
 ## Quick Start
 
-### 1. Start the server
+### 1. Integrasi dengan opencode (recommended)
 
-```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:
+Di `~/.config/opencode/opencode.json`, tambahkan:
 
 ```json
 {
-  "mcpServers": {
+  "mcp": {
     "council": {
-      "command": "node",
-      "args": ["/path/to/mcp-council-server/src/index.js"]
+      "type": "local",
+      "command": ["npx", "-y", "mcp-council-server"]
     }
   }
 }
 ```
 
-### 4. Make your first call
+Atau pake path lokal setelah clone:
 
 ```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": {
+    "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