atabey-mcp 0.0.12 → 0.0.13

package/README.md

@@ -6,94 +6,238 @@
 
 The **Model Context Protocol (MCP)** server for [Agent Atabey](https://www.npmjs.com/package/atabey).
 
-Bu paket, AI asistanları (Claude Code, Gemini CLI, Cursor, Antigravity CLI) ile yerel proje ortamınız arasında köprü görevi görür. 30+ araç ile güvenli, denetimli ve tip-güvenli bir etkileşim sağlar.
+This package bridges AI assistants (Claude Code, Gemini CLI, Cursor, Codex, Antigravity) with your local project environment. Provides **30+ secure, audited, type-safe tools** across 10 categories. Includes the **Hermes Control Center** dashboard with 8 live modules.
 
-## 🚀 Özellikler / Features
+> **Main Package:** [`atabey`](https://www.npmjs.com/package/atabey) (CLI + Framework)
 
-| Özellik | Açıklama |
-|---------|----------|
-| **Sıkı Yönetişim** | Zero Type Hole, Zero Console politikaları, AST analizi ile denetim |
-| **Cerrahi Düzenleme** | `patch_file` ve `replace_text` ile tam dosya yeniden yazımı yerine satır bazlı düzenleme |
-| **Hermes Message Broker** | Uzman ajanlar arası asenkron iletişim (`@manager`, `@architect`, `@security`, vb.) |
-| **Bellek Yönetimi** | Proje geçmişinin tamamını dökmek yerine hedeflenmiş, budanmış bağlam |
-| **Risk Engine** | Yüksek riskli işlemler için otomatik engelleme veya insan onayı |
+---
+
+## 📋 Table of Contents
 
-## 📦 Kurulum / Installation
+- [Installation](#installation)
+- [How It Works](#how-it-works)
+- [Hermes Control Center Dashboard](#hermes-control-center-dashboard)
+- [Provided Tools (30+)](#provided-tools-30)
+- [MCP Configuration](#mcp-configuration)
+- [Development](#development)
+- [Testing](#testing)
+
+---
+
+## Installation
 
 ```bash
-# Global kurulum (genelde init ile otomatik gelir)
+# Run with npx (no install needed)
+npx atabey-mcp
+
+# Global install
 npm install -g atabey-mcp
 
-# Projeye ekleme
+# Add to project
 npm install atabey-mcp
 ```
 
-## 🛠️ Sağlanan Araçlar / Provided Tools (30+)
-
-### 📁 Dosya Sistemi / File System
-| Araç | Açıklama |
-|------|---------|
-| `read_file` | Dosya okuma |
-| `write_file` | Dosya yazma |
-| `replace_text` | Metin değiştirme |
-| `patch_file` | Yama uygulama |
-| `batch_surgical_edit` | Toplu cerrahi düzenleme |
-| `list_dir` | Dizin listeleme |
-| `grep_search` | Regex arama |
-
-### 🎛️ Kontrol Paneli / Control Plane
-| Araç | Açıklama |
-|------|---------|
-| `acquire_lock` | Kaynak kilidi al |
-| `release_lock` | Kaynak kilidini bırak |
-| `register_agent` | Ajan kaydet |
-
-### 🔍 Arama & Haritalama / Search & Map
-| Araç | Açıklama |
-|------|---------|
-| `get_project_map` | Proje haritası |
-| `get_project_gaps` | Proje boşlukları |
-| `search_knowledge` | Bilgi tabanında ara |
-| `store_knowledge` | Bilgi tabanına ekle |
-
-### 📊 Kalite & Gözlem / Quality & Observability
-| Araç | Açıklama |
-|------|---------|
-| `check_lint` | Lint kontrolü |
-| `check_compliance` | Uyumluluk denetimi |
-| `run_tests` | Test çalıştır |
-| `get_system_health` | Sistem sağlığı |
-| `check_active_ports` | Port denetimi |
-| `audit_dependencies` | Bağımlılık denetimi |
-
-### 💬 Mesajlaşma / Messaging
-| Araç | Açıklama |
-|------|---------|
-| `send_agent_message` | Ajanlar arası mesaj |
-| `log_agent_action` | Ajan eylemlerini logla |
-
-### 🧠 Bellek & Framework / Memory & Framework
-| Araç | Açıklama |
-|------|---------|
-| `read_project_memory` | Proje hafızasını oku |
-| `update_project_memory` | Proje hafızasını güncelle |
-| `get_memory_insights` | Bellek içgörüleri |
-| `get_framework_status` | Framework durumu |
-
-### ⚡ Çalıştırma / Execution
-| Araç | Açıklama |
-|------|---------|
-| `run_shell_command` | Shell komutu çalıştır |
-| `run_tests` | Test çalıştır |
-
-## 🔧 Claude Code ile Kullanım
+---
+
+## How It Works
+
+Atabey MCP Server connects your AI assistant to your project via the **Model Context Protocol**:
+
+```
+AI Assistant (Claude/Gemini/Cursor)
+       │
+       ▼  MCP Protocol (stdio transport)
+       │
+Atabey MCP Server (30+ tools)
+       │
+       ▼
+Your Project (files, database, git, shell)
+```
+
+When you type `@backend Create login API` in your AI chat:
+1. The AI calls `send_agent_message` tool via MCP
+2. Atabey routes it through `RoutingEngine`
+3. The `@backend` agent executes the task
+4. `QualityGate` validates the output
+5. Result is stored in `Vector Memory`
+
+**No separate terminal needed. No CLI commands for daily use.**
+
+---
+
+## Hermes Control Center Dashboard
+
+The MCP package includes a real-time WebSocket dashboard with 8 live modules:
+
+| Module | Description | Update |
+|--------|-------------|--------|
+| 🤖 **Agent Monitor** | 13 AI agent status + live tasks | WS (5s) |
+| 📨 **Hermes Messages** | Agent message queue + filtering | WS (5s) |
+| 🔐 **Approval Center** | Human-in-the-Loop approvals | WS |
+| 📋 **Task Planner** | Task DAG + progress tracking | REST (5s) |
+| 📝 **Agent Logs** | Execution logs + agent filter | WS (5s) |
+| ⚠️ **Error Tracker** | Lint/compliance/security errors | WS |
+| 🧠 **Memory Insights** | Vector memory search | REST |
+| 🛡️ **Compliance** | Quality gate violations | REST (15s) |
+
+```bash
+# Start dashboard (default port: 5858)
+npx atabey dashboard
+# Browser: http://localhost:5858
+```
+
+### Dashboard Components
+
+```
+framework-mcp/dashboard/src/
+├── App.tsx                    # Main app, routing and WS management
+├── main.tsx                   # React entry point
+├── styles.ts                  # PandaCSS styles
+├── components/
+│   ├── AdapterSkillsPanel.tsx # Adapter skill mapping
+│   ├── AgentMonitor.tsx       # Agent status monitoring
+│   ├── ApprovalCenter.tsx     # Approval center
+│   ├── CompliancePanel.tsx    # Compliance control panel
+│   ├── ErrorTracker.tsx       # Error tracking
+│   ├── GatewayPanel.tsx       # LLM Gateway management
+│   ├── HermesBrokerView.tsx   # Hermes message queue
+│   ├── HermesStats.tsx        # Hermes statistics
+│   ├── LogViewer.tsx          # Log viewer
+│   ├── MemoryInsights.tsx     # Memory insights
+│   ├── PlanViewer.tsx         # Plan viewer
+│   └── QualityPanel.tsx       # Quality panel
+└── hooks/
+    ├── useApi.ts              # REST API hook
+    └── useWS.ts               # WebSocket hook
+```
+
+---
+
+## Provided Tools (30+)
+
+### File System
+
+| Tool | Description | Zod Validation |
+|------|-------------|----------------|
+| `read_file` | Read file content with line range | ✅ |
+| `write_file` | Atomic file write with directory creation | ✅ |
+| `replace_text` | Surgical text replacement | ✅ |
+| `patch_file` | Safe line-range update | ✅ |
+| `batch_surgical_edit` | Multi-file batch editing | ✅ |
+
+### Search & Exploration
+
+| Tool | Description |
+|------|-------------|
+| `list_dir` | List directory contents |
+| `grep_search` | Recursive regex search |
+| `get_project_map` | Project structure tree |
+| `get_project_gaps` | Find TODOs, FIXMEs, gaps |
+
+### Control Plane
+
+| Tool | Description |
+|------|-------------|
+| `acquire_lock` | Acquire resource lock |
+| `release_lock` | Release resource lock |
+| `register_agent` | Register agent instance |
+
+### Messaging (Hermes Protocol)
+
+| Tool | Description |
+|------|-------------|
+| `send_agent_message` | Hermes protocol messaging |
+| `log_agent_action` | Log agent actions |
+| `ask_human` | Wait for human input |
+
+### Memory
+
+| Tool | Description |
+|------|-------------|
+| `read_project_memory` | Read central memory |
+| `update_project_memory` | Update memory section |
+| `get_memory_insights` | Memory summaries |
+| `store_knowledge` | Store vector knowledge |
+| `search_knowledge` | Search vector memory |
+| `delete_knowledge` | Delete knowledge entry |
+
+### Framework & Quality
+
+| Tool | Description |
+|------|-------------|
+| `get_framework_status` | Framework status |
+| `run_tests` | Run test suites |
+| `check_lint` | Run ESLint |
+| `update_contract_hash` | Sync contract hash |
+| `orchestrate_loop` | Process Hermes messages |
+| `submit_plan` | Submit DAG task plan |
+| `audit_dependencies` | Audit package.json |
+| `get_system_health` | CPU/RAM metrics |
+| `check_active_ports` | Port monitoring |
+
+### Quality
+
+| Tool | Description |
+|------|-------------|
+| `analyze_code_quality` | Code quality analysis |
+| `check_architecture_compliance` | Architecture compliance check |
+| `check_lint` | ESLint validation |
+
+### Observability
+
+| Tool | Description |
+|------|-------------|
+| `get_health` | System health |
+| `check_ports` | Port status |
+
+### Shell
+
+| Tool | Description |
+|------|-------------|
+| `run_shell_command` | Execute shell commands |
+
+---
+
+## LLM Gateway Tools
+
+### `llm_gateway_query`
+
+Sends queries to LLM providers with load balancing, circuit breaker, and rate limiting.
+
+**Parameters:**
+- `provider` (string): LLM provider name (`openai`, `anthropic`, `google`, `groq`, `ollama`)
+- `model` (string): Model name
+- `messages` (array): Chat messages
+- `options` (object, optional): Temperature, max tokens, etc.
+
+### `llm_gateway_status`
+
+Returns gateway status and provider statistics.
+
+**Supported Providers:**
+
+| Provider | Models | Status |
+|----------|--------|--------|
+| OpenAI | GPT-4, GPT-4o, o3, o4-mini | ✅ |
+| Anthropic | Claude Opus 4.5, Sonnet 4.5, Haiku 3.5 | ✅ |
+| Google | Gemini 2.5 Pro, Flash, Flash-Lite | ✅ |
+| Groq | Llama, Mixtral | ✅ |
+| Ollama | Local models | ✅ |
+
+---
+
+## MCP Configuration
+
+### Claude Code
+
+Add to your `mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "atabey": {
-      "command": "node",
-      "args": ["/path/to/atabey-mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["atabey-mcp"],
       "env": {
         "ATABEY_PROJECT_ROOT": "/path/to/your/project"
       }
@@ -102,14 +246,117 @@ npm install atabey-mcp
 }
 ```
 
-## 📖 Daha Fazla Bilgi
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ATABEY_PROJECT_ROOT` | Project root directory | `process.cwd()` |
+| `PORT` or `DASHBOARD_PORT` | Dashboard port | `5858` |
+| `NODE_ENV` | Environment (production/development) | `development` |
+
+### Gemini CLI
+
+```bash
+gemini config set mcpServers.atabey.command "npx"
+gemini config set mcpServers.atabey.args "[\"atabey-mcp\"]"
+```
+
+### Cursor
+
+```json
+// .cursor/mcp.json
+{
+  "mcpServers": {
+    "atabey": {
+      "command": "npx",
+      "args": ["atabey-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Build dashboard
+npm run build --prefix dashboard
+
+# Development mode
+npm run dev
+```
+
+### Project Structure
+
+```
+framework-mcp/
+├── src/
+│   ├── index.ts            # MCP Server (Stdio Transport)
+│   ├── constants.ts        # MCP-specific constants
+│   ├── declarations.d.ts   # Type declarations
+│   ├── resources/          # MCP Resources
+│   ├── tools/
+│   │   ├── definitions.ts  # Tool definitions
+│   │   ├── index.ts        # Tool handlers
+│   │   ├── schemas.ts      # Zod validation schemas
+│   │   ├── types.ts        # Tool types
+│   │   ├── control_plane/  # Lock, Registry
+│   │   ├── file_system/    # Read, Write, Edit, Patch
+│   │   ├── framework/      # Status, Test, Orchestrate
+│   │   ├── gateway/        # LLM Gateway
+│   │   ├── memory/         # Knowledge management
+│   │   ├── messaging/      # Hermes messaging
+│   │   ├── observability/  # Health, Port
+│   │   ├── quality/        # Code quality
+│   │   ├── search/         # Grep, Map, Gap
+│   │   └── shell/          # Command execution
+│   └── utils/              # Utilities
+├── dashboard/              # React Dashboard
+└── tests/                  # Tests
+```
+
+---
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test
+npx vitest run tests/tools/file_system/file_system_tools.test.ts
+```
+
+### Current Test Files
+
+| Test File | Scope |
+|-----------|-------|
+| `file_system/file_system_tools.test.ts` | Basic file system tools |
+| `file_system/compliance-risk.test.ts` | Compliance risk analysis |
+| `file_system/permissions.test.ts` | Permission controls |
+| `messaging/send_message.test.ts` | Hermes messaging |
+| `quality/check_lint.test.ts` | ESLint validation |
+| `shell/run_command.test.ts` | Shell commands |
+
+> **Note:** Gateway module tests are in the main package: `tests/modules/gateway/`
+
+---
 
-Tüm dokümantasyon, mimari detaylar ve kurumsal iletişim için ana depoyu ziyaret edin:
+## More Information
 
-- **Ana Paket:** [atabey](https://www.npmjs.com/package/atabey)
+- **Main Package:** [`atabey`](https://www.npmjs.com/package/atabey) (CLI + Framework)
 - **GitHub:** [github.com/ysf-bkr/atabey](https://github.com/ysf-bkr/atabey)
+- **Documentation:** [ARCHITECTURE.md](../ARCHITECTURE.md)
+- **Contributing:** [CONTRIBUTING.md](../CONTRIBUTING.md)
 - **Enterprise:** ybekar@msn.com
 
 ---
 
-*Developed by **Yusuf BEKAR** — "Order from Chaos"*
+*Developer: **Yusuf BEKAR** — "Order from Chaos"*