athar-mcp 0.2.1 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +57 -172
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
- # أثر — Athar
1
+ # Athar
2
2
 
3
3
  > **Every mistake leaves a trace, every lesson leaves an impact.**
4
4
 
5
- An open-source, local-first MCP server that captures programming lessons from AI-assisted coding sessions, stores them in a local SQLite database, and uses spaced repetition to ensure you never repeat the same mistake twice.
5
+ Athar is an open-source, local-first MCP (Model Context Protocol) server designed to capture non-trivial software engineering lessons from your daily AI-assisted coding sessions. It operates silently in the background, intercepting teachable moments, storing them in a local SQLite database, and reinforcing long-term retention via a Spaced Repetition System (SM-2).
6
6
 
7
7
  <div align="center">
8
8
 
@@ -15,13 +15,13 @@ An open-source, local-first MCP server that captures programming lessons from AI
15
15
 
16
16
  ---
17
17
 
18
- ## 🧠 What is Athar?
18
+ ## What is Athar?
19
19
 
20
- **Athar** (أثر) is a memory system for developers. It works as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that integrates with AI-powered IDEs like [Antigravity IDE](https://antigravity.google).
20
+ **Athar** (أثر) acts as an engineering memory system. By integrating natively with MCP-compatible IDEs (such as Antigravity IDE, Cursor, and VS Code), it bridges the gap between solving a bug and actually learning from it.
21
21
 
22
- When you're coding with an AI assistant and it helps you fix a real bug, Athar automatically captures the lesson — the problem, root cause, fix, and review questions — and stores it locally. Later, it uses **spaced repetition** (SM-2 algorithm) to quiz you on past mistakes so they stick in your memory permanently.
22
+ When you resolve a complex issue with your AI assistant, the AI evaluates the architectural or pedagogical value of the fix. If deemed valuable, the AI autonomously invokes Athar to capture the problem, root cause, code diffs, and review questions. Later, you can leverage Athar's built-in spaced repetition CLI or Nuxt 4 web dashboard to permanently commit these insights to memory.
23
23
 
24
- ### How it works
24
+ ### Architecture
25
25
 
26
26
  ```
27
27
  ┌─────────────────────┐ stdio ┌──────────────────┐
@@ -32,211 +32,96 @@ When you're coding with an AI assistant and it helps you fix a real bug, Athar a
32
32
  ┌────────▼─────────┐
33
33
  │ SQLite DB │
34
34
  │ (local-first) │
35
- │ ~/.local/share/ │
36
- │ athar/lessons.db│
37
- └──────────────────┘
35
+ │ ~/.local/share/│
36
+ │ athar/lessons │
37
+ └────────┬─────────┘
38
38
  │
39
39
  ┌────────▼─────────┐
40
- │ CLI & Dashboard │
41
- │ athar review │
42
- │ athar status │
40
+ │ CLI & Dashboard │
41
+ │ athar review │
42
+ │ athar dashboard │
43
43
  └──────────────────┘
44
44
  ```
45
45
 
46
46
  ---
47
47
 
48
- ## ✨ Features
48
+ ## Features
49
49
 
50
- - **🔌 MCP Integration** — Works seamlessly with Antigravity IDE via stdio transport
51
- - **📝 Smart Lesson Capture** — AI assistant saves lessons with structured data: problem, root cause, bad/good code, review questions
52
- - **🛡️ Quality Validation** — Rejects trivial changes (formatting, typos) and detects duplicates
53
- - **🔍 Full-Text Search** — FTS5-powered search to recall past lessons instantly
54
- - **🧠 Spaced Repetition** — SM-2 algorithm schedules reviews at optimal intervals
55
- - **💾 Local-First** — All data stored locally in SQLite. No cloud, no API keys, no costs
56
- - **🌐 Bilingual** — Supports lessons in both Arabic and English
57
- - **⚡ Zero Native Dependencies** — Uses Node.js built-in `node:sqlite` module
50
+ - **MCP Integration**: Native integration with standard MCP-compatible IDEs via stdio transport.
51
+ - **Autonomous Knowledge Capture**: AI autonomously filters and saves high-value engineering lessons.
52
+ - **Quality Validation Pipeline**: Automatic rejection of trivial modifications (e.g., typos, linting) and FTS5-based duplicate detection.
53
+ - **Spaced Repetition Engine**: Built-in SuperMemo-2 (SM-2) algorithm calculates dynamic review intervals based on recall accuracy.
54
+ - **Visual Analytics Dashboard**: A bundled, locally-served Nuxt 4 application offering side-by-side code diffs and mastery metrics.
55
+ - **Local-First & Privacy Preserving**: Zero telemetry. 100% of your data remains on your local filesystem using `node:sqlite`.
58
56
 
59
57
  ---
60
58
 
61
- ## 🚀 Quick Start
59
+ ## Setup Guide
62
60
 
63
- ### Prerequisites
61
+ ### Requirements
62
+ - **Node.js**: v20.0.0 or higher (Strict requirement for native `node:sqlite`).
63
+ - **IDE**: Any MCP-compatible IDE.
64
64
 
65
- - **Node.js** ≥ 20 (tested on v24)
66
- - **Antigravity IDE** (or any MCP-compatible IDE)
65
+ ### 1. Global Installation
67
66
 
68
- ### Installation
67
+ Install the package globally via npm:
69
68
 
70
69
  ```bash
71
- # Clone the repository
72
- git clone https://github.com/ameenmv/athar.git
73
- cd athar
74
-
75
- # Install dependencies
76
- npm install
77
-
78
- # Build
79
- npm run build
70
+ npm install -g athar-mcp
80
71
  ```
81
72
 
82
- ### Setup with Antigravity IDE
73
+ ### 2. IDE Integration
83
74
 
84
- Run the setup command (coming in Phase 2), or manually add to your MCP config:
75
+ To register the MCP server with your IDE, execute the automated setup command:
85
76
 
86
- **`~/.gemini/config/mcp_config.json`**
87
-
88
- ```json
89
- {
90
- "mcpServers": {
91
- "athar": {
92
- "command": "node",
93
- "args": ["/absolute/path/to/athar/dist/index.js"]
94
- }
95
- }
96
- }
77
+ ```bash
78
+ athar setup
97
79
  ```
98
80
 
99
- Then restart/refresh MCP servers in Antigravity IDE.
100
-
101
- ---
102
-
103
- ## 🛠️ MCP Tools
104
-
105
- Athar exposes two tools to the AI assistant:
106
-
107
- ### `save_lesson`
108
-
109
- Captures a programming lesson from a real mistake.
110
-
111
- | Field | Type | Required | Description |
112
- |-------|------|----------|-------------|
113
- | `title` | string | ✅ | Concise title describing the mistake pattern |
114
- | `problem` | string | ✅ | What went wrong — the symptom observed |
115
- | `root_cause` | string | ✅ | WHY it happened — the actual root cause |
116
- | `lesson` | string | ✅ | Key takeaway — what to remember |
117
- | `tags` | string[] | ✅ | Categorization tags |
118
- | `review_questions` | {q,a}[] | ✅ | 1-3 review questions for spaced repetition |
119
- | `error_message` | string | ❌ | Exact error message or stack trace |
120
- | `bad_code` | string | ❌ | The incorrect code snippet |
121
- | `good_code` | string | ❌ | The corrected code snippet |
122
- | `language` | string | ❌ | Programming language |
123
- | `file_path` | string | ❌ | File where the error occurred |
124
- | `git_diff` | string | ❌ | Git diff context |
125
-
126
- **Validation rules:**
127
- - Rejects trivial formatting/style changes
128
- - Rejects if problem and root_cause are identical
129
- - Requires both bad_code and good_code if either is provided
130
- - Detects and rejects duplicates via FTS5 similarity
131
-
132
- ### `memory`
133
-
134
- Searches past lessons for relevant mistakes and solutions.
135
-
136
- | Field | Type | Required | Description |
137
- |-------|------|----------|-------------|
138
- | `query` | string | ✅ | Search query — keyword, error pattern, or tag |
139
- | `limit` | number | ❌ | Max results (1-10, default: 3) |
140
- | `language` | string | ❌ | Filter by programming language |
141
- | `tags` | string[] | ❌ | Filter by tags |
142
-
143
- ---
81
+ This utility will locate your IDE configuration (e.g., `mcp_config.json`) and automatically inject the local server binary.
144
82
 
145
- ## 📁 Project Structure
146
-
147
- ```
148
- athar/
149
- ├── src/
150
- │ ├── index.ts # MCP server entry point
151
- │ ├── server.ts # McpServer setup & tool registration
152
- │ ├── db/
153
- │ │ ├── schema.ts # SQLite schema + FTS5 + triggers
154
- │ │ └── connection.ts # Database singleton
155
- │ ├── tools/
156
- │ │ ├── save-lesson.ts # save_lesson handler + validation
157
- │ │ ├── memory.ts # memory search handler
158
- │ │ └── validators.ts # Zod schemas
159
- │ ├── spaced-repetition/ # SM-2 algorithm (Phase 3)
160
- │ ├── cli/ # CLI commands (Phase 3)
161
- │ └── utils/
162
- │ ├── paths.ts # XDG-compliant paths
163
- │ └── logger.ts # stderr-only logger
164
- ├── dashboard/ # Nuxt 4 web UI (Phase 4)
165
- ├── package.json
166
- └── tsconfig.json
167
- ```
83
+ > **Critical**: After running setup, restart your IDE or execute a refresh of your MCP servers list to guarantee the tools are registered in the LLM context.
168
84
 
169
85
  ---
170
86
 
171
- ## 🗺️ Roadmap
172
-
173
- - [x] **Phase 1** — Core MCP Server & Database
174
- - [x] SQLite schema with FTS5 full-text search
175
- - [x] `save_lesson` tool with quality validation
176
- - [x] `memory` search tool with FTS5 + LIKE fallback
177
- - [x] Duplicate detection
178
- - [x] stderr-only logging (MCP-safe)
87
+ ## Command Line Interface (CLI)
179
88
 
180
- - [ ] **Phase 2** — IDE Integration
181
- - [ ] `athar setup` command for Antigravity IDE
182
- - [ ] Auto-detect and configure MCP settings
183
-
184
- - [ ] **Phase 3** — Spaced Repetition & CLI
185
- - [ ] SM-2 algorithm implementation
186
- - [ ] `athar review` — interactive terminal review sessions
187
- - [ ] `athar status` — pending reviews dashboard
188
- - [ ] `athar list` — browse and filter lessons
189
-
190
- - [ ] **Phase 4** — Nuxt 4 Dashboard
191
- - [ ] Web UI for browsing lessons
192
- - [ ] Syntax-highlighted code diff viewer
193
- - [ ] Review progress visualization
194
-
195
- ---
196
-
197
- ## 🧪 Development
89
+ Athar is primarily managed via its robust CLI interface.
198
90
 
91
+ ### Active Review
92
+ To execute your daily spaced repetition session:
199
93
  ```bash
200
- # Type check
201
- npm run typecheck
202
-
203
- # Build
204
- npm run build
205
-
206
- # Run MCP server directly (for testing)
207
- npm run dev
208
-
209
- # Run smoke tests
210
- npx tsx src/smoke-test.ts
94
+ athar review
211
95
  ```
96
+ *The CLI will sequentially prompt you with technical questions generated from past bugs. Grade your response accuracy (0-5) to inform the SM-2 scheduling algorithm.*
212
97
 
213
- ### Debug logging
214
-
215
- Set `ATHAR_DEBUG=1` to enable verbose logging to stderr:
216
-
98
+ ### Dashboard
99
+ Launch the visual web interface:
217
100
  ```bash
218
- ATHAR_DEBUG=1 npm run dev
101
+ athar dashboard
219
102
  ```
103
+ *This initiates a Nitro server on `http://127.0.0.1:3333`, providing access to your full lesson repository and analytics.*
220
104
 
221
- ---
105
+ ### Data Management
106
+ - **`athar status`**: Check pending review queues and mastery distribution.
107
+ - **`athar list --language typescript --tag architecture`**: Search and filter your local engineering memory.
222
108
 
223
- ## 💡 How the AI Decides to Save a Lesson
109
+ ---
224
110
 
225
- The MCP server includes detailed instructions for the AI assistant. It will save a lesson when:
111
+ ## AI Heuristics: When are lessons saved?
226
112
 
227
- - ✅ Helping fix a **non-trivial bug** with a clear root cause
228
- - ✅ Correcting a **misconception** about an API or framework
229
- - ✅ A **debugging session** reveals unexpected behavior
230
- - ✅ An **architectural mistake** is identified
231
- - ✅ A **security vulnerability** or performance issue is discovered
113
+ The MCP server maintains strict system prompts instructing the IDE's AI assistant. Lessons are actively captured during:
114
+ - Resolution of **non-trivial logic bugs** with identifiable root causes.
115
+ - Correction of **fundamental misconceptions** regarding APIs or frameworks.
116
+ - Identification of **architectural anti-patterns** or security vulnerabilities.
232
117
 
233
- It will **NOT** save for:
234
- - ❌ Simple typos or formatting fixes
235
- - ❌ Routine code generation
236
- - ❌ Style preferences
118
+ Lessons are intentionally bypassed for:
119
+ - Syntax formatting or styling preferences.
120
+ - Standard boilerplate generation.
121
+ - Repetitive, previously mastered content.
237
122
 
238
123
  ---
239
124
 
240
- ## 📄 License
125
+ ## License
241
126
 
242
- [MIT](LICENSE) — Built with ❤️ by [Ameen](https://github.com/ameenmv)
127
+ [MIT](LICENSE) — Maintained by [Ameen](https://github.com/ameenmv).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "athar-mcp",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
4
  "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.",
5
5
  "type": "module",
6
6
  "bin": {