athar-mcp 0.1.0

package/dist/tools/validators.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+/**
+ * Zod schema for the save_lesson tool input.
+ * Enforces structured, high-quality lesson data from the AI assistant.
+ */
+export const SaveLessonSchema = z.object({
+    title: z
+        .string()
+        .min(10, 'Title must be at least 10 characters — be specific about the mistake pattern')
+        .max(200)
+        .describe('Concise title describing the mistake pattern (e.g., "React useEffect cleanup race condition")'),
+    problem: z
+        .string()
+        .min(20, 'Problem description must be detailed enough to be useful')
+        .describe('What went wrong — the symptom observed by the developer'),
+    error_message: z
+        .string()
+        .optional()
+        .describe('Exact error message, stack trace snippet, or compiler error if applicable'),
+    root_cause: z
+        .string()
+        .min(20, 'Root cause must explain WHY, not just WHAT')
+        .describe('The actual root cause — WHY this happened, not just what happened'),
+    bad_code: z
+        .string()
+        .optional()
+        .describe('The incorrect code snippet that caused the problem'),
+    good_code: z
+        .string()
+        .optional()
+        .describe('The corrected code snippet showing the fix'),
+    lesson: z
+        .string()
+        .min(20, 'Lesson must be a meaningful takeaway')
+        .describe('The key takeaway — what to always remember to avoid this mistake'),
+    tags: z
+        .array(z.string().min(1).max(30))
+        .min(1, 'At least one tag is required for categorization')
+        .max(10)
+        .describe('Categorization tags (e.g., ["async", "react", "typescript", "race-condition"])'),
+    language: z
+        .string()
+        .optional()
+        .describe('Programming language (e.g., "typescript", "python", "rust")'),
+    file_path: z
+        .string()
+        .optional()
+        .describe('File path where the error occurred'),
+    git_diff: z
+        .string()
+        .optional()
+        .describe('Git diff context showing the change that fixed the issue'),
+    review_questions: z
+        .array(z.object({
+        q: z.string().min(10).describe('A review question testing understanding of this lesson'),
+        a: z.string().min(10).describe('The expected answer'),
+    }))
+        .min(1, 'At least one review question is required')
+        .max(3, 'Maximum 3 review questions per lesson')
+        .describe('1-3 review questions to test understanding during spaced repetition reviews'),
+});
+/**
+ * Zod schema for the memory (search) tool input.
+ */
+export const MemorySchema = z.object({
+    query: z
+        .string()
+        .min(2)
+        .describe('Search query — error pattern, keyword, tag name, or natural language description'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(10)
+        .default(3)
+        .describe('Maximum number of results to return (default: 3)'),
+    language: z
+        .string()
+        .optional()
+        .describe('Filter results by programming language'),
+    tags: z
+        .array(z.string())
+        .optional()
+        .describe('Filter results by tags (matches any)'),
+});
+//# sourceMappingURL=validators.js.map

package/dist/tools/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/tools/validators.ts"],"names":[],"mappings":"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"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Logger utility for Athar.
+ *
+ * CRITICAL: In MCP servers using stdio transport, stdout is the JSON-RPC channel.
+ * ALL logging MUST go to stderr. Using console.log() would corrupt the protocol.
+ */
+declare class Logger {
+    private context;
+    private isVerbose;
+    constructor(context: string);
+    private write;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Create a namespaced logger instance.
+ * @param context - Module name (e.g., 'server', 'db', 'save-lesson')
+ */
+export declare function createLogger(context: string): Logger;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH,cAAM,MAAM;IACV,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAU;gBAEf,OAAO,EAAE,MAAM;IAK3B,OAAO,CAAC,KAAK;IAgBb,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAIhD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAI/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAI/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;CAGjD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/utils/logger.js

@@ -0,0 +1,55 @@
+/**
+ * Logger utility for Athar.
+ *
+ * CRITICAL: In MCP servers using stdio transport, stdout is the JSON-RPC channel.
+ * ALL logging MUST go to stderr. Using console.log() would corrupt the protocol.
+ */
+const LOG_COLORS = {
+    debug: '\x1b[90m', // gray
+    info: '\x1b[36m', // cyan
+    warn: '\x1b[33m', // yellow
+    error: '\x1b[31m', // red
+};
+const RESET = '\x1b[0m';
+class Logger {
+    context;
+    isVerbose;
+    constructor(context) {
+        this.context = context;
+        this.isVerbose = process.env.ATHAR_DEBUG === '1' || process.env.ATHAR_DEBUG === 'true';
+    }
+    write(level, message, ...args) {
+        if (level === 'debug' && !this.isVerbose)
+            return;
+        const timestamp = new Date().toISOString().slice(11, 23); // HH:mm:ss.SSS
+        const color = LOG_COLORS[level];
+        const prefix = `${color}[${timestamp}] [${level.toUpperCase()}] [${this.context}]${RESET}`;
+        // Always write to stderr — never stdout
+        process.stderr.write(`${prefix} ${message}\n`);
+        if (args.length > 0) {
+            for (const arg of args) {
+                process.stderr.write(`  ${typeof arg === 'string' ? arg : JSON.stringify(arg, null, 2)}\n`);
+            }
+        }
+    }
+    debug(message, ...args) {
+        this.write('debug', message, ...args);
+    }
+    info(message, ...args) {
+        this.write('info', message, ...args);
+    }
+    warn(message, ...args) {
+        this.write('warn', message, ...args);
+    }
+    error(message, ...args) {
+        this.write('error', message, ...args);
+    }
+}
+/**
+ * Create a namespaced logger instance.
+ * @param context - Module name (e.g., 'server', 'db', 'save-lesson')
+ */
+export function createLogger(context) {
+    return new Logger(context);
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,UAAU,GAA6B;IAC3C,KAAK,EAAE,UAAU,EAAG,OAAO;IAC3B,IAAI,EAAE,UAAU,EAAI,OAAO;IAC3B,IAAI,EAAE,UAAU,EAAI,SAAS;IAC7B,KAAK,EAAE,UAAU,EAAG,MAAM;CAC3B,CAAC;AAEF,MAAM,KAAK,GAAG,SAAS,CAAC;AAExB,MAAM,MAAM;IACF,OAAO,CAAS;IAChB,SAAS,CAAU;IAE3B,YAAY,OAAe;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,KAAK,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,KAAK,MAAM,CAAC;IACzF,CAAC;IAEO,KAAK,CAAC,KAAe,EAAE,OAAe,EAAE,GAAG,IAAe;QAChE,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO;QAEjD,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe;QACzE,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,MAAM,GAAG,GAAG,KAAK,IAAI,SAAS,MAAM,KAAK,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC,OAAO,IAAI,KAAK,EAAE,CAAC;QAE3F,wCAAwC;QACxC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,OAAO,IAAI,CAAC,CAAC;QAC/C,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YAC9F,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,GAAG,IAAe;QACvC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACxC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,GAAG,IAAe;QACtC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,GAAG,IAAe;QACtC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,GAAG,IAAe;QACvC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACxC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC"}

package/dist/utils/paths.d.ts

@@ -0,0 +1,17 @@
+/**
+ * XDG-compliant data directory for Athar.
+ *
+ * Linux:   ~/.local/share/athar/
+ * macOS:   ~/Library/Application Support/athar/
+ * Windows: %APPDATA%/athar/
+ */
+export declare function getDataDir(): string;
+/**
+ * Full path to the SQLite database file.
+ */
+export declare function getDatabasePath(): string;
+/**
+ * Path to the Antigravity IDE MCP config file.
+ */
+export declare function getMcpConfigPath(): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/utils/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/utils/paths.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAqBnC;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAGzC"}

package/dist/utils/paths.js

@@ -0,0 +1,43 @@
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, existsSync } from 'node:fs';
+/**
+ * XDG-compliant data directory for Athar.
+ *
+ * Linux:   ~/.local/share/athar/
+ * macOS:   ~/Library/Application Support/athar/
+ * Windows: %APPDATA%/athar/
+ */
+export function getDataDir() {
+    const home = homedir();
+    let dataDir;
+    switch (platform()) {
+        case 'darwin':
+            dataDir = join(home, 'Library', 'Application Support', 'athar');
+            break;
+        case 'win32':
+            dataDir = join(process.env.APPDATA || join(home, 'AppData', 'Roaming'), 'athar');
+            break;
+        default: // linux, freebsd, etc.
+            dataDir = join(process.env.XDG_DATA_HOME || join(home, '.local', 'share'), 'athar');
+            break;
+    }
+    if (!existsSync(dataDir)) {
+        mkdirSync(dataDir, { recursive: true });
+    }
+    return dataDir;
+}
+/**
+ * Full path to the SQLite database file.
+ */
+export function getDatabasePath() {
+    return join(getDataDir(), 'lessons.db');
+}
+/**
+ * Path to the Antigravity IDE MCP config file.
+ */
+export function getMcpConfigPath() {
+    const home = homedir();
+    return join(home, '.gemini', 'config', 'mcp_config.json');
+}
+//# sourceMappingURL=paths.js.map

package/dist/utils/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/utils/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,IAAI,OAAe,CAAC;IAEpB,QAAQ,QAAQ,EAAE,EAAE,CAAC;QACnB,KAAK,QAAQ;YACX,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,qBAAqB,EAAE,OAAO,CAAC,CAAC;YAChE,MAAM;QACR,KAAK,OAAO;YACV,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC;YACjF,MAAM;QACR,SAAS,uBAAuB;YAC9B,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;YACpF,MAAM;IACV,CAAC;IAED,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACzB,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,IAAI,CAAC,UAAU,EAAE,EAAE,YAAY,CAAC,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,OAAO,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC;AAC5D,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "athar-mcp",
+  "version": "0.1.0",
+  "description": "أثر — AI-powered programming lesson memory with spaced repetition. An MCP server that captures lessons from coding sessions and helps you never repeat the same mistake.",
+  "type": "module",
+  "bin": {
+    "athar": "./dist/cli/index.js",
+    "athar-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "dev:cli": "tsx src/cli/index.ts",
+    "test": "node --test",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "spaced-repetition",
+    "learning",
+    "programming-lessons",
+    "ai-assistant",
+    "antigravity",
+    "cli",
+    "sqlite",
+    "local-first"
+  ],
+  "author": "Ameen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ameenmv/athar.git"
+  },
+  "homepage": "https://github.com/ameenmv/athar#readme",
+  "bugs": {
+    "url": "https://github.com/ameenmv/athar/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "chalk": "^5.4.0",
+    "commander": "^13.0.0",
+    "inquirer": "^12.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}
+