@asd412id/mcp-context-manager 1.0.0

package/README.md

@@ -0,0 +1,183 @@
+# 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.
+
+## Features
+
+- **Memory Store** - Persistent key-value storage antar session
+- **Context Summarizer** - Ringkas 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
+
+## Installation
+
+```bash
+npm install -g @asd412id/mcp-context-manager
+```
+
+Atau jalankan langsung dengan npx:
+
+```bash
+npx @asd412id/mcp-context-manager
+```
+
+## Configuration
+
+### Claude Desktop
+
+Tambahkan ke `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "context-manager": {
+      "command": "npx",
+      "args": ["-y", "@asd412id/mcp-context-manager"],
+      "env": {
+        "MCP_CONTEXT_PATH": "/path/to/your/project/.context"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MCP_CONTEXT_PATH` | Path untuk menyimpan context data | `{cwd}/.context` |
+
+## Available Tools
+
+### Memory Store (6 tools)
+
+| 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_clear` | Clear memory (all/by tags) |
+
+### Context Summarizer (4 tools)
+
+| 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 |
+
+### Project Tracker (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `tracker_log` | Log decision/change/todo/note/error |
+| `tracker_status` | Get project status overview |
+| `tracker_todo_update` | Update todo status |
+| `tracker_search` | Search tracker entries |
+| `tracker_set_project` | Set project name |
+| `tracker_export` | Export tracker as markdown |
+
+### Session Checkpoint (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `checkpoint_save` | Save session state |
+| `checkpoint_load` | Load checkpoint |
+| `checkpoint_list` | List all checkpoints |
+| `checkpoint_delete` | Delete checkpoint |
+| `checkpoint_compare` | Compare 2 checkpoints |
+
+### Smart File Loader (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `file_smart_read` | Read file with smart options (lines, keywords, structure) |
+| `file_info` | Get file metadata |
+| `file_search_content` | Search pattern in file |
+| `file_list_dir` | List directory files |
+
+## Usage Examples
+
+### Memory Store
+
+```
+// Save important context
+memory_set({ key: "api_base_url", value: "https://api.example.com", tags: ["config"] })
+
+// Retrieve later
+memory_get({ key: "api_base_url" })
+
+// Search by tags
+memory_search({ tags: ["config"] })
+```
+
+### Context Summarizer
+
+```
+// 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"] })
+```
+
+### Project Tracker
+
+```
+// Log a decision
+tracker_log({ type: "decision", content: "Using PostgreSQL for database", tags: ["database"] })
+
+// Log a todo
+tracker_log({ type: "todo", content: "Implement user authentication" })
+
+// Get project status
+tracker_status()
+```
+
+### Session Checkpoint
+
+```
+// 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"]
+})
+
+// Load checkpoint in new session
+checkpoint_load({ name: "before-refactor" })
+```
+
+### Smart File Loader
+
+```
+// Read only code structure
+file_smart_read({ path: "src/index.ts", structureOnly: true })
+
+// Read specific lines
+file_smart_read({ path: "src/index.ts", startLine: 50, endLine: 100 })
+
+// Search by keywords
+file_smart_read({ path: "src/index.ts", keywords: ["function", "export"] })
+```
+
+## Best Practices untuk Optimasi Context
+
+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
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as path from 'path';
+import { initStore } from './storage/file-store.js';
+import { registerMemoryTools } from './tools/memory.js';
+import { registerSummarizerTools } from './tools/summarizer.js';
+import { registerTrackerTools } from './tools/tracker.js';
+import { registerCheckpointTools } from './tools/checkpoint.js';
+import { registerLoaderTools } from './tools/loader.js';
+import { registerPrompts } from './prompts.js';
+const SERVER_NAME = 'mcp-context-manager';
+const SERVER_VERSION = '1.0.0';
+async function main() {
+    const contextPath = process.env.MCP_CONTEXT_PATH || path.join(process.cwd(), '.context');
+    initStore(contextPath);
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION
+    });
+    registerMemoryTools(server);
+    registerSummarizerTools(server);
+    registerTrackerTools(server);
+    registerCheckpointTools(server);
+    registerLoaderTools(server);
+    registerPrompts(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`${SERVER_NAME} v${SERVER_VERSION} started`);
+    console.error(`Context path: ${contextPath}`);
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/prompts.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerPrompts(server: McpServer): void;

package/dist/prompts.js

@@ -0,0 +1,127 @@
+import * as z from 'zod';
+export function registerPrompts(server) {
+    // ctx-init - Load previous context
+    server.registerPrompt('ctx-init', {
+        title: 'Init Session',
+        description: 'Load previous context at session start'
+    }, () => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Load previous context:
+1. checkpoint_load() - get last state
+2. tracker_status() - see todos & decisions
+3. memory_list() - check saved data`
+                }
+            }]
+    }));
+    // ctx-save - Quick save current state
+    server.registerPrompt('ctx-save', {
+        title: 'Save State',
+        description: 'Quick save current session state',
+        argsSchema: {
+            name: z.string().optional().describe('Checkpoint name')
+        }
+    }, ({ name }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Save current state to checkpoint "${name || 'auto'}". Include: current task, progress, important decisions, modified files.`
+                }
+            }]
+    }));
+    // ctx-remember - Save to memory
+    server.registerPrompt('ctx-remember', {
+        title: 'Remember',
+        description: 'Save important info to memory',
+        argsSchema: {
+            what: z.string().describe('What to remember')
+        }
+    }, ({ what }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Save to memory: "${what}". Use descriptive key and appropriate tags.`
+                }
+            }]
+    }));
+    // ctx-todo - Add todo item
+    server.registerPrompt('ctx-todo', {
+        title: 'Add Todo',
+        description: 'Log a todo item',
+        argsSchema: {
+            task: z.string().describe('Task to do')
+        }
+    }, ({ task }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Log todo: "${task}"`
+                }
+            }]
+    }));
+    // ctx-decide - Log decision
+    server.registerPrompt('ctx-decide', {
+        title: 'Log Decision',
+        description: 'Record a decision',
+        argsSchema: {
+            decision: z.string().describe('Decision made')
+        }
+    }, ({ decision }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Log decision: "${decision}"`
+                }
+            }]
+    }));
+    // ctx-status - Get current status
+    server.registerPrompt('ctx-status', {
+        title: 'Status',
+        description: 'Show project status'
+    }, () => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Show: tracker_status(), memory_list(), checkpoint_list()`
+                }
+            }]
+    }));
+    // ctx-compress - Summarize long context
+    server.registerPrompt('ctx-compress', {
+        title: 'Compress Context',
+        description: 'Summarize to save context space'
+    }, () => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Context getting long. Summarize conversation with context_summarize(), save checkpoint, store key info to memory.`
+                }
+            }]
+    }));
+    // ctx-recall - Search memories
+    server.registerPrompt('ctx-recall', {
+        title: 'Recall',
+        description: 'Search saved memories',
+        argsSchema: {
+            query: z.string().optional().describe('Search term')
+        }
+    }, ({ query }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: query
+                        ? `Search memories for: "${query}"`
+                        : `List all memories with memory_list()`
+                }
+            }]
+    }));
+}

