atabey-mcp 0.0.11 → 0.0.13

package/README.md

@@ -1,48 +1,362 @@
 # Agent Atabey — MCP Server (`atabey-mcp`)
 
-[![Version](https://img.shields.io/npm/v/atabey-mcp.svg)](https://npmjs.com/package/atabey-mcp)
+[![Version](https://img.shields.io/npm/v/atabey-mcp.svg)](https://www.npmjs.com/package/atabey-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/dt/atabey-mcp)](https://www.npmjs.com/package/atabey-mcp)
 
-The **Model Context Protocol (MCP)** server for [Agent Atabey](https://npmjs.com/package/atabey). 
+The **Model Context Protocol (MCP)** server for [Agent Atabey](https://www.npmjs.com/package/atabey).
 
-This package acts as the bridge between AI Assistants (like Claude Desktop, Cursor, or Antigravity CLI) and your local project environment. It provides a highly governed, type-safe set of tools that allow AI agents to interact with your codebase securely.
+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.
 
-## 🚀 Features
+> **Main Package:** [`atabey`](https://www.npmjs.com/package/atabey) (CLI + Framework)
 
-- **Strict Governance:** Enforces Zero Type Hole and Zero Console policies via AST parsing.
-- **Surgical Edits:** Uses `patch_file` and `replace_text` instead of full-file rewrites to save tokens and prevent context loss.
-- **Hermes Message Broker:** Facilitates asynchronous communication between specialized agents (`@manager`, `@architect`, `@security`, etc.).
-- **Memory Insights:** Provides agents with targeted, pruned context (last 5 actions, active trace) instead of dumping the entire project history.
-- **Risk Engine:** Automatically blocks or requires human approval for high-risk operations (e.g., deleting databases, touching `.env` files).
+---
+
+## 📋 Table of Contents
+
+- [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
+---
 
-Typically, you do not need to install this package manually. It is automatically installed and configured when you initialize an Atabey project:
+## Installation
 
 ```bash
-npx atabey init
+# Run with npx (no install needed)
+npx atabey-mcp
+
+# Global install
+npm install -g atabey-mcp
+
+# Add to project
+npm install atabey-mcp
+```
+
+---
+
+## 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)
 ```
 
-However, you can install it globally or locally if needed:
+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
-npm install atabey-mcp
+# 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 |
 
-## 🛠️ Provided Tools
+### Memory
 
-The `atabey-mcp` server exposes over 25 specialized tools grouped into the following domains:
+| 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 |
 
-- **File System:** `read_file`, `write_file`, `replace_text`, `patch_file`, `batch_surgical_edit`
-- **Control Plane:** `acquire_lock`, `release_lock`, `register_agent`
-- **Framework & Orchestration:** `submit_plan`, `orchestrate_loop`, `update_project_memory`, `audit_dependencies`
-- **Search & Map:** `grep_search`, `list_dir`, `get_architectural_map`, `get_knowledge_gaps`
-- **Quality & Observability:** `check_lint`, `run_tests`, `get_system_health`, `check_ports`
-- **Messaging:** `send_agent_message`, `log_agent_action`
+### Framework & Quality
 
-## 📖 Learn More
+| 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 |
 
-For full documentation, architecture details, and enterprise inquiries, please visit the main [Agent Atabey Repository](https://github.com/ysf-bkr/atabey).
+### 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 |
 
 ---
-*Developed by Yusuf BEKAR*
+
+## 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": "npx",
+      "args": ["atabey-mcp"],
+      "env": {
+        "ATABEY_PROJECT_ROOT": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+### 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/`
+
+---
+
+## More Information
+
+- **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
+
+---
+
+*Developer: **Yusuf BEKAR** — "Order from Chaos"*