atabey-mcp 0.0.4

package/src/tools/search/get_gaps.ts

@@ -0,0 +1,54 @@
+import fs from "fs";
+import path from "path";
+import { safePath } from "../../utils/security.js";
+import { GetProjectGapsArgs, ToolResult } from "../types.js";
+
+/**
+ * Scans the codebase for TODOs, FIXMEs, and empty function bodies.
+ * Helps identify what's left and where the agent might have skipped logic.
+ */
+export function handleGetProjectGaps(projectRoot: string, args: GetProjectGapsArgs): ToolResult {
+    const srcDir = safePath(projectRoot, args.path || "src");
+    const results: string[] = [];
+
+    const walk = (dir: string) => {
+        if (!fs.existsSync(dir)) return;
+        const files = fs.readdirSync(dir);
+        for (const file of files) {
+            const fullPath = path.join(dir, file);
+            const relativePath = path.relative(projectRoot, fullPath);
+
+            if (fs.statSync(fullPath).isDirectory()) {
+                if (file !== "node_modules" && file !== "dist" && !file.startsWith(".")) {
+                    walk(fullPath);
+                }
+            } else if (file.endsWith(".ts") || file.endsWith(".tsx")) {
+                const content = fs.readFileSync(fullPath, "utf8");
+                const lines = content.split("\n");
+
+                lines.forEach((line, index) => {
+                    // 1. Scan for markers
+                    if (line.includes("TODO") || line.includes("FIXME") || line.includes("!!!")) {
+                        results.push(`[${relativePath}:${index + 1}] Marker found: ${line.trim()}`);
+                    }
+                    
+                    // 2. Scan for empty function placeholders (heuristic)
+                    if (line.includes("throw new Error(\"Not implemented") || line.includes("// ... rest of code")) {
+                        results.push(`[${relativePath}:${index + 1}] Gap found: ${line.trim()}`);
+                    }
+                });
+            }
+        }
+    };
+
+    walk(srcDir);
+
+    return {
+        content: [{
+            type: "text",
+            text: results.length > 0 
+                ? `Found ${results.length} gaps/todos:\n\n${results.join("\n")}`
+                : "✅ No major gaps or TODOs found in the scanned directory."
+        }]
+    };
+}

package/src/tools/search/get_map.ts

@@ -0,0 +1,48 @@
+import fs from "fs";
+import path from "path";
+import { GetProjectMapArgs, ToolResult } from "../types.js";
+
+/**
+ * Generates a tree-view map of the project structure.
+ * Helps agents visualize the entire project layout quickly.
+ */
+export function handleGetProjectMap(projectRoot: string, args: GetProjectMapArgs): ToolResult {
+    const maxDepth = args.maxDepth || 3;
+    const includeFiles = args.includeFiles !== false;
+
+    const buildTree = (dir: string, depth: number): string[] => {
+        if (depth > maxDepth) return [];
+
+        const results: string[] = [];
+        const files = fs.readdirSync(dir);
+
+        files.forEach(file => {
+            if (file === "node_modules" || file === ".git" || file === "dist" || file.startsWith(".")) return;
+
+            const fullPath = path.join(dir, file);
+            const stat = fs.statSync(fullPath);
+            const indent = "  ".repeat(depth);
+
+            if (stat.isDirectory()) {
+                results.push(`${indent}📁 ${file}/`);
+                results.push(...buildTree(fullPath, depth + 1));
+            } else if (includeFiles) {
+                results.push(`${indent}📄 ${file}`);
+            }
+        });
+
+        return results;
+    };
+
+    try {
+        const tree = buildTree(projectRoot, 0);
+        return {
+            content: [{
+                type: "text",
+                text: `🗺️ **Project Map (Depth: ${maxDepth})**\n\n${tree.join("\n")}`
+            }]
+        };
+    } catch (e) {
+        return { isError: true, content: [{ type: "text", text: `Failed to map project: ${String(e)}` }] };
+    }
+}

package/src/tools/search/grep_search.ts

