ideconnect 1.0.0

package/README.md

@@ -0,0 +1,272 @@
+# IDEConnect
+
+A free, self-hosted Model Context Protocol (MCP) server that provides shared, persistent project context across multiple AI IDEs.
+
+## What Is IDEConnect?
+
+IDEConnect creates a "shared project brain" so that all IDEs and AI agents understand the same project scope, architecture, constraints, and decisions **without relying on chat history**.
+
+**Key Concept: Project Context vs Chat History**
+
+IDEConnect provides project context (what your project is), not chat history (what you've discussed). Each IDE maintains separate conversations, but all IDEs understand your project the same way.
+
+Example: You chat in Cursor about authentication → Chat stays in Cursor. You open Kiro → Kiro understands your project architecture (from IDEConnect) but does NOT see your Cursor chat.
+
+## What IDEConnect Offers
+
+**1. Consistent Project Understanding**
+
+All your AI IDEs (Cursor, Kiro, Antigravity, Claude Desktop) understand:
+- Project Overview - Purpose, scope, goals, stakeholders
+- Architecture - System design, components, data flow, patterns
+- Constraints - Technical limits, business rules, resource constraints
+- Decisions - Architectural decisions with rationale
+- Roadmap - Future plans and milestones
+
+**2. Zero Manual Configuration**
+
+One command sets up everything - auto-detects IDEs, configures them automatically, creates templates, and generates file injection.
+
+**3. File-Based Storage**
+
+Deterministic, version-controlled, human-readable markdown files. No database needed - simple, reliable, portable.
+
+**4. IDE-Agnostic**
+
+Works with Cursor (native MCP), Claude Desktop (native MCP), Kiro (file injection), Antigravity (CLI adapter), and any IDE via adapters.
+
+**5. Free & Self-Hosted**
+
+No external services, no paid APIs, no cloud dependencies - 100% local and private.
+
+## Installation
+
+**Prerequisites:** Node.js 18 or higher, npm or yarn
+
+**Quick Install - One command does everything:**
+
+```bash
+npm run install
+```
+
+This automatically:
+1. Checks Node.js version
+2. Installs all dependencies
+3. Creates `.ideconnect/` directory
+4. Initializes context file templates
+5. Auto-detects and configures your IDEs
+6. Generates file injection for non-MCP IDEs
+
+**After Installation:**
+
+1. Edit context files in `.ideconnect/` to document your project:
+   - `overview.md` - Project purpose, scope, goals
+   - `architecture.md` - System design, components
+   - `constraints.md` - Technical and business limits
+   - `decisions.md` - Architectural decisions
+   - `roadmap.md` - Future plans (optional)
+
+2. Restart your IDE to load IDEConnect
+
+3. Start using context-aware AI assistance!
+
+**Manual Installation (If Needed):**
+
+If automated setup doesn't work:
+
+```bash
+# 1. Install dependencies
+cd server
+npm install
+
+# 2. Initialize context
+cd ..
+node scripts/init.js
+
+# 3. Configure IDE manually (see IDE Configuration below)
+```
+
+## IDE Configuration
+
+The setup script automatically configures Cursor and Claude Desktop. If automatic configuration fails, manually add to your IDE's config:
+
+**Cursor** - Edit `~/.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "ideconnect": {
+      "command": "node",
+      "args": ["/absolute/path/to/ideconnect/server/index.js"]
+    }
+  }
+}
+```
+
+**Claude Desktop** - Edit your platform's config file:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "ideconnect": {
+      "command": "node",
+      "args": ["/absolute/path/to/ideconnect/server/index.js"]
+    }
+  }
+}
+```
+
+**Non-MCP IDEs (Kiro, Antigravity, etc.)**
+
+Option 1: File Injection - IDEConnect generates `.ideconnect-context.json` automatically. Your IDE can read this file.
+
+Option 2: CLI Adapter:
+```bash
+node adapters/cli/ideconnect-cli.js get-overview
+```
+
+## How It Works
+
+**Architecture:** AI IDEs → MCP Protocol → IDEConnect Server → .ideconnect/ Files
+
+1. IDE starts and calls MCP tools
+2. IDEConnect Server reads markdown files from `.ideconnect/`
+3. Returns structured JSON with project context
+4. AI uses context for all responses
+
+**Context Files:** IDEConnect reads from `.ideconnect/` directory:
+- `overview.md` - Project overview
+- `architecture.md` - System architecture
+- `constraints.md` - Project constraints
+- `decisions.md` - Architectural decisions
+- `roadmap.md` - Roadmap (optional)
+
+**Available MCP Tools:**
+- `get_project_context` - Get complete project context
+- `get_overview` - Get project overview
+- `get_architecture` - Get architecture documentation
+- `get_constraints` - Get project constraints
+- `get_decisions` - Get recorded decisions
+- `get_roadmap` - Get roadmap (optional)
+
+## Common Issues & Troubleshooting
+
+**Setup Fails** - `npm run install` fails
+- Check Node.js version: `node --version` (must be 18+)
+- Ensure write permissions in project directory
+- Try running with administrator/sudo if needed
+- Check if `.ideconnect/` directory already exists (delete and retry)
+
+**IDE Not Detected** - Setup says "No IDEs detected"
+- This is okay - setup will still attempt to configure common IDEs
+- Manually configure your IDE (see IDE Configuration above)
+- Verify IDE config file location exists
+
+**IDE Not Connecting** - IDE doesn't connect to IDEConnect
+- Verify MCP server path in IDE config matches actual location (use absolute path)
+- Check server dependencies: `cd server && npm install`
+- Test server manually: `node server/index.js` (should start without errors)
+- Restart IDE after configuration changes
+- Check IDE logs for connection errors
+
+**Context Files Not Found** - MCP tools return "file not found"
+- Verify `.ideconnect/` directory exists: `ls .ideconnect`
+- Re-initialize context: `node scripts/init.js`
+- Check you're in project root when running commands
+- Verify file permissions - ensure files are readable
+
+**Server Won't Start** - MCP server crashes or won't start
+- Verify dependencies installed: `cd server && npm install`
+- Check Node.js version: `node --version` (must be 18+)
+- Test server directly: `node server/index.js` (look for error messages)
+- Check file paths in server code match your system
+
+**IDE Shows Old Context** - Changes to context files not reflected
+- No restart needed - changes are immediate
+- Verify file was saved correctly
+- Check file encoding - should be UTF-8
+- Restart IDE if still not working
+
+**File Injection Not Working** - `.ideconnect-context.json` not generated
+- Run manually: `node adapters/file-inject/inject.js`
+- Check `.ideconnect/` directory exists
+- Verify write permissions in project directory
+
+**Multiple Projects** - How to use IDEConnect with multiple projects?
+- Each project has its own `.ideconnect/` directory
+- IDEConnect searches up directory tree to find context
+- Works automatically - no configuration needed per project
+
+**Team Collaboration** - How to share context with team?
+- Commit `.ideconnect/` to git (recommended)
+- Team members pull updates
+- Context files are version controlled
+- No sync needed - file-based, deterministic
+
+**Privacy Concerns** - Worried about storing project context
+- All local - no external services
+- File-based - you control everything
+- Version control - use `.gitignore` if needed
+- No chat history - only project context stored
+
+## Verification
+
+Check that everything is working:
+
+```bash
+npm run verify
+```
+
+This checks:
+- ✅ Context files exist
+- ✅ IDE configurations are correct
+- ✅ MCP server is ready
+- ✅ File injection is valid
+
+## Project Structure
+
+```
+ideconnect/
+├── server/              # MCP server implementation
+│   ├── index.js         # Main server
+│   ├── tools/           # Context tools
+│   └── package.json     # Dependencies
+├── .ideconnect/          # Context storage (created by setup)
+│   ├── overview.md
+│   ├── architecture.md
+│   ├── constraints.md
+│   ├── decisions.md
+│   └── roadmap.md
+├── adapters/             # IDE adapters
+│   ├── cli/             # CLI wrapper
+│   └── file-inject/     # File injection
+├── scripts/              # Setup scripts
+│   ├── setup.js         # Automated setup
+│   ├── init.js          # Initialize context
+│   └── verify.js        # Verification
+└── README.md            # This file
+```
+
+## Requirements
+
+- **Node.js**: 18 or higher
+- **npm**: Any recent version
+- **Operating System**: Windows, macOS, or Linux
+
+## License
+
+MIT
+
+## Contributing
+
+This is a self-hosted tool. Fork, modify, and use as needed for your projects.
+
+## Support
+
+For issues:
+1. Check "Common Issues" section above
+2. Verify installation with `npm run verify`
+3. Check IDE logs for error messages
+4. Ensure Node.js 18+ is installed

package/adapters/cli/ideconnect-cli.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+import { spawn } from 'child_process';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * CLI wrapper for IDEConnect
+ * Allows IDEs without native MCP support to query context via command line
+ */
+
+const commands = {
+  'get-project-context': 'get_project_context',
+  'get-overview': 'get_overview',
+  'get-architecture': 'get_architecture',
+  'get-constraints': 'get_constraints',
+  'get-decisions': 'get_decisions',
+  'get-roadmap': 'get_roadmap',
+};
+
+async function callMCPTool(toolName) {
+  return new Promise((resolve, reject) => {
+    const serverPath = join(__dirname, '../../server/index.js');
+    const nodeProcess = spawn('node', [serverPath], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    // Construct MCP request
+    const request = {
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'tools/call',
+      params: {
+        name: toolName,
+        arguments: {},
+      },
+    };
+
+    let output = '';
+    let errorOutput = '';
+
+    nodeProcess.stdout.on('data', (data) => {
+      output += data.toString();
+    });
+
+    nodeProcess.stderr.on('data', (data) => {
+      errorOutput += data.toString();
+    });
+
+    nodeProcess.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(`MCP server exited with code ${code}: ${errorOutput}`));
+        return;
+      }
+
+      try {
+        const lines = output.trim().split('\n');
+        const responseLine = lines.find((line) => {
+          try {
+            const parsed = JSON.parse(line);
+            return parsed.id === 1;
+          } catch {
+            return false;
+          }
+        });
+
+        if (responseLine) {
+          const response = JSON.parse(responseLine);
+          if (response.error) {
+            reject(new Error(response.error.message || 'MCP error'));
+          } else {
+            resolve(response.result);
+          }
+        } else {
+          reject(new Error('No valid response from MCP server'));
+        }
+      } catch (error) {
+        reject(new Error(`Failed to parse response: ${error.message}`));
+      }
+    });
+
+    // Send request
+    const requestStr = JSON.stringify(request) + '\n';
+    nodeProcess.stdin.write(requestStr);
+    nodeProcess.stdin.end();
+  });
+}
+
+// CLI interface
+const command = process.argv[2];
+
+if (!command || !commands[command]) {
+  console.error('Usage: ideconnect-cli <command>');
+  console.error('\nAvailable commands:');
+  Object.keys(commands).forEach((cmd) => {
+    console.error(`  ${cmd}`);
+  });
+  process.exit(1);
+}
+
+const toolName = commands[command];
+
+callMCPTool(toolName)
+  .then((result) => {
+    console.log(JSON.stringify(result, null, 2));
+  })
+  .catch((error) => {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  });
+

package/adapters/file-inject/inject.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+
+/**
+ * File-based context injection for IDEs without MCP support
+ * Generates a single JSON file that IDEs can read directly
+ */
+
+async function injectContext() {
+  const contextDir = '.ideconnect';
+  const outputFile = '.ideconnect-context.json';
+
+  if (!existsSync(contextDir)) {
+    console.error(`Error: ${contextDir} directory not found. Run "ideconnect init" first.`);
+    process.exit(1);
+  }
+
+  const files = {
+    overview: 'overview.md',
+    architecture: 'architecture.md',
+    constraints: 'constraints.md',
+    decisions: 'decisions.md',
+    roadmap: 'roadmap.md',
+  };
+
+  const context = {
+    timestamp: new Date().toISOString(),
+    sources: {},
+  };
+
+  for (const [key, filename] of Object.entries(files)) {
+    const filePath = join(contextDir, filename);
+    try {
+      if (existsSync(filePath)) {
+        const content = await readFile(filePath, 'utf-8');
+        context.sources[key] = content.trim();
+      } else {
+        context.sources[key] = null;
+      }
+    } catch (error) {
+      console.error(`Warning: Failed to read ${filename}: ${error.message}`);
+      context.sources[key] = null;
+    }
+  }
+
+  await writeFile(outputFile, JSON.stringify(context, null, 2), 'utf-8');
+  console.log(`✓ Generated ${outputFile}`);
+  console.log('  IDEs can read this file to get project context');
+}
+
+injectContext().catch((error) => {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+});
+

package/examples/example-context/architecture.md

@@ -0,0 +1,60 @@
+# Architecture
+
+## System Design
+
+Three-tier architecture:
+- **Frontend**: React SPA with TypeScript
+- **Backend**: Node.js/Express REST API
+- **Database**: PostgreSQL for persistence, Redis for caching
+
+## Components
+
+### Frontend
+- React 18 with hooks
+- React Router for navigation
+- Zustand for state management
+- Tailwind CSS for styling
+
+### Backend
+- Express.js REST API
+- JWT authentication
+- PostgreSQL with Prisma ORM
+- Redis for session management
+
+### Infrastructure
+- Docker containers
+- Nginx reverse proxy
+- AWS S3 for file storage
+
+## Data Flow
+
+1. User action in React app
+2. API call to Express backend
+3. Authentication middleware validates JWT
+4. Business logic processes request
+5. Prisma queries PostgreSQL
+6. Response sent back to frontend
+7. React updates UI state
+
+## Patterns & Conventions
+
+- RESTful API design
+- Component-based frontend architecture
+- Repository pattern for data access
+- Dependency injection for testability
+- Error handling with try-catch and middleware
+
+## Technology Stack
+
+- **Frontend**: React, TypeScript, Tailwind CSS
+- **Backend**: Node.js, Express, TypeScript
+- **Database**: PostgreSQL 15
+- **Cache**: Redis 7
+- **Deployment**: Docker, AWS
+
+## Dependencies
+
+- React ecosystem: react, react-dom, react-router
+- Backend: express, prisma, jsonwebtoken
+- Utilities: zod (validation), date-fns (dates)
+

package/examples/example-context/constraints.md

@@ -0,0 +1,38 @@
+# Constraints
+
+## Technical Constraints
+
+- **Performance**: API response time < 200ms (p95)
+- **Scalability**: Support 10,000 concurrent users
+- **Browser Support**: Modern browsers only (Chrome, Firefox, Safari, Edge latest 2 versions)
+- **Database**: PostgreSQL 15+ required
+- **Node.js**: Version 18+ required
+
+## Business Constraints
+
+- **Budget**: No paid third-party services (use free tiers only)
+- **Timeline**: MVP must launch within 3 months
+- **Compliance**: GDPR compliance required for EU users
+- **Data Retention**: User data retained for 2 years after account deletion
+
+## Resource Constraints
+
+- **Team Size**: 3 developers, 1 designer
+- **Infrastructure**: Self-hosted or free cloud tiers only
+- **Time**: 40 hours/week per developer
+- **Expertise**: Team familiar with React/Node.js, learning Prisma
+
+## Design Constraints
+
+- **Responsive**: Must work on desktop and tablet (mobile optional)
+- **Accessibility**: WCAG 2.1 AA compliance
+- **Browser Storage**: Use localStorage (no IndexedDB requirement)
+- **API**: REST only (no GraphQL)
+
+## Operational Constraints
+
+- **Deployment**: Manual deployment process (CI/CD future phase)
+- **Monitoring**: Basic logging only (no APM tools)
+- **Backup**: Daily database backups required
+- **Uptime**: Target 99% uptime (no SLA)
+

package/examples/example-context/decisions.md

@@ -0,0 +1,76 @@
+# Architectural Decisions
+
+## Decision Log
+
+### 2024-01-15 - Use Prisma ORM Instead of Raw SQL
+
+**Context**: Need to choose database access layer for PostgreSQL.
+
+**Decision**: Use Prisma ORM for type-safe database queries and migrations.
+
+**Rationale**: 
+- Type safety reduces runtime errors
+- Migration system simplifies schema changes
+- Good developer experience with auto-completion
+- Team familiar with similar ORMs
+
+**Alternatives Considered**: 
+- Raw SQL with pg library (more control, less safety)
+- TypeORM (more complex, larger ecosystem)
+- Drizzle (newer, less mature)
+
+**Consequences**: 
+- Positive: Faster development, fewer bugs
+- Negative: Learning curve for Prisma-specific features
+- Risk: Vendor lock-in to Prisma (mitigated by standard SQL)
+
+---
+
+### 2024-01-10 - Choose Zustand Over Redux for State Management
+
+**Context**: Frontend state management solution needed.
+
+**Decision**: Use Zustand for global state management.
+
+**Rationale**:
+- Simpler API than Redux
+- Less boilerplate code
+- Good TypeScript support
+- Small bundle size
+
+**Alternatives Considered**:
+- Redux Toolkit (more features, more complexity)
+- Context API (built-in, but performance concerns)
+- Jotai (atomic state, but team unfamiliar)
+
+**Consequences**:
+- Positive: Faster development, easier onboarding
+- Negative: Less ecosystem than Redux
+- Risk: May need to migrate if requirements grow (low probability)
+
+---
+
+### 2024-01-05 - Self-Hosted Over SaaS for Core Infrastructure
+
+**Context**: Choose hosting and infrastructure approach.
+
+**Decision**: Self-host on VPS with Docker, avoid managed services for core features.
+
+**Rationale**:
+- Cost control (no per-user pricing)
+- Full control over data and infrastructure
+- Learning opportunity for team
+- No vendor lock-in
+
+**Alternatives Considered**:
+- AWS managed services (easier, but costly at scale)
+- Heroku (simple, but expensive)
+- Vercel/Netlify (great for frontend, limited for backend)
+
+**Consequences**:
+- Positive: Lower costs, more control
+- Negative: More operational overhead
+- Risk: Scaling challenges (mitigated by Docker and load balancing)
+
+---
+

package/examples/example-context/overview.md

@@ -0,0 +1,39 @@
+# Project Overview
+
+## Purpose
+
+Example web application for managing tasks and projects. Demonstrates modern full-stack development practices.
+
+## Scope
+
+**Included:**
+- User authentication and authorization
+- Task creation, editing, and deletion
+- Project organization
+- Real-time collaboration features
+
+**Excluded:**
+- Mobile native apps (web-only)
+- Third-party integrations (future phase)
+- Advanced analytics (future phase)
+
+## Goals
+
+1. Provide intuitive task management interface
+2. Support team collaboration
+3. Ensure data security and privacy
+4. Maintain high performance with 1000+ concurrent users
+
+## Key Stakeholders
+
+- Product Team: Feature requirements and prioritization
+- Engineering Team: Implementation and architecture
+- Design Team: UI/UX design and user research
+
+## Current Status
+
+- Phase 1: Core functionality (in progress)
+- Authentication: Complete
+- Task management: 80% complete
+- Collaboration: Not started
+

package/examples/example-context/roadmap.md

@@ -0,0 +1,47 @@
+# Roadmap
+
+## Current Phase
+
+**Phase 1: MVP Core Features** (Jan - Mar 2024)
+- User authentication ✅
+- Task CRUD operations (in progress)
+- Basic project organization
+- Simple UI/UX
+
+## Upcoming Milestones
+
+**Q2 2024: Collaboration**
+- Real-time task updates
+- Team workspaces
+- User mentions and notifications
+
+**Q3 2024: Advanced Features**
+- Task templates
+- Recurring tasks
+- Advanced filtering and search
+- Mobile responsive design
+
+**Q4 2024: Integrations**
+- Calendar sync
+- Email notifications
+- Third-party app integrations
+
+## Future Considerations
+
+- Mobile native apps (React Native)
+- Advanced analytics and reporting
+- AI-powered task suggestions
+- Offline support with sync
+- Multi-language support
+
+## Known Work Items
+
+- [ ] Implement task drag-and-drop
+- [ ] Add task due date reminders
+- [ ] Create project templates
+- [ ] Build admin dashboard
+- [ ] Set up CI/CD pipeline
+- [ ] Add comprehensive error logging
+- [ ] Write API documentation
+- [ ] Performance optimization for large task lists
+