@asd412id/mcp-context-manager 1.0.0 → 1.0.2

package/README.md

@@ -1,33 +1,197 @@
 # MCP Context Manager
 
-MCP (Model Context Protocol) tools untuk manajemen context pada AI coding agents. Membantu mengatasi masalah out-of-context pada chat yang panjang.
+MCP (Model Context Protocol) tools for context management in AI coding agents. Helps prevent out-of-context issues in long conversations.
 
 ## Features
 
-- **Memory Store** - Persistent key-value storage antar session
-- **Context Summarizer** - Ringkas chat/text, extract key points, decisions, action items
+- **Memory Store** - Persistent key-value storage across sessions
+- **Context Summarizer** - Summarize chat/text, extract key points, decisions, action items
 - **Project Tracker** - Track decisions, changes, todos, notes, errors
 - **Session Checkpoint** - Save/restore session state
-- **Smart File Loader** - Load file dengan filter relevansi
+- **Smart File Loader** - Load files with relevance filtering
 
 ## Installation
 
+Requires Node.js >= 18.0.0
+
 ```bash
+# Run directly with npx (recommended)
+npx @asd412id/mcp-context-manager
+
+# Or install globally
 npm install -g @asd412id/mcp-context-manager
 ```
 
-Atau jalankan langsung dengan npx:
+## Configuration by Client
 
-```bash
-npx @asd412id/mcp-context-manager
+### Claude Desktop
+
+**Config file location:**
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "context-manager": {
+      "command": "npx",
+      "args": ["-y", "@asd412id/mcp-context-manager"]
+    }
+  }
+}
 ```
 
-## Configuration
+### VS Code (GitHub Copilot / Claude Extension)
 
-### Claude Desktop
+**Option 1: Workspace config** - `.vscode/mcp.json`
+
+```json
+{
+  "servers": {
+    "context-manager": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@asd412id/mcp-context-manager"]
+    }
+  }
+}
+```
+
+**Option 2: User settings** - `settings.json`
+
+```json
+{
+  "mcp.servers": {
+    "context-manager": {
+      "command": "npx",
+      "args": ["-y", "@asd412id/mcp-context-manager"]
+    }
+  }
+}
+```
+
+### Cursor
 