@@ -0,0 +1,75 @@
+import fs from "fs";
+import path from "path";
+import { GrepSearchArgs, ToolResult } from "../types.js";
+import { Metrics } from "../../utils/metrics.js";
+
+/**
+ * Searches for a regex pattern within files in the project.
+ */
+export function handleGrepSearch(projectRoot: string, args: GrepSearchArgs): ToolResult {
+    const pattern = args.pattern as string;
+    const includePattern = args.includePattern as string || ""; // e.g., ".ts"
+    const excludePattern = args.excludePattern as string || "node_modules";
+
+    if (!pattern) {
+        const err = "Search pattern is required.";
+        Metrics.logError(projectRoot, "@mcp", "grep_search", err);
+        return { isError: true, content: [{ type: "text", text: `❌ ${err}` }] };
+    }
+
+    const results: string[] = [];
+    try {
+        new RegExp(pattern);
+    } catch (e) {
+        const err = `Invalid regex pattern: ${String(e)}`;
+        Metrics.logError(projectRoot, "@mcp", "grep_search", err);
+        return { isError: true, content: [{ type: "text", text: `❌ ${err}` }] };
+    }
+
+    const walk = (dir: string) => {
+        if (results.length > 100) return;
+        try {
+            const files = fs.readdirSync(dir);
+            for (const file of files) {
+                if (results.length > 100) return;
+                const filePath = path.join(dir, file);
+                if (excludePattern && filePath.includes(excludePattern)) {
+                    continue;
+                }
+                const stat = fs.statSync(filePath);
+                if (stat.isDirectory()) {
+                    walk(filePath);
+                } else if (stat.isFile()) {
+                    if (includePattern && !filePath.endsWith(includePattern)) {
+                        continue;
+                    }
+                    const content = fs.readFileSync(filePath, "utf8");
+                    // Create a new regex object for each line to avoid state issues with /g
+                    if (new RegExp(pattern).test(content)) {
+                        if (results.length < 100) {
+                            results.push(filePath);
+                        }
+                    }
+                }
+            }
+        } catch {
+            // Ignore directories that cannot be read
+        }
+    };
+    try {
+        walk(projectRoot);
+    } catch (e) {
+        const err = `Search failed: ${String(e)}`;
+        Metrics.logError(projectRoot, "@mcp", "grep_search", err);
+        return { isError: true, content: [{ type: "text", text: `❌ ${err}` }] };
+    }
+
+    return {
+        content: [{
+            type: "text",
+            text: results.length > 0
+                ? `Found ${results.length} matches:\n\n${results.join("\n")}`
+                : "No matches found."
+        }]
+    };
+}

package/src/tools/search/list_dir.ts

@@ -0,0 +1,34 @@
+import fs from "fs";
+import path from "path";
+import { safePath } from "../../utils/security.js";
+import { ListDirArgs, ToolResult } from "../types.js";
+
+/**
+ * Lists the contents of a directory.
+ */
+export function handleListDir(projectRoot: string, args: ListDirArgs): ToolResult {
+    const dirPath = safePath(projectRoot, args.path || ".");
+    
+    if (!fs.existsSync(dirPath)) {
+        throw new Error(`Directory not found: ${args.path}`);
+    }
+
+    const stats = fs.statSync(dirPath);
+    if (!stats.isDirectory()) {
+        throw new Error(`Path is not a directory: ${args.path}`);
+    }
+
+    const files = fs.readdirSync(dirPath);
+    const results = files.map(file => {
+        const fullPath = path.join(dirPath, file);
+        const isDir = fs.statSync(fullPath).isDirectory();
+        return `${isDir ? "[DIR] " : "      "}${file}`;
+    });
+
+    return {
+        content: [{
+            type: "text",
+            text: `Directory listing for ${args.path || "."}:\n\n${results.join("\n")}`
+        }]
+    };
+}

package/src/tools/shell/run_command.ts

