atabey-mcp 0.0.10 → 0.0.12

package/README.md

@@ -1,48 +1,115 @@
 # 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.
+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.
 
-## 🚀 Features
+## 🚀 Özellikler / Features
 
-- **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).
+| Ö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ı |
 
-## 📦 Installation
-
-Typically, you do not need to install this package manually. It is automatically installed and configured when you initialize an Atabey project:
+## 📦 Kurulum / Installation
 
 ```bash
-npx atabey init
-```
+# Global kurulum (genelde init ile otomatik gelir)
+npm install -g atabey-mcp
 
-However, you can install it globally or locally if needed:
-
-```bash
+# Projeye ekleme
 npm install atabey-mcp
 ```
 
-## 🛠️ Provided Tools
-
-The `atabey-mcp` server exposes over 25 specialized tools grouped into the following domains:
+## 🛠️ 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
+
+```json
+{
+  "mcpServers": {
+    "atabey": {
+      "command": "node",
+      "args": ["/path/to/atabey-mcp/dist/index.js"],
+      "env": {
+        "ATABEY_PROJECT_ROOT": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
 
-- **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`
+## 📖 Daha Fazla Bilgi
 
-## 📖 Learn More
+Tüm dokümantasyon, mimari detaylar ve kurumsal iletişim için ana depoyu ziyaret edin:
 
