memory-journal-mcp 4.3.1 → 4.4.0

package/SECURITY.md

@@ -1,158 +1,225 @@
-# 🔒 Security Guide
-
-The Memory Journal MCP server implements comprehensive security measures to protect your personal journal data.
-
-## 🛡️ **Database Security**
-
-### **WAL Mode Enabled**
-
-- ✅ **Write-Ahead Logging (WAL)** enabled for better concurrency and crash recovery
-- ✅ **Atomic transactions** ensure data consistency
-- ✅ **Better performance** with concurrent read/write operations
-
-### **Optimized PRAGMA Settings**
-
-```sql
-PRAGMA foreign_keys = ON          -- Enforce referential integrity
-PRAGMA journal_mode = WAL         -- Enable WAL mode
-PRAGMA synchronous = NORMAL       -- Balance safety and performance
-PRAGMA cache_size = -64000        -- 64MB cache for better performance
-PRAGMA mmap_size = 268435456      -- 256MB memory-mapped I/O
-PRAGMA temp_store = MEMORY        -- Store temp tables in memory
-PRAGMA busy_timeout = 30000       -- 30-second timeout for busy database
-```
-
-### **File Permissions**
-
-- ✅ **Database files**: `600` (read/write for owner only)
-- ✅ **Data directory**: `700` (full access for owner only)
-- ✅ **Automatic permission setting** on database creation
-
-## 🔐 **Input Validation**
-
-### **Content Limits**
-
-- **Journal entries**: 50,000 characters maximum
-- **Tags**: 100 characters maximum
-- **Entry types**: 50 characters maximum
-- **Significance types**: 50 characters maximum
-
-### **Character Filtering**
-
-Dangerous characters are blocked in tags:
-
-- `<` `>` `"` `'` `&` `\x00`
-
-### **SQL Injection Prevention**
-
-- ✅ **Parameterized queries** used throughout
-- ✅ **Input validation** before database operations
-- ✅ **Warning system** for potentially dangerous content patterns
-
-## 🐳 **Docker Security**
-
-### **Non-Root User**
-
-- ✅ **Dedicated user**: `appuser` with minimal privileges
-- ✅ **No shell access**: `/bin/false` shell for security
-- ✅ **Restricted home directory**: `/app/user`
-
-### **File System Security**
-
-- ✅ **Minimal base image**: `python:3.11-slim`
-- ✅ **Restricted data directory**: `700` permissions
-- ✅ **Volume mounting**: Data persists outside container
-
-### **Container Isolation**
-
-- ✅ **Process isolation** from host system
-- ✅ **Network isolation** (no external network access needed)
-- ✅ **Resource limits** can be applied via Docker
-
-## 🔍 **Data Privacy**
-
-### **Local-First Architecture**
-
-- ✅ **No external services**: All processing happens locally
-- ✅ **No telemetry**: No data sent to external servers
-- ✅ **Full data ownership**: SQLite database stays on your machine
-
-### **Context Bundle Security**
-
-- ✅ **Git context**: Only reads local repository information
-- ✅ **No sensitive data**: Doesn't access private keys or credentials
-- ✅ **Optional GitHub integration**: Only if explicitly configured
-
-## 🚨 **Security Best Practices**
-
-### **For Users**
-
-1. **Keep Docker updated**: Regularly update Docker and base images
-2. **Secure host system**: Ensure your host machine is secure
-3. **Regular backups**: Back up your `data/` directory
-4. **Monitor logs**: Check container logs for any unusual activity
-5. **Limit access**: Don't expose the container to external networks
-
-### **For Developers**
-
-1. **Regular updates**: Keep Python and dependencies updated
-2. **Security scanning**: Regularly scan Docker images for vulnerabilities
-3. **Code review**: All database operations use parameterized queries
-4. **Input validation**: All user inputs are validated before processing
-
-## 🔧 **Security Configuration**
-
-### **Environment Variables**
-
-```bash
-# Database location (should be on secure volume)
-DB_PATH=/app/data/memory_journal.db
-
-# Python path for module resolution
-PYTHONPATH=/app
-```
-
-### **Volume Mounting Security**
-
-```bash
-# Secure volume mounting
-docker run -v ./data:/app/data:rw,noexec,nosuid,nodev memory-journal-mcp
-```
-
-### **Resource Limits**
-
-```bash
-# Apply resource limits
-docker run --memory=1g --cpus=1 memory-journal-mcp
-```
-
-## 📋 **Security Checklist**
-
-- [x] WAL mode enabled for database consistency
-- [x] Proper file permissions (600/700)
-- [x] Input validation and length limits
-- [x] Parameterized SQL queries
-- [x] Non-root Docker user
-- [x] Minimal container attack surface
-- [x] Local-first data architecture
-- [x] No external network dependencies
-- [x] Comprehensive error handling
-- [x] Security documentation
-
-## 🚨 **Reporting Security Issues**
-
-If you discover a security vulnerability, please:
-
-1. **Do not** open a public GitHub issue
-2. **Contact** the maintainers privately
-3. **Provide** detailed information about the vulnerability
-4. **Allow** time for the issue to be addressed before public disclosure
-
-## 🔄 **Security Updates**
-
-- **Database maintenance**: Run `ANALYZE` and `PRAGMA optimize` regularly
-- **Container updates**: Rebuild Docker images when base images are updated
-- **Dependency updates**: Keep Python packages updated
-- **Security patches**: Apply host system security updates
-
-The Memory Journal MCP server is designed with **security-first principles** to protect your personal journal data while maintaining excellent performance and usability.
+# 🔒 Security Guide
+
+The Memory Journal MCP server implements comprehensive security measures to protect your personal journal data.
+
+## 🛡️ **Database Security**
+
+### **WAL Mode Enabled**
+
+- ✅ **Write-Ahead Logging (WAL)** enabled for better concurrency and crash recovery
+- ✅ **Atomic transactions** ensure data consistency
+- ✅ **Better performance** with concurrent read/write operations
+
+### **Optimized PRAGMA Settings**
+
+```sql
+PRAGMA foreign_keys = ON          -- Enforce referential integrity
+PRAGMA journal_mode = WAL         -- Enable WAL mode
+PRAGMA synchronous = NORMAL       -- Balance safety and performance
+PRAGMA cache_size = -64000        -- 64MB cache for better performance
+PRAGMA mmap_size = 268435456      -- 256MB memory-mapped I/O
+PRAGMA temp_store = MEMORY        -- Store temp tables in memory
+PRAGMA busy_timeout = 30000       -- 30-second timeout for busy database
+```
+
+### **File Permissions**
+
+- ✅ **Database files**: `600` (read/write for owner only)
+- ✅ **Data directory**: `700` (full access for owner only)
+- ✅ **Automatic permission setting** on database creation
+
+## 🔐 **Input Validation**
+
+### **Content Limits**
+
+- **Journal entries**: 50,000 characters maximum
+- **Tags**: 100 characters maximum
+- **Entry types**: 50 characters maximum
+- **Significance types**: 50 characters maximum
+- **HTTP request body**: 1MB maximum (prevents memory exhaustion)
+
+### **Character Filtering**
+
+Dangerous characters are blocked in tags:
+
+- `<` `>` `"` `'` `&` `\x00`
+
+### **SQL Injection Prevention**
+
+- ✅ **Parameterized queries** used throughout
+- ✅ **Input validation** via Zod schemas before database operations
+- ✅ **Warning system** for potentially dangerous content patterns
+- ✅ **LIKE pattern sanitization** (escapes `%`, `_`, `\` wildcards)
+- ✅ **Date format whitelisting** (prevents strftime injection)
+
+### **Path Traversal Protection**
+
+- ✅ **Backup filenames validated** - rejects `/`, `\`, `..` in paths
+- ✅ **Typed security errors** with consistent error codes
+
+## 🌐 **HTTP Transport Security**
+
+When running in HTTP mode (`--transport http`), the following security measures apply:
+
+### **CORS Configuration**
+
+- ✅ **Configurable origin** via `--cors-origin` flag or `MCP_CORS_ORIGIN` environment variable
+- ⚠️ **Default: `*`** (allow all origins) for backward compatibility
+- 🔒 **Recommended**: Set a specific origin for production deployments
+
+```bash
+# Restrict CORS to specific origin
+memory-journal-mcp --transport http --cors-origin "http://localhost:3000"
+
+# Or via environment variable
+export MCP_CORS_ORIGIN="http://localhost:3000"
+```
+
+### **Security Headers**
+
+- ✅ **X-Content-Type-Options: nosniff** - prevents MIME sniffing
+- ✅ **X-Frame-Options: DENY** - prevents clickjacking
+
+### **Session Management (Stateful Mode)**
+
+- ✅ **UUID-based session IDs** (cryptographically random)
+- ✅ **30-minute session timeout** - idle sessions automatically expired
+- ✅ **5-minute sweep interval** - periodic cleanup of abandoned sessions
+- ✅ **Explicit session termination** via `DELETE /mcp`
+
+### **Request Size Limits**
+
+- ✅ **1MB body limit** on JSON requests (prevents memory exhaustion DoS)
+
+## 🐙 **GitHub Token Security**
+
+### **Token Handling**
+
+- ✅ **Environment variables only** - tokens never stored in config files
+- ✅ **Error message scrubbing** - Authorization headers stripped from error logs
+- ✅ **Optional integration** - server works fully offline without GitHub token
+- ✅ **Minimal scopes** - only requires `repo`, `project`, `read:org`
+
+### **Environment Variables**
+
+```bash
+# Required for GitHub features
+GITHUB_TOKEN=ghp_...            # GitHub personal access token
+
+# Optional
+GITHUB_ORG_TOKEN=ghp_...        # For organization projects
+GITHUB_REPO_PATH=/path/to/repo  # For auto-detecting owner/repo
+DEFAULT_PROJECT_NUMBER=1         # Default project for issue assignment
+MCP_CORS_ORIGIN=*               # CORS origin (default: *)
+MCP_HOST=localhost               # Server bind host
+AUTO_REBUILD_INDEX=true          # Rebuild vector index on startup
+```
+
+## 🐳 **Docker Security**
+
+### **Non-Root User**
+
+- ✅ **Dedicated user**: `appuser` (UID 1001) with minimal privileges
+- ✅ **Restricted group**: `appgroup` (GID 1001)
+- ✅ **Restricted data directory**: `700` permissions
+
+### **Container Hardening**
+
+- ✅ **Minimal base image**: `node:24-alpine`
+- ✅ **Multi-stage build**: Build dependencies not in production image
+- ✅ **Process isolation** from host system
+- ✅ **No shell access needed** for production
+
+### **Volume Mounting Security**
+
+```bash
+# Secure volume mounting
+docker run -v ./data:/app/data:rw,noexec,nosuid,nodev memory-journal-mcp
+```
+
+### **Resource Limits**
+
+```bash
+# Apply resource limits
+docker run --memory=1g --cpus=1 memory-journal-mcp
+```
+
+## 🔍 **Data Privacy**
+
+### **Local-First Architecture**
+
+- ✅ **No external services**: All processing happens locally
+- ✅ **No telemetry**: No data sent to external servers
+- ✅ **Full data ownership**: SQLite database stays on your machine
+- ✅ **Semantic search**: ML model runs locally via `@xenova/transformers`
+
+### **Context Security**
+
+- ✅ **Git context**: Only reads local repository information
+- ✅ **No sensitive data**: Doesn't access private keys or credentials
+- ✅ **Optional GitHub integration**: Only if explicitly configured with token
+
+## 🔄 **CI/CD Security**
+
+- ✅ **CodeQL analysis** - automated static analysis on push/PR
+- ✅ **Trivy container scanning** - Docker image vulnerability detection
+- ✅ **TruffleHog + Gitleaks** - secret scanning on push/PR
+- ✅ **npm audit** - dependency vulnerability checking
+- ✅ **Dependabot** - automated dependency update PRs
+
+## 🚨 **Security Best Practices**
+
+### **For Users**
+
+1. **Set a CORS origin** when exposing the HTTP transport on a network
+2. **Keep Node.js updated**: Use Node.js 24+ (LTS)
+3. **Secure host system**: Ensure your host machine is secure
+4. **Regular backups**: Use the `backup_journal` tool or back up your `.db` file
+5. **Limit network access**: Don't expose the HTTP transport to untrusted networks
+6. **Use resource limits**: Apply Docker `--memory` and `--cpus` limits
+
+### **For Developers**
+
+1. **Regular updates**: Keep Node.js and npm dependencies updated
+2. **Security scanning**: Regularly scan Docker images for vulnerabilities
+3. **Code review**: All database operations use parameterized queries
+4. **Input validation**: All tool inputs validated via Zod schemas
+
+## 📋 **Security Checklist**
+
+- [x] WAL mode enabled for database consistency
+- [x] Proper file permissions (600/700)
+- [x] Input validation and length limits (Zod schemas)
+- [x] Parameterized SQL queries
+- [x] SQL injection detection heuristics
+- [x] Path traversal protection
+- [x] LIKE pattern sanitization
+- [x] Date format whitelisting
+- [x] HTTP body size limit (1MB)
+- [x] Configurable CORS origin
+- [x] Security headers (X-Content-Type-Options, X-Frame-Options)
+- [x] Session timeout (30 minutes)
+- [x] Non-root Docker user
+- [x] Multi-stage Docker build
+- [x] Local-first data architecture
+- [x] GitHub token error scrubbing
+- [x] CI/CD security pipeline (CodeQL, Trivy, secret scanning)
+- [x] Comprehensive security documentation
+
+## 🚨 **Reporting Security Issues**
+
+If you discover a security vulnerability, please:
+
+1. **Do not** open a public GitHub issue
+2. **Contact** the maintainers privately
+3. **Provide** detailed information about the vulnerability
+4. **Allow** time for the issue to be addressed before public disclosure
+
+## 🔄 **Security Updates**
+
+- **Container updates**: Rebuild Docker images when base images are updated
+- **Dependency updates**: Keep npm packages updated via `npm audit` and Dependabot
+- **Database maintenance**: Run `ANALYZE` and `PRAGMA optimize` regularly
+- **Security patches**: Apply host system security updates
+
+The Memory Journal MCP server is designed with **security-first principles** to protect your personal journal data while maintaining excellent performance and usability.

package/dist/cli.js

@@ -12,25 +12,31 @@ program
     .version(pkg.version)
     .option('--transport <type>', 'Transport type: stdio or http', 'stdio')
     .option('--port <number>', 'HTTP port (for http transport)', '3000')
+    .option('--server-host <host>', 'Server bind host for HTTP transport (default: localhost)')
     .option('--stateless', 'Use stateless HTTP mode (no session management)')
     .option('--db <path>', 'Database path', './memory_journal.db')
     .option('--tool-filter <filter>', 'Tool filter string (e.g., "starter", "core,search")')
     .option('--default-project <number>', 'Default GitHub Project number')
     .option('--auto-rebuild-index', 'Rebuild vector index on server startup')
+    .option('--cors-origin <origin>', 'CORS allowed origin for HTTP transport (default: *)')
     .option('--log-level <level>', 'Log level: debug, info, warning, error', 'info')
     .action(async (options) => {
     // Set log level
     logger.setLevel(options.logLevel);
+    // Resolve host: CLI flag > env var > default (localhost)
+    const host = options.serverHost ?? process.env['MCP_HOST'] ?? process.env['HOST'] ?? undefined;
     logger.info('Starting Memory Journal MCP Server', {
         module: 'CLI',
         transport: options.transport,
         stateless: options.stateless ?? false,
         db: options.db,
+        ...(host ? { host } : {}),
     });
     try {
         await createServer({
             transport: options.transport,
             port: parseInt(options.port, 10),
+            host,
             statelessHttp: options.stateless === true,
             dbPath: options.db,
             toolFilter: options.toolFilter,
@@ -40,6 +46,7 @@ program
                     ? parseInt(process.env['DEFAULT_PROJECT_NUMBER'], 10)
                     : undefined,
             autoRebuildIndex: options.autoRebuildIndex ?? process.env['AUTO_REBUILD_INDEX'] === 'true',
+            corsOrigin: options.corsOrigin,
         });
     }
     catch (error) {

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC1C,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AAEvD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAA;AAE7B,OAAO;KACF,IAAI,CAAC,oBAAoB,CAAC;KAC1B,WAAW,CAAC,wDAAwD,CAAC;KACrE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;KACpB,MAAM,CAAC,oBAAoB,EAAE,+BAA+B,EAAE,OAAO,CAAC;KACtE,MAAM,CAAC,iBAAiB,EAAE,gCAAgC,EAAE,MAAM,CAAC;KACnE,MAAM,CAAC,aAAa,EAAE,iDAAiD,CAAC;KACxE,MAAM,CAAC,aAAa,EAAE,eAAe,EAAE,qBAAqB,CAAC;KAC7D,MAAM,CAAC,wBAAwB,EAAE,qDAAqD,CAAC;KACvF,MAAM,CAAC,4BAA4B,EAAE,+BAA+B,CAAC;KACrE,MAAM,CAAC,sBAAsB,EAAE,wCAAwC,CAAC;KACxE,MAAM,CAAC,qBAAqB,EAAE,wCAAwC,EAAE,MAAM,CAAC;KAC/E,MAAM,CACH,KAAK,EAAE,OASN,EAAE,EAAE;IACD,gBAAgB;IAChB,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAkD,CAAC,CAAA;IAE3E,MAAM,CAAC,IAAI,CAAC,oCAAoC,EAAE;QAC9C,MAAM,EAAE,KAAK;QACb,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,KAAK;QACrC,EAAE,EAAE,OAAO,CAAC,EAAE;KACjB,CAAC,CAAA;IAEF,IAAI,CAAC;QACD,MAAM,YAAY,CAAC;YACf,SAAS,EAAE,OAAO,CAAC,SAA6B;YAChD,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;YAChC,aAAa,EAAE,OAAO,CAAC,SAAS,KAAK,IAAI;YACzC,MAAM,EAAE,OAAO,CAAC,EAAE;YAClB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,oBAAoB,EAAE,OAAO,CAAC,cAAc;gBACxC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;gBACtC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC;oBACrC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,EAAE,EAAE,CAAC;oBACrD,CAAC,CAAC,SAAS;YACjB,gBAAgB,EACZ,OAAO,CAAC,gBAAgB,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,KAAK,MAAM;SAC/E,CAAC,CAAA;IACN,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CAAC,wBAAwB,EAAE;YACnC,MAAM,EAAE,KAAK;YACb,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAChE,CAAC,CAAA;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACnB,CAAC;AACL,CAAC,CACJ,CAAA;AAEL,OAAO,CAAC,KAAK,EAAE,CAAA"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/constants/ServerInstructions.d.ts

@@ -4,7 +4,7 @@
  * These instructions are automatically sent to MCP clients during initialization,
  * providing guidance for AI agents on tool usage.
  *
- * v3.1.6: Optimized for token efficiency with tiered instruction levels.
+ * Unreleased: Optimized for token efficiency with tiered instruction levels.
  */
 /**
  * Resource definition for instruction generation

package/dist/constants/ServerInstructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ServerInstructions.d.ts","sourceRoot":"","sources":["../../src/constants/ServerInstructions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;CAClB;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,CAAA;AAuLhE;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAChC,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,EACzB,UAAU,EAAE,kBAAkB,EAAE,EAChC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,WAAW,CAAC,EAAE,mBAAmB,EACjC,KAAK,GAAE,gBAA6B,GACrC,MAAM,CAuCR;AAkBD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAA+C,CAAA"}
+{"version":3,"file":"ServerInstructions.d.ts","sourceRoot":"","sources":["../../src/constants/ServerInstructions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;CAClB;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,CAAA;AAmOhE;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAChC,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,EACzB,UAAU,EAAE,kBAAkB,EAAE,EAChC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,WAAW,CAAC,EAAE,mBAAmB,EACjC,KAAK,GAAE,gBAA6B,GACrC,MAAM,CAuCR;AAkBD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAA+C,CAAA"}

package/dist/constants/ServerInstructions.js

@@ -4,7 +4,7 @@
  * These instructions are automatically sent to MCP clients during initialization,
  * providing guidance for AI agents on tool usage.
  *
- * v3.1.6: Optimized for token efficiency with tiered instruction levels.
+ * Unreleased: Optimized for token efficiency with tiered instruction levels.
  */
 import { TOOL_GROUPS } from '../filtering/ToolFilter.js';
 /**
@@ -41,6 +41,7 @@ const GITHUB_INSTRUCTIONS = `
 - After closing issue/merging PR → create summary entry with learnings
 - CI failures → \`actions-failure-digest\` prompt or \`memory://actions/recent\`
 - Kanban: \`get_kanban_board(project_number)\` → \`move_kanban_item\` → document completion
+- Milestones: \`get_github_milestones\` → track project progress, \`memory://github/milestones\`
 - GitHub tools auto-detect owner/repo from git context; specify explicitly if null
 `;
 /**
@@ -81,10 +82,10 @@ const TOOL_PARAMETER_REFERENCE = `
 ### Entry Operations
 | Tool | Required Parameters | Optional Parameters |
 |------|---------------------|---------------------|
-| \`create_entry\` | \`content\` (string) | \`entry_type\`, \`tags\` (array), \`is_personal\` (bool) |
+| \`create_entry\` | \`content\` (string) | \`entry_type\`, \`tags\` (array), \`is_personal\`, \`significance_type\`, \`share_with_team\`, \`auto_context\`, \`issue_number\`, \`issue_url\`, \`pr_number\`, \`pr_url\`, \`pr_status\`, \`project_number\`, \`project_owner\`, \`workflow_run_id\`, \`workflow_name\`, \`workflow_status\` |
 | \`create_entry_minimal\` | \`content\` (string) | none |
-| \`get_entry_by_id\` | \`entry_id\` (number) | none |
-| \`get_recent_entries\` | none | \`limit\` (default 10), \`is_personal\` (bool) |
+| \`get_entry_by_id\` | \`entry_id\` (number) | \`include_relationships\` (bool, default true) |
+| \`get_recent_entries\` | none | \`limit\` (default 5), \`is_personal\` (bool) |
 | \`update_entry\` | \`entry_id\` (number) | \`content\`, \`tags\`, \`entry_type\`, \`is_personal\` |
 | \`delete_entry\` | \`entry_id\` (number) | \`permanent\` (bool, default false) |
 | \`list_tags\` | none | none |
@@ -92,33 +93,40 @@ const TOOL_PARAMETER_REFERENCE = `
 ### Search Tools
 | Tool | Required Parameters | Optional Parameters |
 |------|---------------------|---------------------|
-| \`search_entries\` | \`query\` (string) | \`limit\`, \`entry_type\`, \`tags\` |
-| \`search_by_date_range\` | \`start_date\`, \`end_date\` (YYYY-MM-DD) | \`tags\`, \`entry_type\` |
-| \`semantic_search\` | \`query\` (string) | \`limit\`, \`similarity_threshold\` (default 0.3) |
+| \`search_entries\` | none | \`query\`, \`limit\`, \`is_personal\`, \`issue_number\`, \`pr_number\`, \`pr_status\`, \`project_number\`, \`workflow_run_id\` |
+| \`search_by_date_range\` | \`start_date\`, \`end_date\` (YYYY-MM-DD) | \`tags\`, \`entry_type\`, \`is_personal\`, \`issue_number\`, \`pr_number\`, \`project_number\`, \`workflow_run_id\` |
+| \`semantic_search\` | \`query\` (string) | \`limit\`, \`similarity_threshold\` (default 0.25), \`is_personal\`, \`hint_on_empty\` (bool, default true) |
 | \`get_vector_index_stats\` | none | none |
 
 ### Relationship Tools
 | Tool | Required Parameters | Notes |
 |------|---------------------|-------|
-| \`link_entries\` | \`from_entry_id\`, \`to_entry_id\` (numbers) | Types: \`evolves_from\`, \`references\`, \`implements\`, \`clarifies\`, \`response_to\`, \`blocked_by\`, \`resolved\`, \`caused\` |
-| \`visualize_relationships\` | \`entry_id\` (number) | Optional \`depth\` (default 2). Returns Mermaid diagram. |
+| \`link_entries\` | \`from_entry_id\`, \`to_entry_id\` (numbers) | Types: \`evolves_from\`, \`references\`, \`implements\`, \`clarifies\`, \`response_to\`, \`blocked_by\`, \`resolved\`, \`caused\`. Optional \`description\`. |
+| \`visualize_relationships\` | none | Optional \`entry_id\`, \`tags\` (array), \`depth\` (1-3, default 2), \`limit\` (default 20). Returns Mermaid diagram. |
 
 ### GitHub Tools
 | Tool | Required Parameters | Notes |
 |------|---------------------|-------|
-| \`get_github_context\` | none | Returns repo info, open issues/PRs |
-| \`get_github_issues\` | none | Optional \`state\` (open/closed/all), \`limit\` |
-| \`get_github_prs\` | none | Optional \`state\`, \`limit\` |
-| \`get_github_issue\` | \`issue_number\` (number) | Fetches single issue details |
-| \`get_github_pr\` | \`pr_number\` (number) | Fetches single PR details |
+| \`get_github_context\` | none | Returns repo info, open issues/PRs. Only counts OPEN items. |
+| \`get_github_issues\` | none | Optional \`state\` (open/closed/all), \`limit\`, \`owner\`, \`repo\` |
+| \`get_github_prs\` | none | Optional \`state\`, \`limit\`, \`owner\`, \`repo\` |
+| \`get_github_issue\` | \`issue_number\` (number) | Optional \`owner\`, \`repo\`. Fetches single issue details. |
+| \`get_github_pr\` | \`pr_number\` (number) | Optional \`owner\`, \`repo\`. Fetches single PR details. |
+| \`get_repo_insights\` | none | Optional \`sections\` (stars/traffic/referrers/paths/all, default "stars"), \`owner\`, \`repo\`. Requires push access for traffic. |
 
 GitHub tools auto-detect owner/repo from GITHUB_REPO_PATH. If \`detectedOwner\`/\`detectedRepo\` are null in response, specify \`owner\` and \`repo\` parameters explicitly.
 
+### Issue Lifecycle Tools
+| Tool | Required Parameters | Notes |
+|------|---------------------|-------|
+| \`create_github_issue_with_entry\` | \`title\` (string) | Optional \`body\`, \`labels\` (array), \`assignees\` (array), \`project_number\`, \`initial_status\`, \`milestone_number\`, \`entry_content\`, \`tags\`, \`owner\`, \`repo\` |
+| \`close_github_issue_with_entry\` | \`issue_number\` (number) | Optional \`comment\`, \`resolution_notes\`, \`tags\`, \`move_to_done\` (bool), \`project_number\`, \`owner\`, \`repo\` |
+
 ### Kanban Tools (GitHub Projects v2)
 | Tool | Required Parameters | Notes |
 |------|---------------------|-------|
-| \`get_kanban_board\` | \`project_number\` (number) | Returns columns with items grouped by Status |
-| \`move_kanban_item\` | \`project_number\`, \`item_id\` (string), \`target_status\` (string) | \`item_id\` is the GraphQL node ID from board items |
+| \`get_kanban_board\` | \`project_number\` (number) | Optional \`owner\`. Returns columns with items grouped by Status |
+| \`move_kanban_item\` | \`project_number\`, \`item_id\` (string), \`target_status\` (string) | Optional \`owner\`. \`item_id\` is the GraphQL node ID from board items. Status matching is case-insensitive. |
 
 **Finding the right project**: User may have multiple projects. Use \`get_kanban_board\` with different project numbers (1, 2, 3...) to find the correct one by checking \`projectTitle\`.
 
@@ -135,33 +143,53 @@ Kanban resources:
 - \`memory://kanban/{project_number}\` - JSON board data
 - \`memory://kanban/{project_number}/diagram\` - Mermaid visualization
 
+### Milestone Tools
+| Tool | Required Parameters | Notes |
+|------|---------------------|-------|
+| \`get_github_milestones\` | none | Optional \`state\` (open/closed/all), \`limit\`, \`owner\`, \`repo\` |
+| \`get_github_milestone\` | \`milestone_number\` (number) | Optional \`owner\`, \`repo\`. Single milestone with completion %. |
+| \`create_github_milestone\` | \`title\` (string) | Optional \`description\`, \`due_on\` (YYYY-MM-DD), \`owner\`, \`repo\` |
+| \`update_github_milestone\` | \`milestone_number\` (number) | Optional \`title\`, \`description\`, \`due_on\`, \`state\` (open/closed), \`owner\`, \`repo\` |
+| \`delete_github_milestone\` | \`milestone_number\`, \`confirm: true\` | Optional \`owner\`, \`repo\`. Permanent deletion. |
+
+Milestone resources:
+- \`memory://github/milestones\` - Open milestones with completion %
+- \`memory://milestones/{number}\` - Single milestone detail
+
 ### Admin Tools
 | Tool | Required Parameters | Notes |
 |------|---------------------|-------|
-| \`backup_journal\` | none | Optional \`backup_name\` |
+| \`backup_journal\` | none | Optional \`name\` (custom backup name) |
 | \`list_backups\` | none | Returns available backup files |
-| \`restore_backup\` | \`backup_filename\`, \`confirm: true\` | Creates auto-backup before restore |
+| \`cleanup_backups\` | none | Optional \`keep_count\` (default 5). Deletes old backups, keeps N most recent. |
+| \`restore_backup\` | \`filename\`, \`confirm: true\` | Creates auto-backup before restore |
 | \`add_to_vector_index\` | \`entry_id\` (single number) | Indexes one entry for semantic search |
 | \`rebuild_vector_index\` | none | Re-indexes all entries |
 
 ### Export Tools
 | Tool | Required Parameters | Notes |
 |------|---------------------|-------|
-| \`export_entries\` | none | Optional \`format\` (json/markdown), \`limit\`, \`tags\` |
+| \`export_entries\` | none | Optional \`format\` (json/markdown), \`limit\` (default 100), \`tags\`, \`start_date\`, \`end_date\`, \`entry_types\` |
 
 ## Entry Types
 Valid values for \`entry_type\` parameter:
 - \`personal_reflection\` (default) - Personal thoughts and notes
-- \`technical_note\` - Technical documentation
+- \`project_decision\` - Architectural and team decisions
+- \`technical_achievement\` - Milestones and breakthroughs
 - \`bug_fix\` - Bug fixes and resolutions
-- \`progress_update\` - Project progress updates
+- \`feature_implementation\` - Feature builds and rollouts
 - \`code_review\` - Code review notes
-- \`deployment\` - Deployment records
-- \`technical_achievement\` - Milestones and breakthroughs
+- \`meeting_notes\` - Meeting summaries
+- \`learning\` - Learning and research insights
+- \`research\` - Research and exploration
+- \`planning\` - Planning sessions and roadmaps (\`create_github_issue_with_entry\` uses this type)
+- \`retrospective\` - Sprint and project retrospectives
+- \`standup\` - Daily standup notes
+- \`other\` - Miscellaneous
 
 ## Field Notes
 - **\`autoContext\`**: Reserved for future automatic context capture. Currently always \`null\`.
-- **\`memory://tags\` vs \`list_tags\`**: Resource includes \`id\`, \`name\`, \`count\`; tool returns only \`name\`, \`count\`.
+- **\`memory://tags\` vs \`list_tags\`**: Resource includes \`id\`, \`name\`, \`count\`; tool returns only \`name\`, \`count\`. Neither returns orphan tags with zero usage.
 - **Tag naming**: Use lowercase with dashes (e.g., \`bug-fix\`, \`phase-2\`). Use \`merge_tags\` to consolidate duplicates (e.g., merge \`phase2\` into \`phase-2\`).
 - **\`merge_tags\` behavior**: Only updates non-deleted entries. Deleted entries retain their original tags.
 - **\`prStatus\` in entries**: Reflects PR state at entry creation time, not current state. Use \`get_github_pr\` for live status.
@@ -170,19 +198,35 @@ Valid values for \`entry_type\` parameter:
 - **\`semantic_search\` thresholds**: Default similarity threshold is 0.25. For broader matches, try 0.15-0.2. Higher values (0.4+) return only very close semantic matches.
 - **Causal relationship types**: Use \`blocked_by\` (A was blocked by B), \`resolved\` (A resolved B), \`caused\` (A caused B) for decision tracing and failure analysis. Visualizations use distinct arrow styles for causal types.
 - **Enhanced analytics**: \`get_statistics\` returns \`decisionDensity\` (significant entries per period), \`relationshipComplexity\` (avg relationships per entry), \`activityTrend\` (period-over-period growth %), and \`causalMetrics\` (counts for blocked_by/resolved/caused).
-- **Importance scores**: \`get_entry_by_id\` returns an \`importance\` score (0.0-1.0) based on: significance type (30%), relationship count (35%), causal relationships (20%), and recency (15%). \`memory://significant\` sorts entries by importance.
+- **Importance scores**: \`get_entry_by_id\` returns \`importance\` (0.0-1.0) and \`importanceBreakdown\` showing weighted components: significance (30%), relationships (35%), causal (20%), recency (15%). \`memory://significant\` sorts entries by importance.
+- **\`inactiveThresholdDays\`**: \`get_cross_project_insights\` includes \`inactiveThresholdDays: 7\` in output, documenting the inactive project classification cutoff.
+- **GitHub metadata in entries**: Entry output includes 10 GitHub fields (\`issueNumber\`, \`issueUrl\`, \`prNumber\`, \`prUrl\`, \`prStatus\`, \`projectNumber\`, \`projectOwner\`, \`workflowRunId\`, \`workflowName\`, \`workflowStatus\`) in all tool responses.
+- **\`delete_entry\` on soft-deleted**: \`delete_entry(id, permanent: true)\` works on previously soft-deleted entries. Returns \`success: false\` for nonexistent entries.
 
 ## Key Resources
 | URI | Description |
 |-----|-------------|
 | \`memory://health\` | Server health, DB stats, tool filter status |
 | \`memory://briefing\` | Session context with userMessage to show user |
+| \`memory://instructions\` | Full server instructions and tool reference |
 | \`memory://statistics\` | Entry counts by type and period |
 | \`memory://recent\` | 10 most recent entries |
 | \`memory://tags\` | All tags with usage counts |
-| \`memory://significant\` | Entries marked as milestones/breakthroughs |
+| \`memory://significant\` | Entries sorted by importance score |
 | \`memory://graph/recent\` | Mermaid diagram of recent relationships |
+| \`memory://graph/actions\` | CI/CD narrative graph |
+| \`memory://actions/recent\` | Recent workflow runs |
+| \`memory://team/recent\` | Team-shared entries |
+| \`memory://github/status\` | GitHub repo overview (CI, issues, PRs, milestones) |
+| \`memory://github/milestones\` | Open milestones with completion % |
+| \`memory://github/insights\` | Stars, forks, and 14-day traffic summary |
 | \`memory://kanban/{n}\` | Kanban board for project number n |
+| \`memory://kanban/{n}/diagram\` | Mermaid Kanban visualization |
+| \`memory://milestones/{n}\` | Single milestone detail + progress |
+| \`memory://projects/{n}/timeline\` | Project entries timeline |
+| \`memory://issues/{n}/entries\` | Entries linked to issue n |
+| \`memory://prs/{n}/entries\` | Entries linked to PR n |
+| \`memory://prs/{n}/timeline\` | PR lifecycle and linked entries |
 `;
 /**
  * Generate dynamic instructions based on enabled tools, resources, prompts, and latest entry