@@ -0,0 +1,66 @@
+import { exec } from "child_process";
+import { RunCommandArgs, ToolResult } from "../types.js";
+import { Metrics } from "../../utils/metrics.js";
+
+const COMMAND_ALLOW_LIST = [
+    "npm test",
+    "npm run lint",
+    "npm run build",
+    "git status",
+    "git diff",
+    "npx vitest run",
+    "go test",
+    "go fmt",
+    "go build",
+    "pytest",
+    "ruff check",
+    "dotnet test",
+    "dotnet format",
+    "dotnet build",
+    "./gradlew",
+    "mvn",
+];
+
+const TIMEOUT = 30000; // 30 seconds
+
+export function handleRunCommand(projectRoot: string, args: RunCommandArgs): Promise<ToolResult> {
+    const command = args.command;
+
+    const isAllowed = COMMAND_ALLOW_LIST.some(allowedCmd => command.startsWith(allowedCmd));
+
+    if (!isAllowed) {
+        const errorMsg = `Command not allowed: "${command}". Only commands starting with the following are allowed: ${COMMAND_ALLOW_LIST.join(", ")}`;
+        Metrics.logError(projectRoot, "@mcp", `run_shell_command: ${command} (denied)`, errorMsg);
+        return Promise.resolve({
+            content: [{ type: "text", text: `ERROR: ${errorMsg}` }],
+            isError: true,
+        });
+    }
+
+    return new Promise((resolve) => {
+        exec(command, { cwd: projectRoot, timeout: TIMEOUT }, (error, stdout, stderr) => {
+            const output = stdout + stderr;
+            const tokens = Metrics.estimateTokens(output);
+            Metrics.logUsage(projectRoot, "@mcp", `run_shell_command: ${command}`, tokens);
+            
+            if (error) {
+                const errorMsg = `Command failed with exit code ${error.code}: ${error.message}.`;
+                Metrics.logError(projectRoot, "@mcp", `run_shell_command: ${command}`, errorMsg);
+                resolve({
+                    content: [{ type: "text", text: `ERROR: ${errorMsg}. Output: ${output}` }],
+                    isError: true,
+                });
+                return;
+            }
+
+            // Truncate long outputs
+            const MAX_OUTPUT_LENGTH = 5000;
+            let truncatedOutput = output;
+            if (output.length > MAX_OUTPUT_LENGTH) {
+                truncatedOutput = output.substring(0, MAX_OUTPUT_LENGTH) + "... [TRUNCATED] ..."; // Simplified
+            }
+            
+            resolve({ content: [{ type: "text", text: truncatedOutput }] });
+        });
+    });
+}

package/src/tools/types.ts