-For full documentation, architecture details, and enterprise inquiries, please visit the main [Agent Atabey Repository](https://github.com/ysf-bkr/atabey).
+- **Ana Paket:** [atabey](https://www.npmjs.com/package/atabey)
+- **GitHub:** [github.com/ysf-bkr/atabey](https://github.com/ysf-bkr/atabey)
+- **Enterprise:** ybekar@msn.com
 
 ---
-*Developed by Yusuf BEKAR*
+
+*Developed by **Yusuf BEKAR** — "Order from Chaos"*

package/dist/framework-mcp/src/constants.js

@@ -0,0 +1,64 @@
+import path from "path";
+/**
+ * Agent Atabey — Single Source of Truth for framework constants.
+ * Import from here instead of hardcoding paths, phases, or directory names.
+ */
+// ─── Framework identity ───────────────────────────────────────────────────
+export const FRAMEWORK = {
+    NAME: "Agent Atabey",
+    CORE_DIR: ".atabey",
+    // This is the hub for unified adapter layouts (e.g. .agents/gemini, .agents/claude)
+    UNIFIED_HUB_DIR: ".agents",
+    // This is the default directory to scaffold new apps into
+    APPS_DIR: "apps",
+    // This is where all skills are stored
+    SKILLS_DIR: "skills",
+};
+export const FRAMEWORK_SUBDIRS = {
+    AGENTS: "agents",
+    SKILLS: "skills",
+    KNOWLEDGE: "knowledge",
+    MESSAGES: "messages",
+    MEMORY: "memory",
+    MEMORY_GRAPH: "memory-graph",
+    LOGS: "logs",
+    CONFIG: "config",
+};
+export const ROOT_CONFIG_FILES = {
+    MCP: "mcp.json",
+    NATIVE_MODULES: "native-modules.json",
+    TSCONFIG: "tsconfig.json",
+    ESLINT: "eslint.config.js",
+};
+export const MCP = {
+    // Environment variable used by MCP to identify project root
+    PROJECT_ROOT_ENV: "ATABEY_PROJECT_ROOT",
+    // Environment variable for test mode
+    TEST_DIR_ENV: "ATABEY_TEST_DIR",
+};
+export const MEMORY_FILES = {
+    STATE: "state.json",
+    SHARED_FACTS: "shared_facts.json",
+};
+export const NATIVE_AGENT_PATHS = {
+    gemini: ".gemini/agents",
+    claude: ".claude/agents",
+    cursor: ".cursor/rules",
+    codex: ".agents/instructions",
+    grok: ".grok",
+    "antigravity-cli": ".agents/agents",
+};
+// ─── Backward-compatible aliases ──────────────────────────────────────────
+export const CORE_FRAMEWORK_DIR = FRAMEWORK.CORE_DIR;
+export const UNIFIED_HUB_DIR = FRAMEWORK.UNIFIED_HUB_DIR;
+export const SKILLS_HUB_PATH = pathJoin(UNIFIED_HUB_DIR, FRAMEWORK_SUBDIRS.SKILLS);
+// ─── Path Helpers ─────────────────────────────────────────────────────────
+function pathJoin(...args) {
+    return path.join(...args);
+}
+function corePath(subdir, filename) {
+    return pathJoin(FRAMEWORK.CORE_DIR, subdir, filename);
+}
+export function knowledgePath(filename) {
+    return corePath(FRAMEWORK_SUBDIRS.KNOWLEDGE, filename);
+}

package/dist/framework-mcp/src/index.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { TOOLS, toolHandlers, toolSchemas } from "./tools/index.js";
+import { RESOURCES, handleReadResource } from "./resources/index.js";
+// ─── Server Setup ─────────────────────────────────────────────────
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Robustly find package.json by walking up from __dirname
+function findPackageJson(startDir) {
+    let currentDir = startDir;
+    while (currentDir !== path.parse(currentDir).root) {
+        const pkgPath = path.join(currentDir, "package.json");
+        if (fs.existsSync(pkgPath))
+            return pkgPath;
+        currentDir = path.dirname(currentDir);
+    }
+    throw new Error("Could not find package.json for atabey-mcp");
+}
+const pkgPath = findPackageJson(__dirname);
+const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+const serverVersion = pkg.version;
+const server = new Server({
+    name: "atabey-mcp",
+    version: serverVersion,
+}, {
+    capabilities: {
+        tools: {},
+        resources: {},
+    },
+});
+/**
+ * Validates tool arguments using Zod schemas for "Zero Type Hole" compliance.
+ * Falls back to basic presence check if no Zod schema is defined for the tool.
+ */
+function validateArgs(toolName, args) {
+    const schema = toolSchemas[toolName];
+    if (schema) {
+        const result = schema.safeParse(args);
+        if (!result.success) {
+            return result.error.errors.map(e => `${e.path.join(".")}: ${e.message}`).join(", ");
+        }
+        return null;
+    }
+    // Fallback for tools without Zod schemas yet
+    const definition = TOOLS.find(t => t.name === toolName);
+    if (!definition)
+        return `Unknown tool: ${toolName}`;
+    const required = definition.inputSchema.required || [];
+    for (const field of required) {
+        if (args[field] === undefined || args[field] === null || args[field] === "") {
+            return `Missing required argument: '${field}' for tool '${toolName}'`;
+        }
+    }
+    return null;
+}
+server.setRequestHandler(ListToolsRequestSchema, async (request) => {
+    // 2026 Stateless Spec: Log client info from metadata if available
+    const meta = request._meta;
+    if (meta) {
+        process.stderr.write(`[MCP] Stateless ListTools from ${meta.client?.name || "unknown"} v${meta.client?.version || "?.?"}\n`);
+    }
+    return { tools: TOOLS };
+});
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return { resources: RESOURCES };
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    try {
+        const content = await handleReadResource(uri);
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: "text/markdown",
+                    text: content,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to read resource: ${message}`, { cause: error });
+    }
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const req = request;
+    const { name, arguments: args } = req.params;
+    const meta = request._meta;
+    // 2026 Stateless Spec: Prioritize metadata-driven context
+    if (meta) {
+        process.stderr.write(`[MCP] Stateless CallTool: ${name} (Client: ${meta.client?.name || "unknown"})\n`);
+    }
+    const projectRoot = process.env.ATABEY_PROJECT_ROOT || process.cwd();
+    try {
+        const handler = toolHandlers[name];
+        if (!handler) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `[ERROR] Unknown tool: ${name}` }],
+            };
+        }
+        // [SECURITY] Runtime Validation
+        const validationError = validateArgs(name, args || {});
+        if (validationError) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `[ERROR] Validation Error: ${validationError}` }],
+            };
+        }
+        return await handler(projectRoot, args || {});
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error occurred";
+        return {
+            isError: true,
+            content: [{ type: "text", text: `[ERROR] Execution failed: ${message}` }],
+        };
+    }
+});
+// ─── Graceful Startup & Shutdown ──────────────────────────────────
+async function run() {
+    const transport = new StdioServerTransport();
+    // Prevent unhandled errors from crashing the MCP stream
+    process.on("uncaughtException", (error) => {
+        process.stderr.write(`[atabey-mcp] Uncaught exception: ${error.message}
+`);
+    });
+    process.on("unhandledRejection", (reason) => {
+        const message = reason instanceof Error ? reason.message : String(reason);
+        process.stderr.write(`[atabey-mcp] Unhandled rejection: ${message}
+`);
+    });
+    // Graceful shutdown on SIGINT/SIGTERM
+    const shutdown = async () => {
+        try {
+            await server.close();
+        }
+        catch {
+            // Already closed or failed — safe to ignore
+        }
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await server.connect(transport);
+}
+run().catch((error) => {
+    process.stderr.write(`[atabey-mcp] Fatal startup error: ${error.message}
+`);
+    process.exit(1);
+});

package/dist/framework-mcp/src/resources/index.js

@@ -0,0 +1,58 @@
+import { Storage } from "../utils/storage.js";
+/**
+ * [DATA] MCP Resource Definitions
+ */
+export const RESOURCES = [
+    {
+        uri: "atabey://AL/status",
+        name: "AL Registry Status",
+        description: "Real-time state and active tasks of all specialized agents.",
+        mimeType: "text/markdown"
+    },
+    {
+        uri: "atabey://plan/active",
+        name: "Active Execution Plan",
+        description: "The current DAG of tasks and their completion status.",
+        mimeType: "text/markdown"
+    },
+    {
+        uri: "atabey://memory/project",
+        name: "Project Memory",
+        description: "The central source of truth for project context (PROJECT_MEMORY.md).",
+        mimeType: "text/markdown"
+    }
+];
+export async function handleReadResource(uri) {
+    if (uri === "atabey://AL/status") {
+        const agents = Storage.getAllAgents();
+        let md = "# [AI] AL Registry Status\n\n| Agent | State | Active Task | Last Updated |\n| :--- | :--- | :--- | :--- |\n";
+        agents.forEach((a) => {
+            md += `| @${a.name} | ${a.state} | ${a.task} | ${a.last_updated} |\n`;
+        });
+        return md;
+    }
+    if (uri === "atabey://plan/active") {
+        const tasks = Storage.getTasks();
+        let md = "# [LIST] Active Execution Plan\n\n| ID | Task | Agent | Status | Dependencies |\n| :--- | :--- | :--- | :--- | :--- |\n";
+        tasks.forEach((t) => {
+            const deps = t.dependencies.join(", ") || "-";
+            md += `| ${t.id} | ${t.description} | ${t.agent} | ${t.status} | ${deps} |\n`;
+        });
+        return md;
+    }
+    if (uri === "atabey://memory/project") {
+        const fs = await import("fs");
+        const path = await import("path");
+        const { getFrameworkDir } = await import("../utils/memory.js");
+        const projectRoot = process.env.ATABEY_PROJECT_ROOT || process.cwd();
+        const fwDir = getFrameworkDir();
+        const p = path.isAbsolute(fwDir)
+            ? path.join(fwDir, "memory", "PROJECT_MEMORY.md")
+            : path.join(projectRoot, fwDir, "memory", "PROJECT_MEMORY.md");
+        if (fs.existsSync(p)) {
+            return fs.readFileSync(p, "utf8");
+        }
+        return "Project memory not found. Run 'atabey init' first.";
+    }
+    throw new Error(`Unknown resource URI: ${uri}`);
+}

package/dist/framework-mcp/src/tools/control_plane/locking.js

@@ -0,0 +1,84 @@
+import fs from "fs";
+import path from "path";
+import { resolveFrameworkDir } from "../../utils/security.js";
+import { Metrics } from "../../utils/metrics.js";
+/**
+ * Handles acquiring a stateful lock on a resource with Deadlock Resolution.
+ */
+export async function handleAcquireLock(projectRoot, args) {
+    const { resource, agent, ttl = 300 } = args; // Default TTL 5 minutes to prevent deadlocks
+    const frameworkDir = resolveFrameworkDir(projectRoot);
+    const lockDir = path.join(projectRoot, frameworkDir, "locks");
+    const lockPath = path.join(lockDir, `${resource}.lock`);
+    try {
+        if (!fs.existsSync(lockDir))
+            fs.mkdirSync(lockDir, { recursive: true });
+        // Check for stale lock first (DEADLOCK RESOLUTION)
+        if (fs.existsSync(lockPath)) {
+            const stat = fs.statSync(lockPath);
+            const now = new Date().getTime();
+            const age = (now - stat.mtimeMs) / 1000;
+            if (age < ttl) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `[LOCKED] Resource '${resource}' is currently locked by another agent. Try again later.` }]
+                };
+            }
+            // Lock expired: Force Eviction
+            const oldLockData = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+            Metrics.logError(projectRoot, "@mcp", "lock_eviction", `Forcefully evicted stale lock on '${resource}' held by ${oldLockData.agent} for ${Math.round(age)}s.`);
+            const tempLockPath = `${lockPath}.${Math.random().toString(36).substring(2)}.old`;
+            try {
+                fs.renameSync(lockPath, tempLockPath);
+                fs.unlinkSync(tempLockPath);
+            }
+            catch {
+                // Ignore if already evicted by race condition
+            }
+        }
+        // Use 'wx' flag for atomic file creation
+        const lockData = JSON.stringify({ agent, timestamp: new Date().toISOString() });
+        fs.writeFileSync(lockPath, lockData, { flag: "wx" });
+        return {
+            content: [{ type: "text", text: `[OK] Lock acquired for resource '${resource}' by ${agent}.` }]
+        };
+    }
+    catch (e) {
+        const error = e;
+        if (error.code === "EEXIST") {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `[LOCKED] Resource '${resource}' was just acquired by another agent.` }]
+            };
+        }
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Failed to acquire lock: ${String(e)}` }]
+        };
+    }
+}
+/**
+ * Handles releasing a lock.
+ */
+export async function handleReleaseLock(projectRoot, args) {
+    const { resource, agent } = args;
+    const frameworkDir = resolveFrameworkDir(projectRoot);
+    const lockPath = path.join(projectRoot, frameworkDir, "locks", `${resource}.lock`);
+    try {
+        if (!fs.existsSync(lockPath)) {
+            return { content: [{ type: "text", text: `[INFO] No lock found for resource '${resource}'.` }] };
+        }
+        const lockData = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+        if (lockData.agent !== agent) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `[ERROR] Denied: You do not own the lock for '${resource}'. Owned by ${lockData.agent}.` }]
+            };
+        }
+        fs.unlinkSync(lockPath);
+        return { content: [{ type: "text", text: `[OK] Lock released for resource '${resource}' by ${agent}.` }] };
+    }
+    catch (e) {
+        return { isError: true, content: [{ type: "text", text: `Failed to release lock: ${String(e)}` }] };
+    }
+}

