atabey-mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,12 +1,21 @@
-# [GOV] Atabey MCP — MCP Server for AI Governance & Multi-Agent Platform / Orchestrator
+# [GOV] Atabey MCP — MCP Server for AI Governance & Multi-Agent Orchestration
 
-[![Version](https://img.shields.io/badge/Version-v0.1.0-blue.svg)](https://github.com/ysf-bkr/atabey)
+[![Version](https://img.shields.io/badge/Version-v0.1.2-blue.svg)](https://github.com/ysf-bkr/atabey)
 [![npm](https://img.shields.io/npm/v/atabey-mcp)](https://www.npmjs.com/package/atabey-mcp)
 [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
 [![MCP Tools](https://img.shields.io/badge/MCP%20Tools-40-blue)](https://github.com/ysf-bkr/atabey)
 
-**Atabey MCP** is the MCP (Model Context Protocol) server component of the Atabey framework. It provides 40 MCP tools, a multi-layer governance pipeline (validation, PII masking, discipline, loop detection, token limits, CRUD governance, risk gating, and more), vector memory, risk engine, loop detection, token accounting, auto-rollback, prompt injection protection, and a real-time WebSocket event stream.
+**Atabey MCP** is the MCP (Model Context Protocol) server component of the Atabey framework. It provides **40 MCP tools** and a multi-layer governance pipeline (validation, PII masking, discipline, loop detection, token limits, CRUD governance, risk gating and more), vector memory, risk engine, auto-rollback, prompt-injection protection and a real-time event stream.
+
+**Atabey** is a **local AI control plane & discipline layer** that sits between your
+codebase and your local AI coding assistants. It does **not** write code and does **not**
+host an LLM — it **disciplines, bounds and coordinates** the assistant you already use
+through the Model Context Protocol (MCP).
+
+> "Order from Chaos" — keeps AI coding assistants focused, blocks destructive actions,
+> rolls back broken edits, prevents runaway token loops, and records an audit trail.
+
 
 ---
 
@@ -15,11 +24,11 @@
 | Capability | Description |
 |-----------|-------------|
 | **MCP Tools** | 40 tools across 9 categories: file system, search, messaging, governance, memory, quality, network, orchestration, API catalog |
-| **Governance Pipeline** | Multi-layer pre/post execution validation: PII masking, risk gate, discipline, loop detection, token limits, license scan, CRUD governance, and more |
-| **Memory** | Vector memory with TF-IDF/OpenAI embeddings, project memory, knowledge base |
-| **Observability** | Headless HTTP/SSE server (`/mcp/*`) and a real-time WebSocket event stream (agents, Hermes, token accounting, compliance, loop detection) |
-| **Auth** | Bearer token authentication for HTTP/SSE mode |
-| **Multi-Transport** | Stdio (per-developer) + HTTP/SSE (team server) |
+| **Governance Pipeline** | Multi-layer pre/post execution validation: PII masking, risk gate, discipline, loop detection, token limits, license scan, CRUD governance |
+| **Memory** | Vector memory (TF-IDF/OpenAI embeddings), project memory, knowledge base |
+| **Observability** | Headless HTTP/SSE server (`/mcp/*`) + real-time WebSocket event stream |
+| **Auth** | Bearer-token authentication for HTTP/SSE mode |
+| **Transport** | Stdio (per-developer) + HTTP/SSE (team server) |
 
 ---
 
@@ -32,12 +41,13 @@ npm install -g atabey-mcp
 ## Quick Start
 
 ```bash
-# Start MCP server (stdio mode)
+# Stdio mode (default — spawned by your IDE/CLI)
 atabey-mcp
 
-# Start unified HTTP/SSE server
+# Unified HTTP/SSE server
 MCP_TRANSPORT=unified MCP_PORT=5858 atabey-mcp
-# API: http://localhost:5858/api    WS: ws://localhost:5858/ws
+# MCP SSE:    http://localhost:5858/mcp/sse
+# Hermes Bus: ws://localhost:5858/bus
 ```
 
 ---
@@ -47,7 +57,7 @@ MCP_TRANSPORT=unified MCP_PORT=5858 atabey-mcp
 ### File System (5)
 | Tool | Description |
 |------|-------------|
-| `read_file` | Read file content with line range support |
+| `read_file` | Read file content with line-range support |
 | `write_file` | Write content to file, auto-create directories |
 | `replace_text` | Surgical string replacement |
 | `batch_surgical_edit` | Multi-file batch surgical edits |
@@ -59,7 +69,7 @@ MCP_TRANSPORT=unified MCP_PORT=5858 atabey-mcp
 | `list_dir` | List directory contents |
 | `grep_search` | Recursive regex search |
 | `get_project_map` | Tree-view project structure |
-| `get_project_gaps` | TODO/FIXME/empty function scan |
+| `get_project_gaps` | TODO/FIXME/empty-function scan |
 | `get_symbol_outline` | AST-lite symbol map with line ranges |
 | `get_task_context` | Targeted context bundle from the CodeGraph (no repo re-scan) |
 
@@ -77,33 +87,33 @@ MCP_TRANSPORT=unified MCP_PORT=5858 atabey-mcp
 | `get_system_health` | CPU/RAM metrics |
 | `check_active_ports` | Active port scan |
 | `get_framework_status` | Phase, trace, agent states |
-| `read_project_memory` | Read PROJECT_MEMORY.md |
+| `read_project_memory` | Read `PROJECT_MEMORY.md` |
 | `get_memory_insights` | Memory summary |
 | `update_project_memory` | Update memory |
 | `orchestrate_loop` | Process Hermes messages |
-| `submit_plan` | Submit DAG plan |
+| `submit_plan` | Submit a DAG plan |
 
 ### Control Plane (3)
 | Tool | Description |
 |------|-------------|
-| `acquire_lock` | Lock shared resource |
-| `release_lock` | Release lock |
-| `register_agent` | Register agent instance |
+| `acquire_lock` | Lock a shared resource |
+| `release_lock` | Release a lock |
+| `register_agent` | Register an agent instance |
 
 ### Memory & Knowledge (4)
 | Tool | Description |
 |------|-------------|
 | `store_knowledge` | Store to vector memory |
 | `search_knowledge` | Search vector memory |
-| `delete_knowledge` | Delete knowledge entry |
+| `delete_knowledge` | Delete a knowledge entry |
 | `update_contract_hash` | Update contract hash |
 
 ### Messaging & Human (3)
 | Tool | Description |
 |------|-------------|
 | `send_agent_message` | Hermes agent-to-agent message |
-| `log_agent_action` | Log to framework |
-| `ask_human` | Ask developer a question |
+| `log_agent_action` | Log to the framework |
+| `ask_human` | Ask the developer a question |
 
 ### Compliance & Quality (4)
 | Tool | Description |
@@ -116,64 +126,62 @@ MCP_TRANSPORT=unified MCP_PORT=5858 atabey-mcp
 ### Operations (3)
 | Tool | Description |
 |------|-------------|
-| `approve_operation` | In-chat risk gate approval |
-| `http_proxy_request` | Secure HTTP proxy |
+| `approve_operation` | In-chat risk-gate approval |
+| `http_proxy_request` | Secure HTTP proxy (SSRF-guarded) |
 | `audit_dependencies` | Unused package audit |
 
----
-
-## 🔐 Multi-Layer Governance Pipeline
+## Multi-Layer Governance Pipeline
 
-Every MCP tool call passes through this pipeline:
+Every MCP tool call passes through this **fail-closed** pipeline:
 
 ```
 CallToolRequest
     ↓
- 1. [VALIDATION]      Zod schema validation
- 2. [GOVERNANCE]      validateArgsAgainstRules()
- 3. [DISCIPLINE]      enforceDiscipline()
- 4. [LOOP DETECTION]  recordAndCheck() + cooldown
- 5. [TOKEN LIMITS]    enforceTokenBudgetPreCall() + checkTokenBudget()
- 6. [LICENSE]         validateLicenseCompliance()
- 7. [AUTO-ROLLBACK]   prepareWrite() snapshot
- 8. [HUMAN-IN-LOOP]   RiskEngine.assessTaskRisk() + checkRiskGate()
- 9. [PII MASKING]     maskToolArgs() → mask before handler
- 10. [EXECUTION]      Tool handler runs
- 11. [POST-VALIDATION] scanFileForViolations() → rollback if needed
- 12. [INJECTION PROTECTION] sanitizeResponse()
- 13. [PII MASKING]    maskToolResult() → mask before returning to AI
+ 1. [VALIDATION]       Zod schema validation
+ 2. [GOVERNANCE]       validateArgsAgainstRules()
+ 3. [DISCIPLINE]       enforceDiscipline()
+ 4. [LOOP DETECTION]   recordAndCheck() + cooldown
+ 5. [TOKEN LIMITS]     enforceTokenBudgetPreCall() + checkTokenBudget()
+ 6. [LICENSE]          validateLicenseCompliance()
+ 7. [AUTO-ROLLBACK]    prepareWrite() snapshot
+ 8. [HUMAN-IN-LOOP]    RiskEngine.assessTaskRisk() + checkRiskGate()
+ 9. [PII MASKING]      maskToolArgs() → mask before handler
+10. [EXECUTION]        Tool handler runs
+11. [POST-VALIDATION]  scanFileForViolations() → rollback if needed
+12. [INJECTION PROTECTION] sanitizeResponse()
+13. [PII MASKING]      maskToolResult() → mask before returning to AI
     ↓
-  Return governed result
+ Return governed result
 ```
 
+A control that cannot run **denies** the operation rather than passing it silently.
+
+
 ### Pipeline Details
 
 | Layer | Module | Description |
 |-------|--------|-------------|
 | **Validation** | `zod-to-mcp.ts` | All tool inputs validated against Zod schemas |
 | **Governance** | `rules-engine.ts` | Pre-execution argument validation against governance rules |
-| **Discipline** | `discipline.ts` | AI behavior enforcement: rate limiting, file size limits, tool blacklist |
-| **Loop Detection** | `loop-detector.ts` | Blocks >10 consecutive same-tool calls, cooldown mechanism |
-| **Token Limits** | `context/context-optimizer.ts` | Per-provider token/rate ceilings, cooldowns, smart file truncation |
-| **License** | `license-scanner.ts` | Copyleft license detection in write operations |
+| **Discipline** | `discipline.ts` | Rate limiting, file-size limits, tool blacklist |
+| **Loop Detection** | `loop-detector.ts` | Blocks >10 consecutive same-tool calls, cooldown |
+| **Token Limits** | `context/context-optimizer.ts` | Per-provider token/rate ceilings, cooldowns, smart truncation |
 | **Auto-Rollback** | `auto-rollback.ts` | Pre-write snapshot, post-write governance scan, automatic restore |
-| **Human-in-Loop** | `human-in-loop.ts` | Risk score ≥ 60 requires approval via `approve_operation` tool |
+| **Human-in-Loop** | `human-in-loop.ts` | Risk score ≥ 60 requires approval via `approve_operation` |
 | **PII Masking** | `pii.ts` | 20+ PII patterns masked before/after handler execution |
-| **Injection Protection** | `prompt-injection.ts` | OWASP LLM01 compliant: role-playing, override, jailbreak detection |
+| **Injection Protection** | `prompt-injection.ts` | OWASP LLM01: role-play, override, jailbreak detection |
 
 ---
 
 ## 🧠 Memory & Knowledge
 
 ### Vector Memory
-```typescript
+```
 store_knowledge(content, category, tags) → generateEmbedding() → VectorStore.addEntry()
 search_knowledge(query) → generateEmbedding() → VectorStore.search() → cosine similarity sort
-delete_knowledge(id) → SQLite DELETE
 ```
-
 - **Technology**: SQLite + Float32Array vectors
-- **Embedding**: OpenAI text-embedding-3-small (1536-dim) or TF-IDF fallback (384-dim)
+- **Embedding**: OpenAI `text-embedding-3-small` (1536-dim) or TF-IDF fallback (384-dim)
 - **Categories**: ARCHITECTURE, DECISION, CODE_SNIPPET, RULE, TASK_HISTORY
 
 ### Knowledge Base
@@ -181,6 +189,23 @@ delete_knowledge(id) → SQLite DELETE
 - Retrieval via the `search_knowledge` / `read_project_memory` MCP tools
 - PII masked on all responses
 
+## 3-Layer Memory System
+
+| Layer | Storage | Technology | Purpose |
+|-------|---------|------------|---------|
+| **Vector Memory** | SQLite | TF-IDF / OpenAI embeddings + cosine similarity | Semantic search across project knowledge |
+| **Project Memory** | Markdown | `PROJECT_MEMORY.md` | Central project state, synchronized every session |
+| **Specialty Memory** | Markdown | `.atabey/memory/specialties/{agent}.md` | Per-agent learned conventions from past tasks |
+
+```
+Task → Evaluation Engine → Score (0-100)
+  ├── Success → extractSuccessLesson() → updateSpecialtyMemory()
+  └── Failure → compliance/lint/test lesson → updateSpecialtyMemory()
+       ↓
+  Next session: readLearnedConventions() → injected into agent prompt
+```
+
+
 ---
 
 ## 🌐 Unified HTTP/SSE Server
@@ -191,8 +216,6 @@ MCP_TRANSPORT=unified MCP_PORT=5858 atabey-mcp
 # Hermes Bus: ws://localhost:5858/bus
 ```
 
-The unified server exposes two network surfaces (no bundled web UI):
-
 | Endpoint | Description |
 |----------|-------------|
 | `GET /mcp/health` | Server health + active session count |
@@ -204,61 +227,65 @@ The unified server exposes two network surfaces (no bundled web UI):
 
 ## 🔌 MCP Transport Modes
 
-### Stdio Mode (Default - Per Developer)
+### Stdio Mode (default — per developer)
 ```bash
 atabey-mcp
-# Connects via stdin/stdout JSON-RPC
+# Connects via stdin/stdout JSON-RPC (no network exposure)
 ```
 
-### HTTP/SSE Mode (Team Server)
+### HTTP/SSE Mode (team server)
 ```bash
 MCP_TRANSPORT=unified MCP_PORT=5858 atabey-mcp
 ```
 ```json
-// Client mcp.json:
 {
   "mcpServers": {
-    "atabey": {
-      "url": "http://192.168.1.100:5858/mcp/sse"
-    }
+    "atabey": { "url": "http://192.168.1.100:5858/mcp/sse" }
   }
 }
 ```
 
-### Authentication (HTTP/SSE Mode)
+### Authentication (HTTP/SSE mode)
 ```bash
 export MCP_AUTH_TOKEN="your-secret-token"
 export MCP_AUTH_USERS="alice:key1,bob:key2"
 ```
 
----
+## Security & Compliance
+
+### Deterministic, fail-closed governance
+- AST-based compliance scanning + strict TypeScript (**`any` is forbidden**, no `console.*` in production code)
+- **Fail-closed PolicyGate** + deny-by-default RBAC permission matrix (protected paths: `.env*`, `.git/`, `.ssh/`, `.atabey/*`, keys)
+- **Prompt-injection protection** (OWASP LLM01) on both input and response
+- **Secret-leak redaction** on tool output + AES-256-GCM local secret vault
+- **HMAC-SHA256** tamper-evident audit chain
+- SSRF-guarded HTTP proxy (private IP / metadata / DNS-rebinding protection)
+- **TLS 1.3 + optional mTLS** on the unified HTTP/SSE transport
+- Human-in-the-Loop: risk score ≥ 60 requires approval
+
+### KVKK / GDPR technical alignment
+
+| Feature | KVKK | GDPR | Status |
+|---------|------|------|--------|
+| PII Masking (20+ patterns) | Art. 4, 5, 11, 12 | Art. 5, 32 | ✅ |
+| Data Retention (30–730 days, by category) | Art. 5, 7 | Art. 5, 17 | ✅ |
+| Right to Erasure (`atabey audit erase`) | Art. 7 | Art. 17 | ✅ |
+| Audit Trail | Art. 11 | Art. 30 | ✅ |
+| Data Classification | Art. 6 | Art. 9 | ✅ |
+
+> Technical compliance tooling — not legal certification. Pair with your DPO / counsel.
+
+
+## Token Efficiency
+
+Atabey keeps token consumption low at three layers — **there is no monetary budget layer**:
+
+1. **Measurement** — every tool call is counted with the real `cl100k_base` BPE tokenizer (input/output split).
+2. **Limits** — per-provider context / response / per-minute / per-hour and tool-call rate ceilings (`context-optimizer.ts`). A breach sets a cooldown; hard blocking is opt-in via `ATABEY_TOKEN_BUDGET_ENFORCE=true`.
+3. **Savings** — `read_file` responses are smart-truncated (imports/types/signatures preserved), `http_proxy` caches + strips HTML, loop detection stops token-burning loops, and `get_task_context` / `get_symbol_outline` / `get_api_catalog` feed the AI pre-indexed context instead of forcing full-repo scans.
+
+Tune limits with `MCP_MAX_TOKENS_PER_MINUTE`, `MCP_MAX_TOKENS_PER_HOUR`, `MCP_MAX_CONTEXT_TOKENS`, `MCP_MAX_FILE_READ_SIZE`.
 
-## 🔒 Security Features
-
-### PII Masking (KVKK/GDPR)
-| Pattern | Example | Masked |
-|---------|---------|--------|
-| Email | `user@example.com` | `***@***` |
-| Phone | `+90 555 123 45 67` | `***-***-****` |
-| TC ID | `12345678901` | `***********` |
-| API Key | `sk-abc...xyz` | `***-REDACTED-***` |
-| JWT Token | `eyJ...eyJ...` | `***-JWT-REDACTED-***` |
-| IP Address | `192.168.1.1` | `***.***.***.***` |
-| Credit Card | `4111 1111 1111 1111` | `****-****-****-****` |
-| IBAN | `TR33...1326` | `****-IBAN-REDACTED-****` |
-
-### AI Discipline Engine
-- **Rate Limiting**: Max 60 calls/minute per agent
-- **File Size Limits**: Prevents >1MB files
-- **Loop Detection**: Blocks >10 consecutive same-tool calls
-- **Cooldown**: Automatic when limits exceeded
-- **Injection Protection**: OWASP LLM01 compliant
-
-### Token Efficiency
-- Every tool call is measured with the real `cl100k_base` BPE tokenizer (input/output split)
-- Per-provider context/response/per-minute/per-hour + tool-call rate ceilings
-- Smart truncation of oversized `read_file` responses (imports/types/signatures preserved)
-- Optional hard blocking via `ATABEY_TOKEN_BUDGET_ENFORCE=true` (default: advisory)
 
 ---
 
@@ -299,7 +326,16 @@ packages/atabey-mcp/
 - **ws**: WebSocket (Hermes WSS bus)
 - **typescript**: Compiler API for AST compliance scanning
 
----
+## 🔗 Related Packages
+
+| Package | Role | Links |
+|---------|------|-------|
+| **atabey** | Core engine — CLI, agents, engines, orchestrator | [npm](https://www.npmjs.com/package/atabey) · [source](https://github.com/ysf-bkr/atabey/tree/main/packages/atabey) |
+| **atabey-mcp** | MCP server — 40 tools & governance pipeline | [npm](https://www.npmjs.com/package/atabey-mcp) · [source](https://github.com/ysf-bkr/atabey/tree/main/packages/atabey-mcp) |
+| **atabey-shared** | Shared utilities — constants, storage, PII, audit, locks | [npm](https://www.npmjs.com/package/atabey-shared) · [source](https://github.com/ysf-bkr/atabey/tree/main/packages/shared) |
+
+> Full bilingual documentation (TR + EN): **[github.com/ysf-bkr/atabey](https://github.com/ysf-bkr/atabey#readme)**
+
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atabey-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Atabey — Local AI Control Plane & Discipline Layer — MCP Server",
   "author": "Yusuf BEKAR",
   "license": "AGPL-3.0",
@@ -51,11 +51,11 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "lint": "eslint src tests --ext .ts",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "node ../../scripts/build-readmes.mjs && npm run build"
   },
   "dependencies": {
-    "atabey": "^0.1.0",
-    "atabey-shared": "^0.1.0",
+    "atabey": "^0.1.2",
+    "atabey-shared": "^0.1.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^13.0.2",
     "chalk": "^5.6.2",