@@ -0,0 +1,89 @@
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+
+// ─── File System ────────────────────────────────────────────────
+export interface ReadFileArgs { path: string; startLine?: number; endLine?: number; }
+export interface WriteFileArgs { path: string; content: string; }
+export interface ReplaceTextArgs { path: string; oldText: string; newText: string; allowMultiple?: boolean; }
+export interface PatchFileArgs { path: string; startLine: number; endLine: number; newContent: string; }
+export interface BatchSurgicalEditArgs {
+    edits: Array<{ path: string; oldText: string; newText: string; allowMultiple?: boolean; }>;
+}
+
+// ─── Search & Discovery ──────────────────────────────────────────
+export interface ListDirArgs { path?: string; }
+export interface GrepSearchArgs { pattern: string; includePattern?: string; excludePattern?: string; }
+export interface GetProjectMapArgs { maxDepth?: number; includeFiles?: boolean; }
+export interface GetProjectGapsArgs { path?: string; }
+
+// ─── Messaging (Hermes) ─────────────────────────────────────────
+export interface SendAgentMessageArgs {
+    from: string;
+    to: string;
+    category: "ACTION" | "DELEGATION" | "SUBTASK" | "REPLY" | "ALERT";
+    content: string;
+    traceId: string;
+    parentId?: string;
+    priority?: "HIGH" | "NORMAL" | "LOW";
+    requiresApproval?: boolean;
+}
+export interface LogAgentActionArgs {
+    agent: string;
+    action: string;
+    traceId: string;
+    status: "SUCCESS" | "FAILURE";
+    summary: string;
+    findings?: string;
+}
+
+// ─── Control Plane ──────────────────────────────────────────────
+export interface AcquireLockArgs { resource: string; agent: string; ttl?: number; }
+export interface ReleaseLockArgs { resource: string; agent: string; }
+export interface RegisterAgentArgs { agent: string; role: string; capability?: number; }
+
+// ─── Observability & Utils ──────────────────────────────────────
+export interface StartDashboardArgs { port?: number; }
+export interface CheckActivePortsArgs { filter?: string; }
+export interface RunTestsArgs { command?: string; timeout?: number; }
+export interface UpdateProjectMemoryArgs { section: string; content: string; }
+export interface GetStatusArgs { timeout?: number; }
+export interface OrchestrateArgs { timeout?: number; }
+export interface UpdateContractHashArgs { timeout?: number; }
+export interface RunCommandArgs { command: string; }
+
+export type ToolArgs =
+    | ReadFileArgs
+    | WriteFileArgs
+    | ReplaceTextArgs
+    | PatchFileArgs
+    | BatchSurgicalEditArgs
+    | ListDirArgs
+    | GrepSearchArgs
+    | GetProjectMapArgs
+    | GetProjectGapsArgs
+    | SendAgentMessageArgs
+    | LogAgentActionArgs
+    | AcquireLockArgs
+    | ReleaseLockArgs
+    | RegisterAgentArgs
+    | StartDashboardArgs
+    | CheckActivePortsArgs
+    | RunTestsArgs
+    | UpdateProjectMemoryArgs
+    | GetStatusArgs
+    | OrchestrateArgs
+    | UpdateContractHashArgs;
+
+export interface ToolResult {
+    isError?: boolean;
+    content: Array<{ type: "text"; text: string }>;
+}
+
+export type ToolHandler = (projectRoot: string, args: unknown) => ToolResult | Promise<ToolResult>;

package/src/utils/cli.ts

@@ -0,0 +1,53 @@
+import fs from "fs";
+import path from "path";
+import { execFileSync } from "child_process";
+
+/**
+ * Executes a command safely and returns the output.
+ */
+export function safeExec(cmd: string, args: string[], cwd: string, timeout = 30000): string {
+    try {
+        return execFileSync(cmd, args, { cwd, timeout, encoding: "utf8", stdio: "pipe" });
+    } catch (err: unknown) {
+        const error = err as { stdout?: Buffer | string; stderr?: Buffer | string; message?: string };
+        return error.stdout?.toString() || error.stderr?.toString() || error.message || String(err);
+    }
+}
+
+/**
+ * Detects the backend language from the framework configuration.
+ */
+export function getBackendLanguage(projectRoot: string): string {
+    try {
+        const configPath = path.join(projectRoot, ".atabey", "config.json");
+        if (fs.existsSync(configPath)) {
+            const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+            return config.backendLanguage || "Node.js (TypeScript)";
+        }
+    } catch {
+        // Fallback to default
+    }
+    return "Node.js (TypeScript)";
+}
+
+/**
+ * Returns the default lint command for the given language.
+ */
+export function getDefaultLintCommand(language: string): string {
+    if (language.includes("Go")) return "go fmt ./...";
+    if (language.includes("Java")) return "./gradlew check"; // or mvn check
+    if (language.includes("Python")) return "ruff check .";
+    if (language.includes(".NET")) return "dotnet format";
+    return "npm run lint";
+}
+
+/**
+ * Returns the default test command for the given language.
+ */
+export function getDefaultTestCommand(language: string): string {
+    if (language.includes("Go")) return "go test ./...";
+    if (language.includes("Java")) return "./gradlew test"; // or mvn test
+    if (language.includes("Python")) return "pytest";
+    if (language.includes(".NET")) return "dotnet test";
+    return "npm test";
+}

package/src/utils/compliance.ts