package/dist/framework-mcp/src/tools/control_plane/registry.js

@@ -0,0 +1,35 @@
+import fs from "fs";
+import path from "path";
+import { resolveFrameworkDir } from "../../utils/security.js";
+/**
+ * Handles agent registration with the Control Plane.
+ * This can be used to validate permissions and active status.
+ */
+export async function handleRegisterAgent(projectRoot, args) {
+    const { agent, role, capability = 5, specialties } = args;
+    const frameworkDir = resolveFrameworkDir(projectRoot);
+    const registryDir = path.join(projectRoot, frameworkDir, "registry");
+    const agentFile = path.join(registryDir, `${agent.replace("@", "")}_active.json`);
+    try {
+        if (!fs.existsSync(registryDir))
+            fs.mkdirSync(registryDir, { recursive: true });
+        const agentData = {
+            agent,
+            role,
+            capability,
+            specialties,
+            last_seen: new Date().toISOString(),
+            status: "ACTIVE"
+        };
+        fs.writeFileSync(agentFile, JSON.stringify(agentData, null, 2));
+        return {
+            content: [{ type: "text", text: `[ATABEY] Agent ${agent} (${role}) registered successfully in the Atabey Control Plane.` }]
+        };
+    }
+    catch (e) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Failed to register agent: ${String(e)}` }]
+        };
+    }
+}