package/dist/storage/file-store.d.ts

@@ -0,0 +1,18 @@
+export interface StoreOptions {
+    basePath: string;
+}
+export declare class FileStore {
+    private basePath;
+    constructor(options: StoreOptions);
+    private ensureDir;
+    private getFilePath;
+    read<T>(filename: string, defaultValue: T): Promise<T>;
+    write<T>(filename: string, data: T): Promise<void>;
+    append<T>(filename: string, item: T): Promise<void>;
+    delete(filename: string): Promise<boolean>;
+    exists(filename: string): Promise<boolean>;
+    list(subdir?: string): Promise<string[]>;
+    getSubStore(subdir: string): FileStore;
+}
+export declare function getStore(basePath?: string): FileStore;
+export declare function initStore(basePath: string): FileStore;

package/dist/storage/file-store.js

@@ -0,0 +1,84 @@
+import * as fs from 'fs';
+import * as path from 'path';
+export class FileStore {
+    basePath;
+    constructor(options) {
+        this.basePath = options.basePath;
+        this.ensureDir(this.basePath);
+    }
+    ensureDir(dirPath) {
+        if (!fs.existsSync(dirPath)) {
+            fs.mkdirSync(dirPath, { recursive: true });
+        }
+    }
+    getFilePath(filename) {
+        return path.join(this.basePath, filename);
+    }
+    async read(filename, defaultValue) {
+        const filePath = this.getFilePath(filename);
+        try {
+            if (fs.existsSync(filePath)) {
+                const content = fs.readFileSync(filePath, 'utf-8');
+                return JSON.parse(content);
+            }
+        }
+        catch (error) {
+            console.error(`Error reading ${filename}:`, error);
+        }
+        return defaultValue;
+    }
+    async write(filename, data) {
+        const filePath = this.getFilePath(filename);
+        const dir = path.dirname(filePath);
+        this.ensureDir(dir);
+        fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+    }
+    async append(filename, item) {
+        const existing = await this.read(filename, []);
+        existing.push(item);
+        await this.write(filename, existing);
+    }
+    async delete(filename) {
+        const filePath = this.getFilePath(filename);
+        try {
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+                return true;
+            }
+        }
+        catch (error) {
+            console.error(`Error deleting ${filename}:`, error);
+        }
+        return false;
+    }
+    async exists(filename) {
+        return fs.existsSync(this.getFilePath(filename));
+    }
+    async list(subdir) {
+        const dirPath = subdir ? path.join(this.basePath, subdir) : this.basePath;
+        this.ensureDir(dirPath);
+        try {
+            return fs.readdirSync(dirPath).filter(f => f.endsWith('.json'));
+        }
+        catch {
+            return [];
+        }
+    }
+    getSubStore(subdir) {
+        return new FileStore({
+            basePath: path.join(this.basePath, subdir)
+        });
+    }
+}
+let storeInstance = null;
+export function getStore(basePath) {
+    if (!storeInstance) {
+        const defaultPath = path.join(process.cwd(), '.context');
+        storeInstance = new FileStore({ basePath: basePath || defaultPath });
+    }
+    return storeInstance;
+}
+export function initStore(basePath) {
+    storeInstance = new FileStore({ basePath });
+    return storeInstance;
+}