@@ -0,0 +1,95 @@
+import ts from "typescript";
+
+/**
+ * Enterprise Compliance Guardrail
+ * Checks content against corporate standards using AST analysis before allowing file mutations.
+ */
+export function verifyCorporateCompliance(content: string, filePath: string): void {
+    // Skip compliance checks for non-source files or specific ignored files
+    if (filePath.endsWith(".json") || filePath.endsWith(".md") || filePath.endsWith(".env.example")) {
+        return;
+    }
+
+    const sourceFile = ts.createSourceFile(
+        filePath,
+        content,
+        ts.ScriptTarget.Latest,
+        true
+    );
+
+    const errors: string[] = [];
+
+    /**
+     * Recursive AST Visitor
+     */
+    function visit(node: ts.Node) {
+        // 1. Zero Console Policy
+        if (ts.isPropertyAccessExpression(node)) {
+            const expression = node.expression;
+            const name = node.name.text;
+            if (ts.isIdentifier(expression) && expression.text === "console") {
+                if (["log", "warn", "error"].includes(name)) {
+                    // Check if file is exempt
+                    if (!filePath.includes("logger.ts") && !filePath.includes("check.ts") && !filePath.includes("cli.ts")) {
+                        errors.push(`❌ Corporate Compliance Breach: 'console.${name}' usage is forbidden at line ${sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1}.`);
+                    }
+                }
+            }
+        }
+
+        // 2. No Explicit Any Policy
+        if (ts.isTypeReferenceNode(node)) {
+            if (ts.isIdentifier(node.typeName) && node.typeName.text === "any") {
+                if (!filePath.includes("definitions.ts") && !filePath.includes("types.ts")) {
+                    errors.push(`❌ Corporate Compliance Breach: 'any' type is forbidden at line ${sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1}.`);
+                }
+            }
+        }
+        
+        // 3. Zero UI Library Policy (No @chakra-ui, mui, @shadcn)
+        if (ts.isImportDeclaration(node)) {
+            const moduleSpecifier = node.moduleSpecifier;
+            if (ts.isStringLiteral(moduleSpecifier)) {
+                const forbiddenLibs = ["@chakra-ui", "mui", "@shadcn", "antd", "bootstrap"];
+                const lib = forbiddenLibs.find(l => moduleSpecifier.text.includes(l));
+                if (lib) {
+                    errors.push(`❌ Corporate Compliance Breach: External UI library '${lib}' usage is FORBIDDEN at line ${sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1}. Build atomic components manually instead.`);
+                }
+            }
+        }
+        
+        // Handle 'any' as a keyword type (e.g., parameter: any)
+        if (node.kind === ts.SyntaxKind.AnyKeyword) {
+            if (!filePath.includes("definitions.ts") && !filePath.includes("types.ts")) {
+                errors.push(`❌ Corporate Compliance Breach: 'any' keyword is forbidden at line ${sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1}.`);
+            }
+        }
+
+        ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+
+    // 3. Hardcoded Secrets & PII Guard
+    const piiKeywords = [
+        { regex: /API_KEY\s*=\s*['"][^'"]+['"]/i, msg: "Hardcoded API Key" },
+        { regex: /SECRET\s*=\s*['"][^'"]+['"]/i, msg: "Hardcoded Secret" },
+        { regex: /PASSWORD\s*=\s*['"][^'"]+['"]/i, msg: "Hardcoded Password" },
+        { regex: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/, msg: "PII Detected: Email Address" },
+        { regex: /\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/, msg: "PII Detected: Credit Card Pattern" }
+    ];
+    
+    for (const { regex, msg } of piiKeywords) {
+        if (regex.test(content)) {
+            // Allow emails in specific files like README or package.json
+            if (msg.includes("Email") && (filePath.endsWith("README.md") || filePath.endsWith("package.json") || filePath.includes("CONTRIBUTING"))) {
+                continue;
+            }
+            errors.push(`❌ Corporate Compliance Breach: ${msg} detected.`);
+        }
+    }
+
+    if (errors.length > 0) {
+        throw new Error(errors.join("\n"));
+    }
+}

package/src/utils/fs.ts

@@ -0,0 +1,45 @@
+import fs from "fs";
+import path from "path";
+
+/**
+ * Ensures directory existence.
+ */
+export function ensureDir(dirPath: string): void {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+
+/**
+ * Atomically writes a text file.
+ */
+export function writeTextFileAtomic(filePath: string, content: string): void {
+    const dir = path.dirname(filePath);
+    ensureDir(dir);
+
+    const tempPath = `${filePath}.${Math.random().toString(36).slice(2, 9)}.tmp`;
+    const finalContent = content.endsWith("\n") ? content : `${content}\n`;
+
+    try {
+        fs.writeFileSync(tempPath, finalContent, "utf8");
+        fs.renameSync(tempPath, filePath);
+    } catch (err) {
+        if (fs.existsSync(tempPath)) {
+            try { fs.unlinkSync(tempPath); } catch { /* ignore */ }
+        }
+        throw err;
+    }
+}
+
+/**
+ * Atomically appends to a file (if supported by OS) or simulates it.
+ * Note: Real atomic append on POSIX is a single write() call with O_APPEND.
+ * For simplicity and robustness across platforms, we use a simple append here
+ * as the risk of corruption is lower than a full rewrite, but for logs
+ * it's acceptable.
+ */
+export function appendFileSafe(filePath: string, content: string): void {
+    const dir = path.dirname(filePath);
+    ensureDir(dir);
+    fs.appendFileSync(filePath, content, "utf8");
+}

package/src/utils/metrics.ts

@@ -0,0 +1,73 @@
+import fs from "fs";
+import path from "path";
+import { resolveFrameworkDir } from "./security.js";
+/**
+ * Token and Metric Tracker for Agent Atabey.
+ * Estimates token usage and logs operational costs.
+ */
+
+interface MetricEntry {
+    timestamp: string;
+    agent: string;
+    action: string;
+    estimatedTokens: number;
+    error?: string;
+}
+
+export const Metrics = {
+    /**
+     * Estimates tokens based on character count (rough heuristic: 1 token ~= 4 chars).
+     */
+    estimateTokens: (text: string): number => {
+        return Math.ceil(text.length / 4);
+    },
+
+    /**
+     * Logs the token usage and action to the observability metrics file.
+     */
+    logUsage: (projectRoot: string, agent: string, action: string, tokens: number) => {
+        Metrics.saveMetric(projectRoot, {
+            timestamp: new Date().toISOString(),
+            agent,
+            action,
+            estimatedTokens: tokens
+        });
+    },
+
+    /**
+     * Logs an error occurrence to the observability metrics file.
+     */
+    logError: (projectRoot: string, agent: string, action: string, error: string) => {
+        Metrics.saveMetric(projectRoot, {
+            timestamp: new Date().toISOString(),
+            agent,
+            action: `ERROR: ${action}`,
+            estimatedTokens: 0,
+            error
+        });
+    },
+
+    /**
+     * Internal helper to save metric entries.
+     */
+    saveMetric: (projectRoot: string, entry: MetricEntry) => {
+        const frameworkDir = resolveFrameworkDir(projectRoot);
+        const metricsPath = path.join(projectRoot, frameworkDir, "observability/metrics.json");
+        try {
+            const metricsDir = path.dirname(metricsPath);
+            if (!fs.existsSync(metricsDir)) fs.mkdirSync(metricsDir, { recursive: true });
+
+            let currentMetrics: MetricEntry[] = [];
+            if (fs.existsSync(metricsPath)) {
+                currentMetrics = JSON.parse(fs.readFileSync(metricsPath, "utf8"));
+            }
+
+            currentMetrics.push(entry);
+
+            // Keep only last 100 entries to save space
+            if (currentMetrics.length > 100) currentMetrics.shift();
+
+            fs.writeFileSync(metricsPath, JSON.stringify(currentMetrics, null, 2));
+        } catch { /* ignore: metrics should not block the main process */ }
+    }
+};