indusagi-coding-agent 0.1.30 → 0.1.32

package/docs/FEATURES.md

@@ -0,0 +1,306 @@
+# New Features in v0.1.31
+
+This document outlines the major features added in indusagi-coding-agent v0.1.31.
+
+## 🎯 Quick Start
+
+- **[MCP Guide](./MCP.md)** - Learn how to use Model Context Protocol for external integrations
+- **[Memory Guide](./MEMORY.md)** - Learn how Memory helps the assistant remember context
+
+## 📦 Feature Summary
+
+### 1. Model Context Protocol (MCP)
+
+Connect your AI assistant to external tools and services.
+
+**What it enables:**
+- 🔧 Access external APIs and tools
+- 📁 Filesystem operations
+- 🐙 GitHub integration
+- 🔍 Web search and scraping
+- 🗄️ Database queries
+- 🌐 Real-time web access
+
+**Quick setup:**
+```bash
+# Create ~/.indusagi/mcp-servers.json
+indusagi
+# Tools are automatically available!
+```
+
+**Examples:**
+```
+User: "Read my README.md"
+# Uses filesystem MCP
+
+User: "Search GitHub for open issues"
+# Uses GitHub MCP
+
+User: "What's the latest Node.js update?"
+# Uses web search MCP
+```
+
+👉 [**Read Full MCP Guide →**](./MCP.md)
+
+---
+
+### 2. Memory System
+
+The assistant now remembers important context across sessions.
+
+**What it enables:**
+- 💾 Persistent conversation history
+- 🧠 Semantic understanding of past decisions
+- 🎯 Context-aware responses
+- ⚡ Faster problem-solving
+- 📚 Project knowledge accumulation
+
+**Automatic setup:**
+Memory works out of the box. Just start using indusagi!
+
+**Examples:**
+```
+Session 1:
+User: "I prefer TypeScript for all projects"
+
+Session 2 (days later):
+User: "Create a new API"
+Assistant: "I'll use TypeScript as you prefer..."
+# Assistant remembers your preference!
+```
+
+👉 [**Read Full Memory Guide →**](./MEMORY.md)
+
+---
+
+## 🚀 Feature Comparison
+
+| Feature | Before v0.1.31 | After v0.1.31 |
+|---------|----------------|---------------|
+| **External Tools** | Limited to built-in tools | Full MCP ecosystem |
+| **GitHub Integration** | Manual instructions | Automatic via MCP |
+| **Web Access** | Web fetch only | Web search, fetch, scraping |
+| **Context Memory** | Session-only | Persistent across sessions |
+| **Semantic Search** | Not available | Full vector-based search |
+| **Database Access** | No direct access | Multiple DB systems supported |
+
+---
+
+## 📋 Configuration Files
+
+### MCP Configuration
+**Location**: `~/.indusagi/mcp-servers.json`
+
+```json
+{
+  "servers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "$HOME"]
+    }
+  }
+}
+```
+
+### Memory Configuration
+**Location**: `~/.indusagi/memory.json`
+
+```json
+{
+  "enabled": true,
+  "storage": "in-memory",
+  "vectorStore": "in-memory",
+  "maxMemoryItems": 1000,
+  "similarityThreshold": 0.7
+}
+```
+
+---
+
+## 🛠️ Common Use Cases
+
+### Use Case 1: Code Review with Context
+
+```
+User: "Review my TypeScript code. Remember, we prefer functional patterns."
+
+Memory: Recalls your functional programming preference
+MCP: Accesses your GitHub to fetch the code
+Result: Context-aware, personalized review
+```
+
+### Use Case 2: Project Management
+
+```
+User: "Update the project status"
+
+Memory: Recalls previous project decisions
+MCP: Accesses GitHub to update issues
+Result: Consistent with past architectural decisions
+```
+
+### Use Case 3: Research with Memory
+
+```
+Session 1: "We're building a real-time chat app"
+Session 2: "What database should we use?"
+
+Memory: Recalls the chat app context
+MCP: Searches for latest solutions
+Result: Recommendations tailored to your use case
+```
+
+---
+
+## 📊 Architecture
+
+### MCP Integration
+```
+indusagi
+  ↓
+MCP Client Pool
+  ├─→ Filesystem Server
+  ├─→ GitHub Server
+  ├─→ Web Search Server
+  └─→ Custom Servers
+```
+
+### Memory Integration
+```
+Conversation
+  ↓
+Memory System
+  ├─→ Store as vector embedding
+  ├─→ Search for relevant context
+  └─→ Inject into conversation
+  ↓
+Enhanced Response
+```
+
+---
+
+## ⚙️ Environment Variables
+
+### MCP
+```bash
+INDUSAGI_DEBUG=1              # Enable MCP debug output
+MCP_CONFIG_PATH=~/.indusagi/  # Custom config location
+```
+
+### Memory
+```bash
+MEMORY_ENABLED=true           # Enable/disable memory
+MEMORY_THRESHOLD=0.7          # Similarity threshold
+OPENAI_API_KEY=sk-...         # For semantic embeddings
+```
+
+---
+
+## 🔗 Integration with Other Features
+
+### GPT-5.4 Models
+v0.1.31 includes full support for GPT-5.4:
+- `gpt-5.4` - Base model
+- `gpt-5.4-codex` - Coding optimized (default for openai-codex)
+
+These work seamlessly with MCP and Memory!
+
+### Clean CLI Output
+MCP debug messages are suppressed by default for a clean terminal experience.
+
+Enable with: `INDUSAGI_DEBUG=1 indusagi`
+
+---
+
+## 🚀 Getting Started
+
+### Step 1: Update to v0.1.31
+```bash
+npm install -g indusagi-coding-agent@0.1.31
+indusagi --version
+# Should show: 0.1.31
+```
+
+### Step 2: Enable MCP (Optional)
+```bash
+# Copy example config
+cp ~/.npm-global/lib/node_modules/indusagi-coding-agent/examples/mcp-servers.example.json ~/.indusagi/mcp-servers.json
+
+# Edit to customize
+nano ~/.indusagi/mcp-servers.json
+```
+
+### Step 3: Set Environment Variables
+```bash
+export GITHUB_TOKEN="your_token"
+export BRAVE_API_KEY="your_key"
+export OPENAI_API_KEY="sk-..."
+```
+
+### Step 4: Start Using!
+```bash
+indusagi
+```
+
+Memory and MCP are ready to use!
+
+---
+
+## 📚 Documentation Index
+
+| Topic | Document |
+|-------|----------|
+| **MCP Setup & Usage** | [MCP.md](./MCP.md) |
+| **Memory System** | [MEMORY.md](./MEMORY.md) |
+| **Installation** | [../README.md](../README.md) |
+| **Troubleshooting** | [../README.md#troubleshooting](../README.md) |
+
+---
+
+## 💡 Tips & Tricks
+
+### MCP Tips
+- Start with filesystem and web search for maximum value
+- Set up GitHub if you work with repos
+- Use environment variables for secrets
+
+### Memory Tips
+- Be explicit about preferences and constraints
+- Reference past decisions to strengthen memory
+- Start sessions with relevant context
+- Search memory with `indusagi --search-memory "query"`
+
+---
+
+## ❓ FAQ
+
+**Q: Is my memory data stored online?**  
+A: No! Memory is stored locally in `~/.indusagi/memory/`. Only OpenAI embeddings API may be called (if enabled).
+
+**Q: Can I use MCP without Memory?**  
+A: Yes! They work independently. Enable only what you need.
+
+**Q: Does Memory slow down indusagi?**  
+A: Minimal impact (<5% overhead). Memory retrieval is <100ms.
+
+**Q: Can I share Memory across machines?**  
+A: Export and import: `indusagi --export-memory` and `indusagi --import-memory file.json`
+
+**Q: How often should I clear Memory?**  
+A: You don't need to! Memory automatically manages old items. Clear only if privacy is a concern.
+
+---
+
+## 🐛 Getting Help
+
+If you encounter issues:
+
+1. **MCP Issues**: See [MCP.md Troubleshooting](./MCP.md#troubleshooting)
+2. **Memory Issues**: See [MEMORY.md Troubleshooting](./MEMORY.md#troubleshooting)
+3. **General Issues**: Check [../README.md](../README.md)
+
+---
+
+**Version**: 0.1.31  
+**Released**: March 2026  
+**Status**: ✅ Production Ready

package/docs/MCP.md

@@ -0,0 +1,341 @@
+# Model Context Protocol (MCP) Guide
+
+## What is MCP?
+
+**Model Context Protocol (MCP)** is a standard that allows AI models to interact with external tools and data sources seamlessly. It enables indusagi to connect with third-party services, databases, and APIs through a unified interface.
+
+In indusagi, MCP provides:
+- **External Tool Integration**: Connect to filesystems, APIs, databases
+- **Automatic Tool Registration**: Servers expose tools that are automatically available
+- **Real-time Data Access**: Query live data from external sources
+- **Environment Configuration**: Secure credential management
+
+## Features Added in v0.1.31
+
+✅ **Multiple MCP Server Support**: Run multiple MCP servers simultaneously  
+✅ **Auto-Tool Registration**: Tools from MCP servers are automatically available  
+✅ **Clean Debug Output**: MCP debug messages suppressed by default (cleaner CLI)  
+✅ **Error Handling**: Improved connection management and error recovery  
+✅ **Configuration Flexibility**: Easy server setup via config file  
+
+## Available MCP Servers
+
+### 1. **Filesystem Server**
+Access and manipulate files on your system
+
+```json
+{
+  "servers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
+    }
+  }
+}
+```
+
+**Use cases:**
+- Read files for context
+- Create and edit files
+- List directory contents
+- Search files
+
+### 2. **GitHub Server**
+Interact with GitHub repositories and issues
+
+```json
+{
+  "github": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-github"],
+    "env": {
+      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+    }
+  }
+}
+```
+
+**Use cases:**
+- Search repositories
+- Read issues and pull requests
+- Create issues
+- Push commits
+
+### 3. **Database Servers**
+
+#### PostgreSQL
+```json
+{
+  "postgres": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-postgres"],
+    "env": {
+      "DATABASE_URL": "postgresql://user:password@localhost:5432/dbname"
+    }
+  }
+}
+```
+
+### 4. **Web Search Server**
+
+#### Brave Search
+```json
+{
+  "brave-search": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+    "env": {
+      "BRAVE_API_KEY": "${BRAVE_API_KEY}"
+    }
+  }
+}
+```
+
+**Use cases:**
+- Search the web in real-time
+- Get current news and information
+- Fact-check information
+
+### 5. **Browser Automation**
+
+#### Puppeteer (Headless Browser)
+```json
+{
+  "puppeteer": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
+  }
+}
+```
+
+**Use cases:**
+- Screenshot websites
+- Fill forms
+- Scrape web content
+- Test web applications
+
+### 6. **Git Server**
+Version control operations
+
+```json
+{
+  "git": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "/path/to/git/repo"]
+  }
+}
+```
+
+### 7. **Fetch Server**
+HTTP/HTTPS requests
+
+```json
+{
+  "fetch": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-fetch"]
+  }
+}
+```
+
+## Setup Guide
+
+### Step 1: Create Configuration File
+
+Create `~/.indusagi/mcp-servers.json`:
+
+```json
+{
+  "servers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "$HOME"],
+      "env": {}
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### Step 2: Set Environment Variables
+
+```bash
+# For GitHub
+export GITHUB_TOKEN="your_github_token_here"
+
+# For Brave Search
+export BRAVE_API_KEY="your_brave_api_key_here"
+```
+
+### Step 3: Start indusagi
+
+```bash
+indusagi
+```
+
+MCP servers will automatically load and tools will be available.
+
+## Usage Examples
+
+### Example 1: File Operations
+
+```
+User: Read the README.md file
+Assistant: [Uses filesystem MCP to read file]
+```
+
+### Example 2: GitHub Integration
+
+```
+User: Search for open issues in my repository related to "bug"
+Assistant: [Uses GitHub MCP to search issues]
+```
+
+### Example 3: Web Search
+
+```
+User: Search for latest Node.js updates
+Assistant: [Uses Brave Search MCP for real-time web search]
+```
+
+### Example 4: Browser Automation
+
+```
+User: Take a screenshot of https://example.com
+Assistant: [Uses Puppeteer MCP to capture screenshot]
+```
+
+## Troubleshooting
+
+### MCP Server Won't Connect
+
+**Error**: `Failed to connect to [server-name]`
+
+**Solution**:
+1. Check if the command exists: `npx @modelcontextprotocol/server-[name]`
+2. Verify environment variables are set correctly
+3. Check that the command path is accessible
+4. Enable debug mode: `INDUSAGI_DEBUG=1 indusagi`
+
+### Tools Not Appearing
+
+**Problem**: MCP server connected but tools not available
+
+**Solution**:
+1. Check server status: Look for `Connected to [server]` messages
+2. Verify server configuration in `mcp-servers.json`
+3. Reload indusagi (restart the application)
+4. Check tool registry: `indusagi --help | grep -i tools`
+
+### Authentication Issues
+
+**Error**: `GITHUB_TOKEN not found` or similar
+
+**Solution**:
+1. Verify environment variable is set: `echo $GITHUB_TOKEN`
+2. For `.env` file support, place in `~/.indusagi/.env`
+3. Use environment variable syntax: `"${VARIABLE_NAME}"`
+
+### Enable Debug Output
+
+```bash
+# Enable MCP debug messages
+INDUSAGI_DEBUG=1 indusagi
+```
+
+## Best Practices
+
+### 1. **Security**
+- Never commit API tokens to git
+- Use environment variables for secrets
+- Restrict filesystem access to necessary directories only
+
+```json
+{
+  "filesystem": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-filesystem", "$HOME/projects"],
+    "env": {}
+  }
+}
+```
+
+### 2. **Performance**
+- Only enable servers you actually use
+- Some servers (Puppeteer) consume significant resources
+- Monitor memory usage with many servers
+
+### 3. **Error Handling**
+- MCP failures don't crash indusagi
+- If a server is unavailable, its tools won't be available
+- Check console messages for connection status
+
+### 4. **Tool Awareness**
+When requesting tasks, tell the assistant which tools are available:
+
+```
+I have these MCP tools available:
+- Filesystem (read, write, list files)
+- GitHub (search repos, issues)
+- Web Search (real-time search)
+
+Task: Find recent Python security CVEs
+```
+
+## Advanced Configuration
+
+### Multiple Instances of Same Server
+
+```json
+{
+  "servers": {
+    "filesystem-home": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "$HOME"]
+    },
+    "filesystem-projects": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "$HOME/projects"]
+    }
+  }
+}
+```
+
+### Custom Environment Variables
+
+```json
+{
+  "postgres-production": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-postgres"],
+    "env": {
+      "DATABASE_URL": "postgresql://prod-user:${PROD_DB_PASSWORD}@prod.example.com:5432/main"
+    }
+  }
+}
+```
+
+## Reference
+
+- **MCP Specification**: https://modelcontextprotocol.io
+- **Available Servers**: https://github.com/modelcontextprotocol/servers
+- **Create Custom Server**: https://modelcontextprotocol.io/docs/tools/server
+
+## Support
+
+For issues with MCP:
+1. Check if `mcp-servers.json` exists in `~/.indusagi/`
+2. Run with debug: `INDUSAGI_DEBUG=1 indusagi`
+3. Check console output for connection messages
+4. Verify environment variables: `printenv | grep -i TOKEN`
+
+---
+
+**Version**: Introduced in indusagi-coding-agent v0.1.31  
+**Last Updated**: March 2026