-Tambahkan ke `claude_desktop_config.json`:
+**Config file location:**
+- **Windows:** `%APPDATA%\Cursor\mcp.json`
+- **macOS:** `~/Library/Application Support/Cursor/mcp.json`
+- **Linux:** `~/.config/Cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "context-manager": {
+      "command": "npx",
+      "args": ["-y", "@asd412id/mcp-context-manager"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+**Config file location:**
+- **Windows:** `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
+- **macOS:** `~/.codeium/windsurf/mcp_config.json`
+- **Linux:** `~/.codeium/windsurf/mcp_config.json`
+
+```json
+{
+  "mcpServers": {
+    "context-manager": {
+      "command": "npx",
+      "args": ["-y", "@asd412id/mcp-context-manager"]
+    }
+  }
+}
+```
+
+### Cline (VS Code Extension)
+
+**Config file location:**
+- **Windows:** `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
+- **macOS:** `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+- **Linux:** `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
 
+```json
+{
+  "mcpServers": {
+    "context-manager": {
+      "command": "npx",
+      "args": ["-y", "@asd412id/mcp-context-manager"],
+      "disabled": false,
+      "alwaysAllow": []
+    }
+  }
+}
+```
+
+### Continue (VS Code / JetBrains Extension)
+
+**Config file:** `~/.continue/config.json`
+
+```json
+{
+  "mcpServers": [
+    {
+      "name": "context-manager",
+      "command": "npx",
+      "args": ["-y", "@asd412id/mcp-context-manager"]
+    }
+  ]
+}
+```
+
+Or using YAML (`~/.continue/config.yaml`):
+
+```yaml
+mcpServers:
+  - name: context-manager
+    command: npx
+    args:
+      - "-y"
+      - "@asd412id/mcp-context-manager"
+```
+
+### OpenCode
+
+**Config file:** `opencode.json` in your project root or `~/.config/opencode/config.json`
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "context-manager": {
+      "type": "local",
+      "command": ["npx", "-y", "@asd412id/mcp-context-manager"],
+      "enabled": true
+    }
+  }
+}
+```
+
+### Zed Editor
+
+**Config file:** `~/.config/zed/settings.json`
+
+```json
+{
+  "context_servers": {
+    "context-manager": {
+      "command": "npx",
+      "args": ["-y", "@asd412id/mcp-context-manager"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Custom Context Path
+
+To specify a custom path for storing context data, add environment variables.
+
+**Claude Desktop / Cursor / Windsurf / Cline:**
 ```json
 {
   "mcpServers": {
@@ -42,35 +206,73 @@ Tambahkan ke `claude_desktop_config.json`:
 }
 ```
 
-### Environment Variables
+**OpenCode:**
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "context-manager": {
+      "type": "local",
+      "command": ["npx", "-y", "@asd412id/mcp-context-manager"],
+      "environment": {
+        "MCP_CONTEXT_PATH": "/path/to/your/project/.context"
+      }
+    }
+  }
+}
+```
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `MCP_CONTEXT_PATH` | Path untuk menyimpan context data | `{cwd}/.context` |
+**Zed:**
+```json
+{
+  "context_servers": {
+    "context-manager": {
+      "command": "npx",
+      "args": ["-y", "@asd412id/mcp-context-manager"],
+      "env": {
+        "MCP_CONTEXT_PATH": "/path/to/your/project/.context"
+      }
+    }
+  }
+}
+```
+
+## Prompts (Shortcut Commands)
 
-## Available Tools
+| Prompt | Description |
+|--------|-------------|
+| `ctx-init` | Load context from previous session |
+| `ctx-save` | Save current state to checkpoint |
+| `ctx-remember` | Save important info to memory |
+| `ctx-todo` | Add a todo item |
+| `ctx-decide` | Log a decision |
+| `ctx-status` | Show project status |
+| `ctx-compress` | Compress long context |
+| `ctx-recall` | Search in memory |
 
-### Memory Store (6 tools)
+## Available Tools (25 tools)
+
+### Memory Store
 
 | Tool | Description |
 |------|-------------|
-| `memory_set` | Simpan key-value ke memory |
-| `memory_get` | Ambil value dari memory |
-| `memory_search` | Cari memory by pattern/tags |
-| `memory_delete` | Hapus memory entry |
-| `memory_list` | List semua memory keys |
+| `memory_set` | Store key-value in memory |
+| `memory_get` | Retrieve value from memory |
+| `memory_search` | Search memory by pattern/tags |
+| `memory_delete` | Delete memory entry |
+| `memory_list` | List all memory keys |
 | `memory_clear` | Clear memory (all/by tags) |
 
-### Context Summarizer (4 tools)
+### Context Summarizer
 
 | Tool | Description |
 |------|-------------|
-| `context_summarize` | Ringkas text, extract key points, decisions, action items |
-| `context_get_summary` | Ambil summary by ID |
-| `context_list_summaries` | List semua summaries |
-| `context_merge_summaries` | Gabungkan beberapa summaries |
+| `context_summarize` | Summarize text, extract key points, decisions, action items |
+| `context_get_summary` | Get summary by ID |
+| `context_list_summaries` | List all summaries |
+| `context_merge_summaries` | Merge multiple summaries |
 
-### Project Tracker (6 tools)
+### Project Tracker
 
 | Tool | Description |
 |------|-------------|
@@ -81,7 +283,7 @@ Tambahkan ke `claude_desktop_config.json`:
 | `tracker_set_project` | Set project name |
 | `tracker_export` | Export tracker as markdown |
 
-### Session Checkpoint (5 tools)
+### Session Checkpoint
 
 | Tool | Description |
 |------|-------------|
@@ -91,7 +293,7 @@ Tambahkan ke `claude_desktop_config.json`:
 | `checkpoint_delete` | Delete checkpoint |
 | `checkpoint_compare` | Compare 2 checkpoints |
 
-### Smart File Loader (4 tools)
+### Smart File Loader
 
 | Tool | Description |
 |------|-------------|
@@ -100,84 +302,88 @@ Tambahkan ke `claude_desktop_config.json`:
 | `file_search_content` | Search pattern in file |
 | `file_list_dir` | List directory files |
 
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MCP_CONTEXT_PATH` | Path to store context data | `{cwd}/.context` |
+
 ## Usage Examples
 
-### Memory Store
+### Session Start Workflow
 
 ```
-// Save important context
-memory_set({ key: "api_base_url", value: "https://api.example.com", tags: ["config"] })
+User: ctx-init
+AI: *runs checkpoint_load(), tracker_status(), memory_list()*
+```
 
-// Retrieve later
-memory_get({ key: "api_base_url" })
+### Save Important Information
 
-// Search by tags
-memory_search({ tags: ["config"] })
+```
+User: ctx-remember what:"API endpoint at https://api.example.com"
+AI: *saves to memory with appropriate key and tags*
 ```
 
-### Context Summarizer
+### Before Ending Session
 
 ```
-// Summarize long conversation
-context_summarize({ 
-  text: "..long conversation..", 
-  maxLength: 2000,
-  sessionId: "session-123"
-})
-
-// Merge multiple summaries
-context_merge_summaries({ ids: ["sum_1", "sum_2", "sum_3"] })
+User: ctx-save name:"feature-login-done"
+AI: *creates checkpoint with current state*
 ```
 
-### Project Tracker
+### When Context Gets Long
 
 ```
-// Log a decision
-tracker_log({ type: "decision", content: "Using PostgreSQL for database", tags: ["database"] })
+User: ctx-compress
+AI: *summarize conversation, save checkpoint, store key info*
+```
 
-// Log a todo
-tracker_log({ type: "todo", content: "Implement user authentication" })
+## Best Practices
 
-// Get project status
-tracker_status()
-```
+1. **Session start** - Always run `ctx-init` to load previous context
+2. **Save decisions** - Use `ctx-decide` for every important decision
+3. **Track todos** - Use `ctx-todo` for tasks to be done
+4. **Checkpoint regularly** - Run `ctx-save` every ~15-20 messages or after milestones
+5. **Compress when long** - Use `ctx-compress` if chat gets too long
 
-### Session Checkpoint
+## Data Storage
 
-```
-// Save checkpoint before major changes
-checkpoint_save({
-  name: "before-refactor",
-  description: "Completed user module, starting refactor",
-  state: { currentTask: "refactoring", completedFiles: ["user.ts"] },
-  files: ["src/user.ts", "src/auth.ts"]
-})
+All data is stored in `.context/` folder (default: working directory):
 
-// Load checkpoint in new session
-checkpoint_load({ name: "before-refactor" })
+```
+.context/
+├── memory.json          # Memory store
+├── tracker.json         # Project tracker
+├── checkpoints/         # Session checkpoints
+│   ├── index.json
+│   └── cp_*.json
+└── summaries/           # Context summaries
+    └── index.json
 ```
 
-### Smart File Loader
+## Troubleshooting
 
-```
-// Read only code structure
-file_smart_read({ path: "src/index.ts", structureOnly: true })
+### Server not starting
 
-// Read specific lines
-file_smart_read({ path: "src/index.ts", startLine: 50, endLine: 100 })
+1. Make sure Node.js >= 18 is installed: `node --version`
+2. Try running manually: `npx @asd412id/mcp-context-manager`
+3. Check if port/process conflicts exist
 
-// Search by keywords
-file_smart_read({ path: "src/index.ts", keywords: ["function", "export"] })
-```
+### Tools not appearing
+
+1. Restart your MCP client after configuration changes
+2. Check config file syntax (valid JSON)
+3. Verify the config file location is correct for your client
 
-## Best Practices untuk Optimasi Context
+### Permission issues
 
-1. **Gunakan memory_set** untuk menyimpan informasi penting yang perlu diingat
-2. **Buat checkpoint** sebelum context terlalu panjang
-3. **Summarize conversation** secara berkala
-4. **Track decisions** agar tidak perlu explain ulang
-5. **Load file secara smart** - hanya bagian yang diperlukan
+1. Ensure write access to the context path
+2. Try setting explicit `MCP_CONTEXT_PATH` in env
 
 ## License
 
 MIT
+
+## Contributing
+
+Issues and PRs welcome at [GitHub](https://github.com/asd412id/mcp-context-manager)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asd412id/mcp-context-manager",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "MCP tools for context management - summarizer, memory store, project tracker, checkpoints, and smart file loader",
   "type": "module",
   "main": "dist/index.js",