package/dist/tools/checkpoint.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerCheckpointTools(server: McpServer): void;

package/dist/tools/checkpoint.js

@@ -0,0 +1,192 @@
+import * as z from 'zod';
+import { getStore } from '../storage/file-store.js';
+const CHECKPOINTS_DIR = 'checkpoints';
+async function getCheckpointStore() {
+    const store = getStore().getSubStore(CHECKPOINTS_DIR);
+    return store.read('index.json', { checkpoints: [] });
+}
+async function saveCheckpointStore(data) {
+    const store = getStore().getSubStore(CHECKPOINTS_DIR);
+    await store.write('index.json', data);
+}
+async function saveCheckpointData(id, data) {
+    const store = getStore().getSubStore(CHECKPOINTS_DIR);
+    await store.write(`${id}.json`, data);
+}
+async function loadCheckpointData(id) {
+    const store = getStore().getSubStore(CHECKPOINTS_DIR);
+    if (await store.exists(`${id}.json`)) {
+        return store.read(`${id}.json`, {});
+    }
+    return null;
+}
+export function registerCheckpointTools(server) {
+    server.registerTool('checkpoint_save', {
+        title: 'Save Checkpoint',
+        description: 'Save current session state as a checkpoint. Use before context gets too long or at important milestones.',
+        inputSchema: {
+            name: z.string().describe('Checkpoint name (e.g., "before-refactor", "feature-complete")'),
+            description: z.string().optional().describe('Description of what was accomplished'),
+            state: z.record(z.unknown()).describe('State data to save (conversation summary, current task, etc.)'),
+            files: z.array(z.string()).optional().describe('List of relevant file paths')
+        }
+    }, async ({ name, description, state, files }) => {
+        const checkpointStore = await getCheckpointStore();
+        const checkpoint = {
+            id: `cp_${Date.now()}`,
+            name,
+            description,
+            state,
+            files: files || [],
+            createdAt: new Date().toISOString()
+        };
+        await saveCheckpointData(checkpoint.id, state);
+        checkpointStore.checkpoints.push({
+            ...checkpoint,
+            state: {}
+        });
+        await saveCheckpointStore(checkpointStore);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Checkpoint saved: "${name}" (ID: ${checkpoint.id})\nDescription: ${description || 'N/A'}\nFiles: ${files?.length || 0}`
+                }]
+        };
+    });
+    server.registerTool('checkpoint_load', {
+        title: 'Load Checkpoint',
+        description: 'Load a previously saved checkpoint to restore context.',
+        inputSchema: {
+            id: z.string().optional().describe('Checkpoint ID (loads latest if not specified)'),
+            name: z.string().optional().describe('Checkpoint name to search for')
+        }
+    }, async ({ id, name }) => {
+        const checkpointStore = await getCheckpointStore();
+        let checkpoint;
+        if (id) {
+            checkpoint = checkpointStore.checkpoints.find(cp => cp.id === id);
+        }
+        else if (name) {
+            checkpoint = checkpointStore.checkpoints
+                .filter(cp => cp.name.toLowerCase().includes(name.toLowerCase()))
+                .pop();
+        }
+        else {
+            checkpoint = checkpointStore.checkpoints[checkpointStore.checkpoints.length - 1];
+        }
+        if (!checkpoint) {
+            return {
+                content: [{ type: 'text', text: 'Checkpoint not found' }]
+            };
+        }
+        const stateData = await loadCheckpointData(checkpoint.id);
+        const output = {
+            id: checkpoint.id,
+            name: checkpoint.name,
+            description: checkpoint.description,
+            createdAt: checkpoint.createdAt,
+            files: checkpoint.files,
+            state: stateData
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(output, null, 2) }]
+        };
+    });
+    server.registerTool('checkpoint_list', {
+        title: 'List Checkpoints',
+        description: 'List all saved checkpoints.',
+        inputSchema: {
+            limit: z.number().optional().describe('Maximum checkpoints to return (default: 10)')
+        }
+    }, async ({ limit = 10 }) => {
+        const checkpointStore = await getCheckpointStore();
+        const checkpoints = checkpointStore.checkpoints.slice(-limit);
+        if (checkpoints.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No checkpoints saved' }]
+            };
+        }
+        const list = checkpoints.map(cp => ({
+            id: cp.id,
+            name: cp.name,
+            description: cp.description,
+            createdAt: cp.createdAt,
+            filesCount: cp.files.length
+        }));
+        return {
+            content: [{ type: 'text', text: JSON.stringify(list, null, 2) }]
+        };
+    });
+    server.registerTool('checkpoint_delete', {
+        title: 'Delete Checkpoint',
+        description: 'Delete a checkpoint by ID.',
+        inputSchema: {
+            id: z.string().describe('Checkpoint ID to delete')
+        }
+    }, async ({ id }) => {
+        const checkpointStore = await getCheckpointStore();
+        const index = checkpointStore.checkpoints.findIndex(cp => cp.id === id);
+        if (index === -1) {
+            return {
+                content: [{ type: 'text', text: `Checkpoint not found: ${id}` }]
+            };
+        }
+        const removed = checkpointStore.checkpoints.splice(index, 1)[0];
+        await saveCheckpointStore(checkpointStore);
+        const store = getStore().getSubStore(CHECKPOINTS_DIR);
+        await store.delete(`${id}.json`);
+        return {
+            content: [{ type: 'text', text: `Deleted checkpoint: "${removed.name}" (${id})` }]
+        };
+    });
+    server.registerTool('checkpoint_compare', {
+        title: 'Compare Checkpoints',
+        description: 'Compare two checkpoints to see what changed.',
+        inputSchema: {
+            id1: z.string().describe('First checkpoint ID'),
+            id2: z.string().describe('Second checkpoint ID')
+        }
+    }, async ({ id1, id2 }) => {
+        const checkpointStore = await getCheckpointStore();
+        const cp1 = checkpointStore.checkpoints.find(cp => cp.id === id1);
+        const cp2 = checkpointStore.checkpoints.find(cp => cp.id === id2);
+        if (!cp1 || !cp2) {
+            return {
+                content: [{ type: 'text', text: 'One or both checkpoints not found' }]
+            };
+        }
+        const state1 = await loadCheckpointData(id1) || {};
+        const state2 = await loadCheckpointData(id2) || {};
+        const allKeys = new Set([...Object.keys(state1), ...Object.keys(state2)]);
+        const changes = [];
+        for (const key of allKeys) {
+            const v1 = JSON.stringify(state1[key]);
+            const v2 = JSON.stringify(state2[key]);
+            if (v1 !== v2) {
+                if (!state1[key]) {
+                    changes.push({ key, change: 'added' });
+                }
+                else if (!state2[key]) {
+                    changes.push({ key, change: 'removed' });
+                }
+                else {
+                    changes.push({ key, change: 'modified' });
+                }
+            }
+        }
+        const newFiles = cp2.files.filter(f => !cp1.files.includes(f));
+        const removedFiles = cp1.files.filter(f => !cp2.files.includes(f));
+        const comparison = {
+            checkpoint1: { id: cp1.id, name: cp1.name, date: cp1.createdAt },
+            checkpoint2: { id: cp2.id, name: cp2.name, date: cp2.createdAt },
+            stateChanges: changes,
+            fileChanges: {
+                added: newFiles,
+                removed: removedFiles
+            }
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(comparison, null, 2) }]
+        };
+    });
+}

package/dist/tools/loader.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerLoaderTools(server: McpServer): void;