kontext-ai 0.1.0

package/backend_dev_plan.md

@@ -0,0 +1,446 @@
+# KONTEXT Backend Development Plan
+
+## Problem Statement
+
+KONTEXT needs to sync context across AI tools. The core challenge is that different AI tools have different capabilities:
+
+- **MCP-supported tools**: Claude (Anthropic), Cursor/Antigravity - these can use the Model Context Protocol directly
+- **Non-MCP tools**: ChatGPT web, Gemini web, other AI assistants - these need alternative integration methods
+
+The backend must create a unified system that all tools can read from and write to, ensuring context stays consistent and up-to-date across the entire ecosystem.
+
+---
+
+## Solution 1: File-Based Context Storage (Simplest)
+
+**Approach**: Store context as JSON/YAML/Markdown files in a synchronized folder (Dropbox, Google Drive, iCloud, or any folder sync service).
+
+**How it works**:
+- Context files live in a shared directory that's sync'd via cloud storage
+- Each AI tool reads the files directly from the local synced folder
+- Users manually configure each tool to point to the context directory
+
+**Pros**:
+- Extremely simple to implement
+- No server infrastructure needed
+- Works with every tool that can read files
+- Human-readable format (JSON/Markdown)
+
+**Cons**:
+- No real-time sync - tools must re-read files to get updates
+- No automatic notifications to tools when context changes
+- Requires manual configuration per tool
+- File conflicts possible if multiple tools write simultaneously
+
+**Complexity**: Low  
+**Cost**: Very Low (just cloud storage subscription)
+
+---
+
+## Solution 2: MCP Server + REST API Hybrid
+
+**Approach**: Build a local MCP server for MCP-enabled tools, and expose a REST API for non-MCP tools to query context.
+
+**How it works**:
+- MCP server runs locally, exposing context read/write capabilities
+- REST API endpoints allow HTTP-based context queries
+- Non-MCP tools make API calls to fetch/update context
+- Local SQLite database stores context data
+
+**Pros**:
+- Full support for MCP tools
+- REST API works with any HTTP-capable tool
+- Local-only (no cloud infrastructure)
+- Real-time within the local network
+
+**Cons**:
+- Non-MCP tools need to be configured to call the API
+- Requires each tool to support HTTP requests or have a proxy
+- No persistent connections for real-time updates
+
+**Complexity**: Medium  
+**Cost**: Low (local hosting only)
+
+---
+
+## Solution 3: MCP + Browser Extension Injection
+
+**Approach**: Use an MCP server for native tools, and a browser extension to inject context into web AI tools.
+
+**How it works**:
+- MCP server provides context to desktop AI tools
+- Browser extension reads context from local storage/API
+- When user opens ChatGPT/Gemini web, extension populates context via DOM injection or content script
+- Extension can also capture context from web tools and write back
+
+**Pros**:
+- Native feel for web tools - context appears automatically
+- Works with any web-based AI tool
+- Can read from and write to web tool interfaces
+
+**Cons**:
+- Extension must be maintained per browser
+- Some web tools may have CSP restrictions
+- Limited API access - extension can only do what browsers allow
+
+**Complexity**: Medium  
+**Cost**: Low to Medium (browser extension development)
+
+---
+
+## Solution 4: MCP + Userscript Layer (Tampermonkey/Greasemonkey)
+
+**Approach**: Use an MCP server for native tools, and userscripts to inject context into web AI tools.
+
+**How it works**:
+- MCP server provides context to desktop AI tools
+- Userscripts (installed via Tampermonkey) run on web AI tool pages
+- Scripts read context from local file/API and inject into page DOM or form fields
+- Scripts can also scrape context from web pages and write back
+
+**Pros**:
+- Works across browsers with userscript support
+- No official extension store needed
+- Highly flexible - can manipulate DOM directly
+- Open source, community-maintainable
+
+**Cons**:
+- Users must install and configure userscript manager
+- Each web tool needs custom script development
+- Fragile to UI changes in target websites
+
+**Complexity**: Low to Medium  
+**Cost**: Low (userscript development)
+
+---
+
+## Solution 5: MCP + Custom Protocol Handler
+
+**Approach**: Use an MCP server for native tools, and register a custom protocol (kontext://) that non-MCP tools can invoke.
+
+**How it works**:
+- MCP server for desktop AI tools
+- Register `kontext://` custom protocol in operating system
+- Non-MCP tools use protocol handler to query context (e.g., `kontext://read?key=skills`)
+- JavaScript in web pages can use `window.location` to trigger protocol
+- Protocol opens local app that returns context via file or callback
+
+**Pros**:
+- Simple URL-based interface
+- Works with any tool that can open URLs
+- No server required - just local app
+
+**Cons**:
+- Limited to tools that can trigger URLs
+- Web tools can only use protocol in limited ways
+- No persistent connection
+
+**Complexity**: Medium  
+**Cost**: Low
+
+---
+
+## Solution 6: MCP + Command-Line Interface Wrapper
+
+**Approach**: Use an MCP server for native tools, and provide a CLI that non-MCP tools can invoke.
+
+**How it works**:
+- MCP server for desktop AI tools
+- CLI tool (`kontext`) reads/writes context via command line
+- Non-MCP tools invoke CLI process and parse output
+- Supports pipes, environment variables, stdin/stdout
+
+**Pros**:
+- Universal - works with any tool that can run processes
+- Powerful - can combine with shell scripts
+- Works locally, no network needed
+
+**Cons**:
+- Non-MCP web tools can't invoke CLI directly
+- Requires wrapper/broker for web tools
+- Process spawning overhead
+
+**Complexity**: Low  
+**Cost**: Very Low
+
+---
+
+## Solution 7: MCP + Webhook Push System
+
+**Approach**: Use an MCP server for native tools, and implement a webhook/callback system for non-MCP tools to receive context updates.
+
+**How it works**:
+- MCP server for desktop AI tools
+- Local webhook server listens for registrations
+- Non-MCP tools register webhooks (URLs to call when context changes)
+- When context updates, registered webhooks receive POST with new context
+- Tools can also poll REST API as fallback
+
+**Pros**:
+- Event-driven - tools get context immediately on change
+- Supports many simultaneous tools
+- Flexible - tools choose push or pull
+
+**Cons**:
+- Webhooks require public URLs (needs ngrok/port forwarding)
+- Some tools don't support receiving webhooks
+- Setup complexity for non-technical users
+
+**Complexity**: Medium to High  
+**Cost**: Medium (webhook hosting)
+
+---
+
+## Solution 8: MCP + Database + GraphQL API
+
+**Approach**: Build a comprehensive backend with MCP server, database storage, and GraphQL API for all tools.
+
+**How it works**:
+- MCP server connects to desktop AI tools
+- PostgreSQL/SQLite database stores all context
+- GraphQL API exposes full CRUD operations
+- Each tool (MCP or not) connects via GraphQL
+- Subscriptions enable real-time updates
+
+**Pros**:
+- Most flexible and powerful solution
+- Single API for all tool types
+- Real-time subscriptions
+- Type-safe, queryable
+
+**Cons**:
+- Most complex to build and host
+- Non-MCP web tools need GraphQL client
+- Requires backend hosting
+
+**Complexity**: High  
+**Cost**: Medium to High
+
+---
+
+## Solution 9: MQTT/Pub-Sub Real-Time Broker
+
+**Approach**: Use a real-time message broker (MQTT) for all context synchronization.
+
+**How it works**:
+- Mosquito (MQTT broker) runs locally or in cloud
+- MCP server publishes/subscribes to topics
+- Non-MCP tools connect via MQTT or WebSocket
+- Topics: `kontEXT/context/read`, `kontEXT/context/write`, etc.
+- Retained messages ensure new subscribers get current context
+
+**Pros**:
+- True real-time synchronization
+- Works with massive numbers of tools
+- Efficient, lightweight protocol
+- Established standard (MQTT 5.0)
+
+**Cons**:
+- Most tools don't natively speak MQTT
+- Need adapters/bridges for non-MQTT tools
+- broker infrastructure required
+
+**Complexity**: High  
+**Cost**: Medium
+
+---
+
+## Solution 10: Comprehensive Sync Platform (KONTEXT Cloud)
+
+**Approach**: Build a full-featured cloud platform with MCP integration, web dashboard, and universal API.
+
+**How it works**:
+- Cloud-hosted backend (or self-hosted)
+- MCP server as one integration option
+- REST and GraphQL APIs for all tools
+- Webhooks for event-driven updates
+- Browser extension for web AI tools
+- CLI for terminal-based tools
+- Mobile app for mobile access
+- Real-time sync across all devices
+
+**Pros**:
+- Complete solution - every integration covered
+- Cloud sync - works from anywhere
+- Professional grade
+- User dashboard for management
+
+**Cons**:
+- Most complex to build
+- Ongoing hosting costs
+- Maintenance burden
+
+**Complexity**: Very High  
+**Cost**: High
+
+---
+
+## Recommended Hybrid Solution: MCP + Webhook/Browser Extension + Local GraphQL API
+
+Given the requirements, here's the recommended approach:
+
+### Components
+
+1. **MCP Server** - For Claude, Cursor, Antigravity, and any MCP-capable AI tools
+2. **Local GraphQL API** - Acts as the central data layer, storing context in SQLite
+3. **Browser Extension** - Injects context into ChatGPT, Gemini, and other web AI tools
+4. **Webhook Server** - Pushes updates to registered tools in real-time
+
+### Architecture Overview
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  MCP Tools       │     │  Web Tools      │     │  CLI Tools       │
+│  (Claude,        │     │  (ChatGPT,     │     │  (Terminal AI   │
+│   Cursor)        │     │   Gemini)       │     │   Assistants)   │
+└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
+         │                       │                       │
+         ▼                       ▼                       ▼
+┌──────────────────────────────────────────────────────────────┐
+│                      KONTEXT Core                           │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │ MCP Server   │  │ GraphQL API │  │  Webhook Server │  │
+│  └──────────────┘  └──────────────┘  └──────────────────┘  │
+│                          │                                  │
+│                  ┌───────▼───────┐                         │
+│                  │   SQLite DB   │                         │
+│                  └───────────────┘                         │
+└──────────────────────────────────────────────────────────────┘
+         │                       │                       │
+         ▼                       ▼                       ▼
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  Desktop        │     │  Browser        │     │  Extensions     │
+│  Extensions     │     │  Extension      │     │  (VS Code,      │
+│  (native)       │     │  (web tools)    │     │   editors)      │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+### Implementation Steps
+
+#### Step 1: Core Data Layer
+
+**Description**: Build the SQLite database schema and basic read/write operations.
+
+**Components**:
+- SQLite database file (`kontEXT.db`)
+- Tables: `context_files`, `skills`, `preferences`, `tool_configs`, `sync_log`
+- Schema for versioned context with timestamps
+
+**Success Criteria**:
+- Database created and accessible
+- CRUD operations working for all entity types
+- Basic CLI tool can read/write context
+
+#### Step 2: Local GraphQL API Server
+
+**Description**: Create a GraphQL API that exposes all context operations.
+
+**Components**:
+- GraphQL schema (types: ContextFile, Skill, Preference, ToolConfig)
+- Queries: getContext, getSkills, getPreferences
+- Mutations: createContext, updateContext, deleteContext
+- Subscriptions: onContextChange (for real-time updates)
+
+**Success Criteria**:
+- GraphQL server starts without errors
+- All queries and mutations return expected data
+- Subscriptions push updates to subscribers
+
+#### Step 3: MCP Server Implementation
+
+**Description**: Build an MCP server that connects to the GraphQL API.
+
+**Components**:
+- MCP server with context tools (read, write, list, search)
+- Authentication with local API
+- Bidirectional sync between MCP and GraphQL
+
+**Success Criteria**:
+- MCP server registers with Claude/Cursor
+- Context loads correctly in test prompts
+- Updates from MCP reflect in GraphQL API
+
+#### Step 4: Webhook Server
+
+**Description**: Implement a webhook system for event-driven updates.
+
+**Components**:
+- Webhook registration endpoint
+- Event queue for context changes
+- Retry logic for failed deliveries
+- Webhook payload format (JSON with context diff)
+
+**Success Criteria**:
+- Webhooks register successfully
+- Events trigger webhook calls immediately
+- Failed webhooks retry with backoff
+
+#### Step 5: Browser Extension (Chrome/Firefox)
+
+**Description**: Build browser extensions that inject context into web AI tools.
+
+**Components**:
+- Extension manifest and background script
+- Content script for ChatGPT, Gemini web
+- Popup for manual context management
+- API client to connect to local GraphQL
+- Context injection into page/forms
+
+**Success Criteria**:
+- Extension installs without errors
+- Context appears in ChatGPT/Gemini inputs
+- Context persists across page reloads
+- Extension syncs changes back to API
+
+#### Step 6: CLI Tool
+
+**Description**: Create a command-line interface for terminal-based tools.
+
+**Components**:
+- `kontEXT` command with subcommands (read, write, list, sync)
+- Output formatting (JSON, YAML, table)
+- Integration examples for common tools
+
+**Success Criteria**:
+- CLI installs globally
+- All commands work as expected
+- Output parses correctly in scripts
+
+#### Step 7: Sync Engine
+
+**Description**: Implement the synchronization logic that keeps context consistent.
+
+**Components**:
+- Change detection (file watcher)
+- Conflict resolution (last-write-wins, merge, manual)
+- Sync status indicators
+- Notification system
+
+**Success Criteria**:
+- File changes detect within 1 second
+- Conflicts resolve correctly
+- User notified of sync status
+
+---
+
+## Implementation Success Criteria Summary
+
+| Step | Component | Key Success Metric |
+|------|-----------|-------------------|
+| 1 | Core Data Layer | SQLite operations complete |
+| 2 | GraphQL API | All queries/mutations work |
+| 3 | MCP Server | Context loads in Claude/Cursor |
+| 4 | Webhook Server | Events trigger webhooks |
+| 5 | Browser Extension | Context injects in web tools |
+| 6 | CLI Tool | Commands execute correctly |
+| 7 | Sync Engine | Changes sync within 1 second |
+
+---
+
+## Future Considerations (Post-MVP)
+
+- **Cloud sync**: Add optional cloud hosting for cross-device sync
+- **Encryption**: End-to-end encryption for sensitive context
+- **Multi-user**: Support for teams sharing context
+- **Analytics**: Usage patterns and insights
+- **Plugins**: Third-party extension system

package/context/base/instructions.yaml

@@ -0,0 +1,3 @@
+# Default Instructions
+
+You are a helpful AI assistant. Be concise and direct in your responses.

package/context/base/preferences.yaml

@@ -0,0 +1,5 @@
+# Preferences
+
+- Output format: markdown
+- Tone: professional but friendly
+- Code style: follow project conventions

package/context/skills/coding.yaml

@@ -0,0 +1,5 @@
+# Coding Skills
+
+- Expert in TypeScript and JavaScript
+- Familiar with React, Node.js, and modern frameworks
+- Follows clean code principles

package/dist/bin/start.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=start.d.ts.map

package/dist/bin/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../src/bin/start.ts"],"names":[],"mappings":""}

package/dist/bin/start.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+console.log('Starting KONTEXT services...\n');
+const services = [
+    { name: 'GraphQL API', script: 'dist/graphql/server.js' },
+    { name: 'MCP Server', script: 'dist/mcp/server.js' },
+    { name: 'Webhook Server', script: 'dist/webhooks/server.js' },
+    { name: 'Sync Engine', script: 'dist/sync/engine.js' },
+];
+const processes = [];
+for (const service of services) {
+    const child = (0, child_process_1.spawn)('node', [service.script], {
+        cwd: process.cwd(),
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    child.stdout?.on('data', (data) => {
+        console.log(`[${service.name}] ${data.toString().trim()}`);
+    });
+    child.stderr?.on('data', (data) => {
+        console.error(`[${service.name}] ${data.toString().trim()}`);
+    });
+    processes.push(child);
+    console.log(`Started ${service.name}`);
+}
+console.log('\nAll services running!');
+console.log('GraphQL API: http://localhost:4000');
+console.log('Webhook Server: http://localhost:4001');
+process.on('SIGINT', () => {
+    console.log('\nShutting down...');
+    processes.forEach((p) => p.kill());
+    process.exit(0);
+});
+//# sourceMappingURL=start.js.map

package/dist/bin/start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../../src/bin/start.ts"],"names":[],"mappings":";;AAAA,iDAAsC;AAGtC,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;AAE9C,MAAM,QAAQ,GAAG;IACf,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,wBAAwB,EAAE;IACzD,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,oBAAoB,EAAE;IACpD,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,yBAAyB,EAAE;IAC7D,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,qBAAqB,EAAE;CACvD,CAAC;AAEF,MAAM,SAAS,GAA+B,EAAE,CAAC;AAEjD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAA,qBAAK,EAAC,MAAM,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;QAC5C,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;QAClB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;KAClC,CAAC,CAAC;IAEH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QAChC,OAAO,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QAChC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtB,OAAO,CAAC,GAAG,CAAC,WAAW,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AACvC,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;AAClD,OAAO,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;AAErD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;IACxB,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAClC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}